Tutorial 5: Iterators
What is an Iterator? An iterator is an object that creates other objects. Say, for example, that you wish to create a row of buttons for programs in a directory (perhaps programs in SYS:Prefs). Although object cloning makes it easy to create all these buttons by hand, you would have to edit each individually to change the name, and when you added new programs to SYS:Prefs, you would have to add new buttons.

There's an easier way using iterators. An iterator lets you define your button object once, and then it copies this object for each program in a directory (or open screen on your system, and so on depending on the iterator object itself). Think of it is a cookie-cutter that stamps out similar objects.
Variables If an iterator just copies a single object repeatedly, what good is that? Certain parameters of the objects being copied can be changed using variables. Variables have many uses outside of iterators, but this is one use. You have actually seen variables once before, when we created our Screenview object.

A variable is used in a text value. Any text of the form ${varname} is replaced by the contents of the named variable. There are several ways a variable can find its value. There is a global list of variables that applies everywhere. These variables can be seen by any object. This global list can be edited from the main editor window.

Also, each object can potentially export a set of variables to its children. In the example we saw earlier, we used the variable ${ScreenName} in a text object. This variable was set for us by the Screenswitch object to the name of the public screen in that object. This means that if we change the screen name in the screenswitch object, all the objects underneath that use the ${ScreenName} variable will automatically change as well.

An iterator can export a different value of the same variable to each of its children. For example, suppose we create an iterator object that makes a button for each file in a directory. The variable ${DIFile} is set to the basename of the file, individually for each button. This will be easy to understand once you see an example.
An Example Iterator Load the project named Project.Tutorial_5. This tutorial contains two sample iterators, and a simple window that with buttons that can pop up their windows. One iterator creates a set of buttons corresponding to files in DEVS:DOSDrivers. When one of the buttons is pressed, multiview is called to display that file, and the button window is closed. This window will open at the top of your screen, and will look something like the one shown here. In this example, you can see that the buttons reference the variable ${DIFile}, which is set to each value found in DEVS:DOSDrivers in turn (FTP, TERM0, DUART0, and so on).

The other iterator creates a row of buttons at the very bottom of the screen, one per screen. Clicking on one of these buttons will bring the corresponding screen to the front.

The mechanics of making these objects won't be explained in this tutorial; by now, you should be able to browse through the associated objects and figure out what is being done. There is extensive MUI bubble-help available for all of the editor windows. The reference section explains more about the features and objects available.
Variable Lookup & Recursion When a variable is found in a text string, first, the object containing that variable is checked for a definition, and that one is used if found. If there is none there, and the object is a child of some other object (such as a Layout group), then the parent object is checked, and so on. If no definition is found by the top object in the window, then the global list of variables is checked.

Variable definitions are resolved until no more resolution is possible. For example, consider a Screenswitch object that exports a variable ${ScreenName}, and a text object as a child that uses ${ScreenName}. Now consider that the actual screen name in the Screenswitch object is set to another variable from the main variable list, ${MyScreen1}. The process for the text object's variable search is:

  • Resolve ${Screenswitch}. The value for this is ${MyScreen1}, i.e., another variable.
  • Resolve ${MyScreen1}, which turns into a real screen name.
This process can go on until a fixed maximum recursion depth is reached (10 levels). Several other types of variable recursion are supported; these are discussed in the reference section.