[PREVIOUS] [NEXT] [UP]

Encapsulation

In this chapter you will learn how to extend the set of predefined NST units by encapsulating existing units or newly built circuits in a suitable user interface.


In the previous chapter we saw how to to equip a visual program with a dialog window for setting a user-specified set of global variables that parametrize the program and allow its easy re-configuration.

Local variables

Consider the example unit labelled my_rnd. It implements a random generator with a built-in visualization window. Each call of the container unit generates a new vector of 1000 normally distributed xy-coordinate pairs at its output and displays the points in the window my_rnd. While the implementation of my_rnd as a subcircuit inside a container allows us to access and change all essential properties of the unit, this is not as convenient as in the case of a pre-defined NST unit, where all such changes are centralized in its creation window.

Therefore, Neo allows for each container that encapsulates a subcircuit to replace its standard creation dialog window by a new one with entry slots for a set of variables that then become available as local variables @0, @1, ... inside the container to parametrize its subunits. In this way, parameters scattered over many subunits in a subcircuit can be made accessible in a centralized creation dialog window that replaces the standard creation dialog window.

How to specify a user interface for a container

The necessary steps are similar to the definition of global variables for an entire circuit, the only major difference is that the defined local variables are referenced by tokens @0, @1, and so on, and their visibility is restricted to the subcircuit inside the container (unlike global variables, the visibility of local variables also does not extend into any deeper nested subcircuits that may occur inside the subunits of the subcircuit).

To replace the standard creation window of my_rnd with a user-defined one, first open my_rnd to display its subcircuit in the circuit window. Then select the "Define" command and proceed as if you would define a dialog window for global variables. E.g., enter something like

title        : %40t %n
width        : %230i %n
height       : %200i %n
nr of points : %1000i %n
variance     : %1f %n

Accept with "OK". You now have defined five local variables @0 (a text string, currently empty), @1, @2, @3 (three integers, initialized to 230, 200 and 1000 resp.), and @4 (a float value, initialized to 1.0).

You can now use the newly defined local variables to replace the values in the corresponding places of the creation and parameter windows of the subunits that make up my_rnd (@0,@1 and @2 will go into the creation window of the plot_xy unit, @3 will go [prefixed by a minus sign to make a float vector output!] into the creation window of rnd_gen, and @4 into its parameter window; note again that we have initialized the variables such that they match the current values that the variables shall replace).

When you now return to the next-outer circuit level (right mouse button), you will see that the former 'o' symbol of the my_rnd-unit (which was a container) has changed into a red 'm' to indicate that my_rnd now offers a user-defined variable window for making modifications to the subcircuit. Click at it to see that your newly defined interface window comes up and allows you to change the properties of the my_rnd unit by just specifying new parameter values to the entries.

As a result, the my_rnd unit now looks pretty much as if it were a predefined NST unit. The only difference is, that its internal "machinery" is not compiled code, but a NST subcircuit that you can inspect and edit graphically. Moreover, you can easily change (e.g., extend by new parameters) the creation window of my_rnd (following steps that are entirely analogous as explained for the case of global variables).

How to remove a user interface of a container

If you wish to give the container back its old, standard creation dialog window, you just need to change the user-defined dialog window to the empty string. This will remove all variables and bring the old, standard creation dialog window (and the 'o' symbol) back.

How to redefine the creation dialog window for a pre-defined unit

The above mechanism can also be used to replace the creation dialog window of a predefined unit with a new one that may be customized for a particular purpose. As an example#2, we make a customized variant of the input_window unit that offers a mxn matrix of little buttons to enter a binary matrix. For, say, m=10, n=12, the necessary input_window widget code would be something like

%10:12{%0:1:0:2b%| %n %} %n %R

The %m:n{String1%|String2%} is a useful shorthand notation for specifying repetitions. It is interpreted by the input_window unit as the string obtained from m repetitions of a "row" that consists of n copies of String1, followed by a single copy of String2.

In the present case, String1 is %0:1:0:2b, i.e., a 2-char wide binary button, and String2 is a linefeed (and some space) that completes each row (there are m of them) of n buttons. The "%n %R" makes a final OK button.

We now want to hide all these details from the user and to replace the standard creation dialog window of the input_window with with a simpler version that is customized for the present case and that just offers two input slots for the values of m and n.

To achieve this, bring up the input_window creation dialog window and follow these steps:

1. Press the right mouse button. In addition to the already open input_window creation dialog, a second dialog window will pop up and take over the input focus. It is the already familiar dialog for specifying the layout of an input window for variables.

2. Specify a suitable input window for querying the two variables row number m and column number n. E.g., enter

nr of rows: %10i %n
   of cols: %12i %n

and continue with "OK". The dialog window will disappear and input focus is back in the still open creation dialog window of the input_window for the button matrix. You now have just defined two new local variables @0 and @1 (with initial values 10 and 10) that are visible for all entry slots of the standard dialog windows of the current unit (the input_window unit).

3. Now use the newly defined variables @0 and @1 to replace the "10" and "12" in the button matrix specification. Then leave the creation and the subsequent parameter dialog with "OK".

You are now back at the circuit level. The created input_window instance will have now a red 'm', indicating that its standard creation window has been replaced. Click at the 'm' and you will see that now indeed only the newly defined variable window pops up and allows you to remake the unit with new row and column numbers.

How to access a replaced dialog window for changes

The standard creation window of the unit, however, still exists "underneath". You can open it (e.g., to make changes) by pressing the right mouse button after you have brought up the new variable window with 'm' and positioned the mouse pointer inside it. When the standard creation window is open, you also can switch to the definition dialog of the variable window by pressing the right mouse button again. If you replace the definition by the empty string, the variable window will disappear and the standard dialog window will come back (all variables will have been replaced by their latest values in this case).

Loadable units

Variables and user-defined interface windows allow you to derive new NST units from pre-defined units (such as the prog_unit) or from interactively constructed circuits that have been encapsulated as subcircuits in a container. To distinguish such units from pre-defined compiled units, they are called "loadable units".

[PREVIOUS] [NEXT] [UP]