Button Select Macro

Macro: WaitBtns

• Introduction
• Command Summary
• Setup And Opening
• Setup And Opening Example
• Reading Button States
• Use With Custom Controls

Introduction:

The WaitBtns macro is intended to be invoked from another macro, to get user input in the form of up to 8 button states.

You can preset WaitBtns with a descriptive title and button names, as well as default button states. You can set the number of buttons, and select independent or one of two "radio button" modes of operation.

When invoked, WaitBtns suspends operation of the invoking macro and shows a dialog panel with the buttons you have created. The user can then change button states as desired. When the "OK" button is clicked, the button panel vanishes and the invoking macro proceeds. It can then read the button states and take whatever action is indicated.

Command Summary:

WaitBtns=              Open button select dialog with 8 buttons
WaitBtns#N=UC          Open with UC buttons (1-8)
WaitBtns="<<My Title"  (31 characters max)
WaitBtns#0="Button 0 Label"    (31 characters max)
WaitBtns#V="Button Ch Label    Use Ch instead of #0-#7 for label set
WaitBtns#3=UA          Preset button 3 to 0 if UA=0, else 1
WaitBtns#3x=UA         Preset button 3 as above, and show disabled
WaitBtns#V=UA          Preset button Ch to 0 if UA=0, else 1
WaitBtns#Vx=UA         Preset button Ch as above and show as disabled
WaitBtns#b=UB          Preset all buttons from low 8 bits of UB bitmap
WaitBtns#R=0           Independent buttons (default)
WaitBtns#R=1           Radio button mode, clears all button states
WaitBtns#R=2           Radio buttons, clears all, allows toggling all off
UA=WaitBtns?3          Reads button 3 state (0 or 1)
UA=WaitBtns?V          Reads button Ch state
UB=WaitBtns?b          Reads all buttons as binary bitmap
UA=WaitBtns?R          Reads which Radio button is set (if prior #R=1 or 2)

Setup And Opening:

Before opening the button select dialog, you should set it for the desired appearance and mode of operation using the following commands.

The button select dialog default title is "Wait Buttons". You can preset another title via WaitBtns="<<My Title". The title can be any quoted string or string expression, limited to 31 characters. Note the leading "<<", which may be inserted ahead of a string expressions as in WaitBtns="<<" + Str7[100].

You can preset the state of any button via WaitBtns#3=UA, where the '3' can be any digit between 0 and 7 to designate the button number, and UA can be any value or expression. If it is anything other than 0, the state will be preset to 1.

WaitBtns#V=UA works just like the above, except the 'V' means that the current value of the Ch Channel Select variable will be used instead of an explicit button number.

By adding an 'x' after the digit or 'V', the button will be set as indicated, but will be disabled (shown in gray). For example, WaitBtns#3x=0 will set button 3 to off and disabled. Without the 'x' the button will be enabled by default.

Alternatively, WaitBtns#b=UB will preset all buttons from the low 8 bits of a bitmap in UB, such that bit 0 is the 0th (top) button, etc.

You can supply a descriptive label for each button via WaitBtns#0="Button 0 Label", where the digit after the '#' can be 0-7 to specify the button number, or 'V' to use the Ch Channel Select variable as above. The label on the right side can be any quoted string or string expression up to 31 characters long. Note, however, that it must start with a quote, not a string variable. If you need to start with a string variable, precede it with a pair of empty quotes as in: WaitBtns#V="" + Str7[1220 + 20 * UI]

By default the buttons will be independent, which can also be set explicitly with WaitBtns#R=0. Setting WaitBtns#R=1 will result in "radio" buttons such that only one can be selected at a time; all button states will be cleared (unselected) by this command, so it will normally be followed by a command to preset one of the buttons. WaitBtns#R=2 operates the same way, except that it allows all buttons to be unselected by clicking on the sole selected button.

The above setup commands may be given in any order, with the exception that after setting radio button mode you should set one of the button states to 1 (depressed). Also, if a radio button command is used, any disable commands like WaitBtns#3x=0 must come after it.

Finally, WaitBtns#N=UC opens the dialog with UC buttons, where UC may be any value or expression that evaluates to a number in the 1 to 8 range. A value of less than 1 or more than 8 will result in 8 buttons. Alternatively, you can omit the '#N' and the right side to get 8 buttons: WaitBtns=.

Setup And Opening Example:

The DaquinOscope macro mini-app uses WaitBtns to set the ADC clock rate, and to select the analog or digital inputs to be displayed. The example below is for setting the ADC clock rate. It is extracted from the _Dscope_Ctrls macro that handles Custom Controls events for DaquinOscope.

The '#V' Channel Select approach makes it convenient to label all the buttons in a WHILE loop. Here String Array Str7 holds 7 strings starting at index Str7[1220], corresponding to the 7 available ADC clock rates. These are near the start of the DaquinOscope main macro:

Str7[1220]="Clock1 = 8 MHz"
Str7[1240]="Clock2 = 4 MHz"
Str7[1260]="Clock3 = 2 MHz"
Str7[1280]="Clock4 = 1 MHz"
Str7[1300]="Clock5 = 500 kHz"
Str7[1320]="Clock6 = 250 kHz"
Str7[1340]="Clock7 = 125 kHz"

Then when the user clicks on the "ADC Clock" button in the Custom Controls dialog, the WaitBtns buttons are labeled, radio-button mode is set, the proper button is set for the current clock rate (held in variable UA), and the WaitBtns button select dialog is opened showing 7 buttons:

    UI=0                   ;Start with button 0
    WHILE.UI=<7            ;Do buttons 0-6
        Ch=UI                  ;Set button to be labeled
        WaitBtns#V="" + Str7[1220 + 20 * UI]   ;Set label
        UI=UI+1                ;Next button
    WEND.
    WaitBtns#R=1           ;Radio-button mode
    Ch=UA-1                ;Current mode UA=1-7 -> button 0-6
    WaitBtns#V=1           ;Current mode button on
    WaitBtns#N=7           ;Open dialog with 7 ADC clock rates

Reading Button States:

After the user clicks the 'OK' button, WaitBtns normally returns control to the invoking macro, which can then read the state of the buttons. (See Use With Custom Controls below for the DaquinOscope example operation.)

UA=WaitBtns?3 sets UA with the state (0 or 1) of button 3, where the '3' can be any digit between 0 and 7 to select the desired button.

UA=WaitBtns?V works just like the above, except the 'V' means that the current value of the Ch Channel Select variable will be used instead of an explicit button number.

UB=WaitBtns?b returns the state of all buttons at once, by setting the low 8 bits of UA with a bitmap. Bit 0 is the 0th (top) button and bit 7 is the bottom.

UA=WaitBtns?R sets UA with the button number (0-7) that was selected in radio button mode, assuming WaitBtns#R=1 or WaitBtns#R=2 were used for the setup. The command will return UA = -1 in the case where all radio buttons have been deselected in WaitBtns#R=2 mode.

Use With Custom Controls:

As noted above, when invoked from a normal macro WaitBtns suspends operation of the invoker until the user clicks the 'OK' button, after which it returns to the next command in the invoker where the button states can be read.

However, when invoked from a Custom Controls button click the operation is somewhat different. The invoking event, as with operation of all Custom Controls, is handled by a separate macro which then returns to wait for the next Custom Controls event. The Setup And Opening Example presented earlier is actually an excerpt from the _Dscope_Ctrls handler for the Ctrls=8 event, which is activated whenever Btn4 is clicked. The final line in that example (WaitBtns#N=7) not only opens the WaitBtns dialog, but also concludes the event. So there would seem to be nothing for the WaitBtns 'OK' to return to.

Instead, WaitBtns tests to see if it was invoked by a Custom Controls event, and saves the event number if so. Then when 'OK' is hit, it initiates a Custom Controls event that has the same base number ORed with h80. In the above example, that would be Ctrls=h88. The _Dscope_Ctrls macro thus includes a test for this event, which then reads the number of the selected button and uses it to construct a command to the Arduino that sets the chosen ADC clock rate.

See also Macro Overview