Getting User Input Getting User Input

On can use the &GET string function to simply get a response from the user, but for many situations this leads to a boring, modal dialogs. A more flexible method is using &STRING macros and WIZARDS. A wizard is a set of commands which are defined inside a &STRING macro and A &STRING macro is the same as an ordinary macro except that it can contain only internal commands, and it can be executed only with an &E_STRING command. Let us look at an example, suppose that one wanted to have a command which prompts for the units to use. This can be accomplished with

     &STRING D2M
     &DIMEN -DIMEN &GET(PICK 1 'PICK UNITS'    \
     'Feet,Kips    ' \
     'Feet,S-tons  ' \
     'Feet,L-tons  ' \
     'Meters,Tonnes' \
     'Meters,KN    ' )
     END
     &ENDSTRING
     &E_STRING D2M

Notice that there is an "END" command at the bottom of the definition of the &STRING macro D2M. This command signals the end of the execution of the macro. At first glance this looks like a concept which is of no value of all, but this is not true. First, as we will see later, &STRING macros can be associated with buttons on the menu bar. Also, WIZARDS must be defined with a &STRING macro. For example, the above could be accomplished with a WIZARD as:

     &STRING D2M
     WIZARD Dimensions -COMMAND  &DIMENSION -SIZE 450 410
     TAB_ADD To Use
     WIDGET_ADD YES-NO -REMEMBER "Remember Previous"
     WIDGET_ADD YES-NO -SAVE     "Save Current"
     WIDGET_ADD RADIO  -DIMEN    "Settings"         \
     "Feet, Kips     "  \
     "Feet, L-tons   "  \
     "Feet, S-tons   "  \
     "Meters, Tonnes "  \
     "Meters, KN     "
     END
     &ENDSTRING
     &E_STRING D2M

Basically what happens here is the the wizard will build a command from the user's actions. The beginning of the command will be &DIMENSION and this is defined with the -COMMAND option. This wizard has one tab labeled "To Use" (all wizards must have a tab) and three things one can choose: two check boxes and one pick from a set of "radio buttons". A WIDGET command defines a single widget which will be placed in the tab and the first token after WIDGET defines the type of widget. The second token defines a prefix which will be added before the main data selected by the widget. The fourth token is a title The YES-NO widgets select whether of not the prefix is added to the command and the RADIO widget will add on of the prefix -DIMEN and the text selected.

Now, let's be more precise. The command


     WIZARD Main Title -OPTIONS

instructs MOSES to enter the Wizard Menu and the options available here are:

     -COMMAND, First Part of Command
     -SIZE, SHOR, SVER, NCOL
     -BUTTON_TEXT, Text On Button

Here, the -COMMAND option was discussed above, and the -SIZE allows the user to specify the horizontal and vertical size of the wizard window in pixels, and the number of columns. Every wizard has a button that the user must push to exit the wizard and execute the command. The -BUTTON_TEXT option defines the text on the button. If this option is omitted, "OK" will be used.

As mentioned above, every wizard must have at least on tab, and it can have many of them. Each one is defined with the command


     TAB_ADD, STRING

where "STRING" defines the text which will be painted on the top of the tab. Once a tab has been defined, all text and widgets defined will be added to the tab until a new TAB_ADD command is issued. The command


     TEXT_ADD, TEXT

will simply add the text "TEXT" to the current tab and the current location.


     WIDGET_ADD, WIDGET_TYPE, W_PREFIX, W_DESC, W_LIST, -OPTIONS

and the available options are

     -INITIALIZE, W_INITIAL_VALUE
     -SUFFIX, W_SUFFIX
     -L_DESCRIPTION, L_DESCRIPTION
     -ACTIVATE, KEY_TO

Here, WIDGET_TYPE defines the type of widget which will be created and it must be chosen from either YES-NO, BOX, RADIO, SEL_ONE, or SEL_MULTIPLE. The YES-NO widget has a check box. If it is checked, then the prefix will be emitted, if it is not checked, then the prefix will not be emitted. The BOX widget has an input box in which the user can put input. If he enters data, then it and the prefix will be omitted. The RADIO widget has a list with a circle. If one clicks on the circle, the the text shown will be emitted with the prefix. Only a single value can be selected. The SEL_ONE and SEL_MULTIPLE widgets are drop down selection boxed. Only a single item can be selected with a SEL_ONE widget, but multiple ones can be selected with SEL_MULTIPLE. W_PREFIX defines the prefix which will be emitted when the user selects the widget. It can be blank. W_DESC is the brief text which will be placed to the left of the selection part of the widget, and W_LIST is a list of things which can be selected. The text defined here is what will be emitted after the prefix. The order in which widget results are emitted is the order in which they were input. Thus, if you use things without a prefix, they probably should be defined first.

The -INITIALIZE and -SUFFIX options defines initial values and suffixes for the widget. If an initial value is specified, then this will be the value displayed in the box as if the user input it. A suffix will not normally be needed, but if it is specified, then what is emitted by this widget will be the concatenation of the prefix, the value, and the suffix.

Ideally the words in the list should suffice to tell the user what he is selecting. Sometime this is not the case and you need to add a -L_DESCRIPTION option which defines a "long description. This description is written in a pop up window when on "mouses over" the description.

The -ACTIVATE option is complicated. When this option is used, the widget is initially hidden. Here KEY_TO is an option on the previous widget and when the previous widget selects KEY_TO, the hidden widget is shown giving choices which only make sense for the chosen value. For example:

     WIDGET BOX -DEFLECTION "Show Deflected Shape"  YES NO
     WIDGET BOX -DEFLECTION "Deflection Multiplier" -ACTIVATE YES

Here, the second widget is hidden unless YES is selected by the first one.