Contents
Operations
User interface elements are generally considered a complex and annoying task that one must undertake when writing simple programs, the goal of which is to make the program easily controllable by the user.
The graphical user interface generated by SDPL scripts, on the other hand, does most of the work for you. Elements are automatically placed and generated with sane defaults, tuned with simple parameters, and the programmer simply gets/sets their values.
UI
This creates a user interface element. It can be specified anywhere in the program body. Elements are created in the order in which they are initialized.
They are run by the preprocessor, so variable substitutions in the UI command itself will not work.
The data portion of the UI command, whether string or hex, becomes both a symbol for the values of the element, as well as its displayed name, so usually a string would be best.
This creates a button called “MY BUTTON”:
UI /BUTTON "MY BUTTON"
The first thing after the UI command MUST be a parameter specifying the control type. The other parameters can be in any order. Invalid control types will simply not be created, and the values retrieved for those control types will be empty.
The displayed name of an element can be overridden with the /LABEL= parameter, using underscores instead of spaces, which allows the displayed name to differ from its symbol:
UI /BUTTON "INTERNAL_NAME" /LABEL=DISPLAYED_NAME
One thing of note is that some UI elements specify a subtype (such as a UI /ENTRY /FILE). Specifying multiple subtypes will have undefined behavior, for example specifying a UI /ENTRY /FILE /HEX /TEXT /NEWFILE will result in a particular subtype being chosen.
UI_GET
This copies the current value of a UI element into the program memory.
If the UI element does not exist, or does not produce an output, an empty value is placed there.
UI_GET %X "MY BUTTON"
UI_SET
This sets the value of a UI element. This sets the value of the button to 01.
UI_SET "MY_BUTTON" TO 01
User Interface Elements
Common Parameters
Certain parameters apply to all controls.
The /LABEL= parameter allows the label assigned to the element to differ from the actual control specifier.
The /WIDTH= parameter allows, for some controls, to override their width. The controls are placed in a 4 cell wide grid, so the width should be between 1 and 4.
BUTTON
The button is a switch control that can be ‘pressed’ by the user. Its value is 00 when not pressed, and greater than 00 when pressed.
DEFAULT
The default is to make a ‘push button’. A typical use of a push button would be to check if its value is 01, and if it is, react to the input and set its value back to 00 so it can be pressed again.
A push button will set its value to 01 when pressed, then disable further input.
UI /BUTTON "BTN" *REPEAT UI_GET %BTN_STATE "BTN" COMPARE $BTN_STATE TO 00 IF > PRINT "Button pressed." IF > UI_SET "BTN" TO 00 # un-press button SLEEP .50 GOTO *REPEAT
SWITCH
One button variation is switch, specified with the parameter /SWITCH.
This creates a ‘check box’ like control.
A switch, unlike a push button, does not disable itself when pressed, allowing the user to constantly modify its state.
UI /BUTTON /SWITCH "BTN" UI_GET %BTN_STATE "BTN" COMPARE $BTN_STATE TO 00 IF > PRINT "Switch is on." IF = PRINT "Switch is off."
ENTRY
This versatile element allows things like direct entry of hex arrays or text by the user, or selection of filenames.
The default display width of an entry field is 4 cells, in other words, it is designed to consume an entire display line, unless otherwise specified.
The default entry mode is TEXT (plain text)
HEX
The /HEX parameter specifies a hex entry field. This field is specially designed and will not allow non-hex entry.
UI /ENTRY /HEX "EXAMPLE_ENTRY"
If a partial HEX value (such as AA B_) is entered at the time you UI_GET the contents, that partial value will be omitted.
TEXT
The /TEXT parameter (or lack of a parameter) specifies a plain text entry:
UI /ENTRY /TEXT "EXAMPLE_ENTRY"
FILE
The /FILE parameter provides a method for users to select an existing file name.
The file is not opened when it is selected – the control itself does not touch the file at all. The programmer must get the file name and open it using the file operations. If a valid file is not selected, the value of this control will be empty.
The /EXT= parameter forces input files with a particular file extension, otherwise any file would be allowed.
UI /ENTRY /FILE /EXT=BIN "Select BIN file"
Multiple file extensions can be provided with a comma delimited list.
UI /ENTRY /FILE /EXT=TXT,DOC,RTF "Select a text file"
NEWFILE
The /NEWFILE parameter works like the /FILE parameter, but provides a method to choose a new file, rather than an existing one.
UI /ENTRY /NEWFILE /EXT=BIN "Choose new BIN file"
NUMBER
This UI element allows entry and conversion of human readable decimal values. This is useful when a variable must contain a raw value such as “Engine RPM” which requires conversion from an array.
It has many options to tailor its use.
Value Conversion
The conversion from the raw byte array to a display value is expressed with the following equation:
( N * MULT / DIV ) + ADD
Any of the parameters can be omitted if not desired, for example if the value is simply multiplied by 2:
UI /NUMBER "Doubled" /MULT=2
The equation is automatically resolved to allow values to be converted back to raw data on user input.
Other Parameters
/READONLY forbids user input
/DEC=n specifies the number of decimal places
/SUFFIX=s specifies a short suffix (perhaps the unit of measure such as KPA or RPM)
/MIN=n and MAX=n specifies the minimum and maximum allowed converted values
Monitoring for control changes
As SDPL is a simple language, there is no signal or callback mechanism to know when the text has been changed by a user.
If you find you need to respond to changes in values in realtime, use logic like this to monitor for a change, by storing the previous value and comparing it:
UI_GET %ENTRY_VALUE "EXAMPLE_ENTRY" COMPARE $ENTRY_VALUE TO $LAST_ENTRY_VALUE IF != PRINT "VALUE CHANGED TO: " /HEX $ENTRY_VALUE IF != SET %LAST_ENTRY_VALUE $ENTRY_VALUE