fsc2: 5.3 Interaction functions

5.3 Interaction functions

The following functions are for creating, handling and deleting of buttons, sliders and input and output fields. When such an object is created for the first time a new window with the title "Toolbox" gets created. The objects (i.e. buttons, sliders and input and output fields) displayed in this toolbox window allow the user to influence the experiment when it is already running. The toolbox window will vanish automatically when all objects have been deleted. The toolbox with its objects can only be used during the experiment, i.e. the functions for creating, handling and deleting of objects can only be used within the EXPERIMENT section of the script.

There are two possible layouts for the toolbox, either all elements laid out vertically (the default) or all side by side horizontally. If that many objects are created that the toolbox wouldn't fit onto the screen anymore in vertical layout mode a new column is started automatically while in horizontal mode a new row. When exactly this happens depends (obviously) on the size of the screen, but also on details of the lengths of labels or the font used for labels.

Please note that when the objects in the toolbox are used it usually isn't possible anymore to check the complete experiment before it is run because it is impossible to foresee which buttons, sliders or input fields are going to be used at what moment in time (the only exception is when only output fields are used). Therefore, these functions should only be used where it is really necessary, e.g. when you're trying to find the optimum parameters for an experiment but not in the final experiment.

When the script is tested before the experiment is started it is assumed that all buttons are not pressed and switched off (unless their state has been set explicitly by the function button_state(), all sliders are assumed to be in the middle position unless a different value has been set via the function slider_value() and all input and output fields are initialized to 0 unless an initial value has been passed to the functions input_create() or output_create().

For all the objects to be created a label string to be drawn with the object can be defined. Normally this will be a simple text, indicating the meaning of the object. But in some cases it might be useful also to be able to draw some symbols instead of text. This can be done by starting the label string by the '@' character. Immediately after the '@' one of the following texts can be used to draw a symbol:

`->': Normal arrow pointing to the right.
`<-': Normal arrow pointing to the left.
`>': Triangular arrow pointing to the right.
`<': Triangular arrow pointing to the left.
`>>': Double triangle pointing to the right.
`<<': Double triangle pointing to the left.
`<->': Arrow pointing left and right.
`->|': Normal arrow pointing to the right and ending in a vertical bar.
`>|': Triangular arrow pointing to the right and ending in a vertical bar.
`|>': Triangular arrow pointing to the right and starting in a vertical bar.
`-->': Thin arrow pointing to the right.
`=': Three embossed lines.
`arrow': Same as -->.
`returnarrow': <Return> key symbol.
`square': Square.
`circle': Circle.
`line': Horizontal line.
`plus': Plus sign (rotate to get a cross).
`UpLine': Embossed vertical line.
`DnLine': Engraved vertical line.
`UpArrow': Embossed triangular arrow pointing to the right.
`DnArrow': Engraved triangular arrow pointing to the right.

It is also possible to rotate most of the symbols. When a symbol name is preceded by a digit between 1 and 9 (except 5) the symbol is rotated like on the numerical keypad, i.e. 6 indicates no rotation, 9 a rotation by 45 degrees anti-clockwise,8 a rotation by 90 degrees, etc. Hence the order is 6,9,8,7,4,1,2,3 (just think of the keypad as consisting of arrow keys). So to get an arrow pointing to the left top use a label string of "@7->". To rotate the symbols in other directions not fitting into this 45 degrees scheme put a 0 directly after the '@', followed by exactly three digits that indicate the angle (counter-clockwise). E.g. to get an arrow at an angle of 30 degrees use the label string "@0030->".

The symbols are designed for labels with a square bounding box. But in most cases the labels bounding box will not be square and the symbol is scaled differently in x- and y-direction. If keeping the aspect ration is desired, put a '#' character immediately after the '@', e.g. "@#9->".

Two additional prefixes, '+' and '-', followed by a single digit, can be used to make small size adjustments. These prefixes must either follow immediately after the '@' or the '#'. The '+' indicates an increase of the symbol size while '-' will decrease the size. The digit following the prefix indicates the increment or decrement in pixels. For example, to draw a circle that is 3 pixels smaller than the default size use the label string "@-3circle".

List of all interaction functions:

`layout()'
`toolbox_changed()'
`toolbox_wait()'
`button_create()'
`button_delete()'
`button_state()'
`button_changed()'
`slider_create()'
`slider_delete()'
`slider_value()'
`slider_changed()'
`input_create()'
`input_delete()'
`input_value()'
`input_changed()'
`output_create()'
`output_delete()'
`output_value()'
`menu_create()'
`menu_add()'
`menu_text()'
`menu_delete()'
`menu_choice()'
`menu_changed()'
`object_delete()'
`object_change_label()'
`object_enable()'
`hide_toolbox()'

Descriptions of interaction functions:

All the following functions can only be used in the EXPERIMENT section of an EDL script.

`layout()'

The functions tells the program how to layout the buttons and sliders in the window, either vertically or horizontally. The function must be called either with the strings "VERT", "VERTICAL", "HORI" or "HORIZONTAL" (the case of the letters doesn't matter). The numbers 0 and 1 can be used alternatively for vertical or horizontal layout.

Of course this function has to be called before a function to create an object (button, slider or in- or output field) has been invoked.

`toolbox_changed()'

This function lets you test if the state of one of the objects in the toolbox has been changed by the user, i.e. if a button has been pressed, a slider has been moved, an input field has been edited or the selected entry of a menu has been changed. You can pass this function a list of object IDs, in which case only the objects in the list are checked. When no argument is passed to the function all objects (except output fields) are checked. If the state of one or more objects has been changed the function returns the ID of the first object (in the list or of all objects in the toolbox) that has been changed. If none have been changed 0 is returned.

Please note: the function will not report changes due to function calls that change the state of an object, e.g. when setting a new slider position from within the EDL script. The function also will report a change until the new state of the object has been determined by an appropriate function call. I.e. it will keep reporting e.g. a new slider value until you have called slider_value() for the object.

`toolbox_wait()'

This function is very similar to the previous function, toolbox_changed(). The main difference is that it will wait for a certain time and only returns when either this time has expired or an objects state has changed. Thus it needs one additional argument: the first argument must be the maximum time the function will block if none of the objects were changed. This first argument may be followed of a list of objects to check. The function also returns the ID of the first changed object or 0 if the time expired and no objects were changed during the time interval.

If you want to wait indefinitely you may pass the function a value of 0 or a negative value. If you pass no arguments at all to the function it will block until one of the objects in the toolbox has been changed by the user.

`button_create()'

The function creates a new button and returns a unique integer number that has to be used in later calls to identify this button. There are three types of buttons, normal buttons that can be just pressed to create an event, push buttons that stay on or off, and finally radio buttons, that are also some kind of push buttons but that belong to a group of buttons of which only one button can be switched on at once, i.e. if a radio button gets pressed all the other radio buttons belonging to the same group (which has to be specified when the button is created) become automatically unset.

Normal buttons are drawn as large rectangular boxes with the label in the middle, push buttons are drawn as squares, standing on a corner, that become yellow when pressed, and radio buttons as round buttons, that become red when activated.

The first argument the function expects is the type of the button, i.e. one of the strings "NORMAL_BUTTON", "PUSH_BUTTON" or "RADIO_BUTTON" (the case of the letters doesn't matter).

For a radio button it must be specified which group it belongs to. Each group has a button functioning as the group leader which is always the first button of the group. For all other members of this group the identifier of the group leader button must be specified as the second argument. I.e. to create a group of three radio buttons use

B_ID_1 = button_create( "RADIO_BUTTON", "Label 1" );
B_ID_2 = button_create( "RADIO_BUTTON", B_ID_1, "Label 2" );
B_ID_3 = button_create( "RADIO_BUTTON", B_ID_1, "Label 3" );

For all buttons except radio buttons the second (optional) argument is the string that is to appear as the label of the button. The final (also optional) argument is another string that is the help text that will appear when the mouse hoovers over the button for some time. Both label and help text may contain two different escape sequences, namely `\n', standing for a line break (to create a multi-line label or help text) and `\\', standing for the backslash character to allow a backslash in front of an `n'.

All buttons start in the deactivated state except the 'leader' of a group of radio buttons.

`button_delete()'

Using this function one or more buttons can be deleted. It expects one or a list of button identifiers (separated by commas) as returned by the function button_create().

If the group leader (i.e. the first button) of a group of radio buttons is deleted, the next button of the group becomes the new group leader automatically. Please also note that when deleting the radio button that is currently active, none of the radio buttons will be active. In this case it is your responsibility to switch on one of the remaining radio buttons of the group (unless all the others are also deleted immediately after-wards).

`button_state()'

This function returns or sets the state of a button, depending on the number of arguments passed to the function. The non-optional first argument is the identifier of the button as it was returned by the function button_create(). If there are no more arguments the state of the button is returned. There is a difference between the values returned for normal buttons on the one side and push and radio buttons on the other. For normal buttons a counter is maintained that counts the number of times the button was pressed and its value is returned and the counter is set back to zero at the same time. In contrast, for push and radio buttons the state of the button, i.e. either 0, meaning off, or 1 for on is returned.

If for push and radio buttons there is a second argument the state of the button will be be set. This argument must be either a string ("ON" or "OFF") or a number with 0 standing for off and a non-zero number for on. If the radio button is currently active and it is about to be switched off, an error message will be printed and the button will remain active. To switch an active radio button off activate another button from its group instead. The state of normal buttons cannot be set.

`button_changed()'

The function takes one argument, the ID of a button. It will return 1 if the button has been activated and 0 if the state of the button hasn't been changed. Please note that the function will repeatedly report a change of the button state until you have determined the new state of the button by calling button_state() for the button.

For radio buttons, the function will only report a change for a newly activated button, but none for a button that automatically got switched off, i.e. only for the button that has become active from a group of radio buttons.

`slider_create()'

Sliders are useful for setting values within a predefined range. There are two types of sliders, normal sliders and value sliders. The difference between these types is that for value sliders there is an additional field showing the currently set value while for normal sliders there isn't such a visual feedback. As already the function button_create() also this function returns a unique integer number to be used to identify the slider.

The first argument the function expects is a string, either "NORMAL_SLIDER", "VALUE_SLIDER", "SLOW_NORMAL_SLIDER" or "SLOW_VALUE_SLIDER" (the keywords are case-insensitive). NORMAL sliders are just sliders without any decoration while VALUE sliders have an extra field showing the current value set via the slider. Normally, a slider reports a new value whenever the slider has been moved. In contrast, SLOW sliders only acquire a new value when also the mouse button (which has to be kept pressed down while the slider is moved) has been released.

The second argument must be the minimum value the slider can be adjusted to and the third argument is the maximum value. The minimum value must always be smaller than the maximum value.

A fourth, optional parameter is the step size to be used, i.e. the minimum increment the slider value can be changed. Of course, this value has to be larger than zero and smaller than the difference between the minimum and maximum value of the slider.

As in the case of buttons there are two more (optional) arguments, the label to be shown below the slider and a help text. The same escape sequences as for button labels and help texts.

All sliders start of set to the middle of their range. If a step size is given for the slider the allowed value nearest to the middle value is used as the sliders initial value.

`slider_delete()'

The function deletes one or more sliders. It expects one or a list of slider identifiers as returned by the function slider_create().

`slider_value()'

This function returns or sets the value of a slider. The first argument must be a slider identifier as returned by the function slider_create(). If this is the only argument the value the slider is currently set to is returned. If there's a second value the slider is set to this value. Obviously, the value must be within the range of the slider as defined by the minimum and maximum value set in slider_create(), otherwise an error message is printed and the slider value is set to the next value still within the allowed range. If a step size is set for the slider and the new value does not fit with the step size the nearest allowed value is set.

`slider_changed()'

The function takes one argument, the ID of a slider. It will return 1 if the value of the slider has been changed by the user and 0 if not. Please note that the function will repeatedly report a change of the sliders value until you have determined the new value by calling slider_value() for the slider.

`input_create()'

Using input fields numerical values can be entered. There are two different types of input fields, one, that will only accept integer values, while the other also allows input of floating point numbers. The first argument of the function for creating an input field, input_create(), is the type of the input field. If the first argument is "INT_INPUT" the input field will only accept integer numbers, while with an argument of "FLOAT_INPUT" also floating point numbers can be entered.

If the second argument is a number it is taken to be the initial value in the input field. If there is either no second argument or the second argument is not a number but a string, the input field will be initialized to 0.

As in the case of buttons and sliders there are two more (optional) arguments, the label to be shown below the input field and a help text. The same escape sequences as for button and slider labels and help texts can be used for buttons and sliders.

The final, optional field for an input object of "FLOAT_INPUT" type is a format string that is used when printing the value. The format string is a simplified version of a C format string. It must start with %, optionally followed by the minimum field width, a dot, the precision and finally (non-optionally) either f, e or g (or F, E or G). For more information please read the manual page for C's printf(3).

Please note that the maximum amount of text shown in the input fields consists of 32 characters (including white-space). If the text is longer it gets truncated and longer texts can't be entered.

`input_delete()'

The function deletes one or more input field. It expects one or a list of input field identifiers as returned by the function input_create().

`input_value()'

This function returns or sets the value of an input field. The first argument must be an input field identifier as returned by the function input_create(). If this is the only argument the value the input field is set to is returned. If there's a second value the input field is set to this value. Obviously, the value must be number, an integer for INT_INPUT fields and a floating point number (but integers will also be accepted) for FLOAT_INPUT objects.

`input_changed()'

The function takes one argument, the ID of an input field. It returns 1 if the value of the input field has been changed by the user and 0 if not. Please note that the function will repeatedly report a change of the input fields value until you have determined the new value by calling input_value().

`output_create()'

In contrast to input objects output objects can be used to display a value but the user can't change the value. As in the case of input objects there are two types of output fields, one, that will only accept integer values while the other also allows output of floating point numbers. The first argument of the function for creating an output field, output_create(), is the type of the output field. If the first argument is "INT_OUTPUT" the output field will only show integer numbers, while with an argument of "FLOAT_OUTPUT" also floating point numbers can be displayed. Beside the two output fields for numerical values there also exists a field for string output. You create it by specifying "STRING_OUTPUT" as the first argument.

If the second argument is a number it is taken to be the initial value in the output field. In the case of output fields for integer or floating point numbers if there is either no second argument or the second argument is not a number but a string, the output field will be initialized to 0. For string output fields an initial value must be given if there are more arguments to follow - it can be e.g. the empty string. If a numerical value is given for a string output field the number is converted to a string representing this number.

The final, optional field for an output object of "FLOAT_OUTPUT" type is a format string that is used when printing the value. The format string is a simplified version of a C format string. It must start with %, optionally followed by the minimum field width, a dot, the precision and finally (non-optionally) either f, e or g (or F, E or G). For more information please read the manual page for C's printf(3).

Please note that the maximum amount of text shown in any of the output fields consists of 32 characters (including white-space). If the text is longer it gets truncated.

`output_delete()'

The function deletes one or more output field. It expects one or a list of output field identifiers as returned by the function input_create().

`output_value()'

This function sets a new value for an output field or returns the current value. The first argument must be an output field identifier as returned by the function output_create(). If this is the only argument the value the output field is set to is returned. If there's a second value the output field is set to this value. Obviously, the value must be number for integer and floating point output fields. If for a string output field a number is passed to the function the number is automatically converted to a string representing that number.

`menu_create()'

This function creates a popup-menu button to allow the selection of one of two or more alternatives. The first argument must be a label string, followed by as many strings as necessary (but at least two) for the items shown when the popup-menu button gets pressed. This widget does not allow setting a help string.

As usual, the value returned is an integer ID for the popup-menu button that has to be used in further commands dealing with the widget.

`menu_add()'

This function allows to add one or more entries to an already existing popup-menu, created by menu_create(). The first argument must be the ID of the menu and the following arguments must be strings, one for each new entry to add.

`menu_text()'

The function allows to either obtain or change the text of a menu entry. If called with two arguments, first the menu ID and the the number of the entry (between 1 and the total number of entries in the menu) the text of that entry gets returned. If called with another argument, a (non-empty) string the text of the corresponding entry gets set to this string.

`menu_delete()'

This function deletes one or more popup-menu buttons. It expects one or more popup-menu button identifiers as returned by the function menu_create().

`menu_choice()'

This function either selects a new item from the list of items of the popup-menu button or returns the number of the currently selected item. The first argument must be a valid popup-menu button identifiers as returned by the function menu_create(). If there is no second argument the currently selected item is returned, an integer number between 1, indicating that the first item is selected, and the total number of items, indicating that the last item is selected.

If called with a second argument this must be an integer number between 1 and the total number of items of the popup-menu button. The number indicates which of the items has to become marked as selected (where, obviously, 1 will select the first item, 2 the second etc.).

`menu_changed()'

The function takes one argument, the ID of a menu. It will return 1 if the the user has selected a new menu item and 0 if not. Please note that the function will repeatedly report a change of the selected menu item until you have determined the new item by calling menu_choice() for the menu object.

`object_delete()'

The function deletes one or more objects from the toolbox. It expects one or a comma separated list of object identifiers as returned by the functions button_create(), slider_create(), input_create(), output_create() or menu_create().

`object_change_label()'

The function allows to change the label of an object. It takes two arguments, the ID of the object that was returned when the object was created and a string with the new label.

`object_enable()'

The function allows to temporarily enable or disable the use of an object. It takes two arguments, the ID of the object that was returned when the object was created and either the string "ON" or the value 1 to enable the object (which is the default state) or the string "OFF" or the value 0 to disable the object.

`hide_toolbox()'

This function can be used to hide and later redraw the toolbox. This can, for example, be used to avoid multiple redraws when creating or deleting several objects. The function can even be used before the toolbox has been drawn for the first time. It expects exactly one boolean argument, either "ON" (or 1) to hide the toolbox or "OFF" (or 0) to redisplay it).

This document was generated by Jens Thoms Toerring on September 6, 2017 using texi2html 1.82.