ConvertBot: Macro interface for creating control panel entries

2020-04-27T22:04:37Z

Macro interface for creating control panel entries

New page

Macro interface for creating control panel entries
<pre>
<TYPE> Widget type: ALERT, BEAN, BUTTON, CALENDAR, CHOICE, DIALOG,
FILE, LABEL, LIST, MENU, PANEL, PIPEMON, PROMPT,
PROGRESS, QUERY, STEXT, TABLE, TEXT, (x)VAL
Where (x) can be of type [DFLT] (eg DVAL, FVAL, LVAL, TVAL).
<NAME> Control name for messaging/result table access
<TITLE> On-screen control label or prompt for all widget types
<P1> First <TYPE>-dependent parameter
<P2> Second <TYPE>-dependent parameter
<P3> Third <TYPE>-dependent parameter
<P4> Fourth <TYPE>-dependent parameter
<P5> Fifth <TYPE>-dependent parameter

Keyword Only Parameters:
[TABLE] - Inline Table to set gcontrol options (properties). (Since 2.7.0)
E.g. to set the ItemColors MENU and it's ToolTipText:
TABLE={ItemColors={PASS="GREEN",FAIL="RED"},ToolTipText="more info.."}

This intrinsic creates control panel objects and sends them to a PANEL
primitive for handling. The default handler is REG.PANEL. To specify an
alternate panel, use the /PANEL=xxx switch (without the REG.). A GCONTROL may
be created any time after the parent PANEL has been created. If used without a
parent macro or panel, the gcontrol will run standalone and return its value in
a result parameter named by <name>.

Each control has a common set of parameters and flags, and another set that is
specific to each widget type.

The common flags for all widgets are:
PERMANENT - widget persists no matter what action is taken
STICKY - widget persists until a right click removes it
FIXED - widget is not allowed to be moved by the user
NOEDIT - widget cannot be edited nor any action taken
INLINE - removes borders to allow embedding in another display
INBAND - not implemented
NOMSG - suppress messages to the macro when this widget changes
VBOX - draw box around current value
VBOXMO - draw box around current value on mouse over

Flags can be set using the /FLAGS=NOMSG|STICKY syntax, or by specifying a state
switch with flag name like /NOMSG or /STICKY. Note that flags placed in the
/FLAGS switch can be abbreviated, where flags as standalone switches must be
exact matches or its negation, ie (/MSG=N matches the NOMSG flag). Also,
standalone flag switches must appear on the command line, they do not check the
global macro switches.

By default a GCONTROL responds only to graphical interaction; however, there
are three provisions for non-graphical interaction. First, the value of any
control can be set behind the scenes by any NeXtMidas object that can call the
control's setValue() method. Second, the /MON=resname switch causes the
control to update its value based on the result named <resname> if the control's
poll() method is coded. Third, if the /MSG=no switch is not asserted, all
controls except LABELs send update messages to the macro's processMessage
handler.

All GCONTROLS have setValue(), getValue(), and setAction() methods that can be
called from the macro language. Setting GC.<NAME>.VALUE simply updates the
current value and display. Using GC.<NAME>.ACTION updates the current value and
sends a message as if graphical action were performed.

Functions are listed below in alphabetical order.

FUNCTIONS:
ALERT - Pop up message (nxm.sys.libg.GAlert)
GCONTROL ALERT <NAME> <TITLE> <P1=text> <P2=actions[OK]> <P3=default[1]>

BEAN - Instantiates an external control that exists within a user option tree
specified as <P1>. (Since NeXtMidas 2.9.1)
GCONTROL BEAN <NAME> <TITLE> <P1=fully qualified class name> &
<TABLE={Property1=Value1,Property2=Value2,..}>

Example to use Date/Time picker under UCL:
TIMEX now myDateTime
GCONTROL BEAN uclDatePicker "Date Picker" P1="nxm.ucl.libg.GDatePicker" &
TABLE={StartTime=^myDateTime}

Example to use GSwingLabel (javax.swing.JLabel) under UCL:
SET htmltext "<html>JLabel with styled &
HTML tags.</html>"
GCONTROL BEAN uclJLabel "title" P1="nxm.ucl.libg.GSwingLabel" &
TABLE={LabelText="^htmltext"}

BUTTON - Button group (nxm.sys.libg.GMenu)
GCONTROL BUTTON <NAME> <TITLE> <P1=names> <P2=default[1]>
names - list of button names (comma-separated) for button group
default - default button to select

Flags: Toggle - toggle allows multiple selections
ChkBox - display buttons with check box
TTop,TLeft,TRight,TBottom,TOff - title placement
OneRow,ToggleList - format options
NoState - selected button not shown as
depressed

CALENDAR - Date selector (nxm.sys.libg.GCalendar)
GCONTROL CALENDAR <NAME>

A CALENDAR control defaults to a square of size PANEL_WIDTH x PANEL_WIDTH.
The GET command can be used against a CALENDAR control to retrieve the
following information:

DATE = string in the form: 'Sat Nov 03 08:41:12 EST 2001'
MONTH = index of month: 11
YEAR = numeric of year: 2001
DAY = current day: 3

CHOICE - Pull down selector (nxm.sys.libg.GMenu)
GCONTROL CHOICE <NAME> <TITLE> <P1=choice list> <P2=default[1]>

Flags: Input - allows input of a value not in the current list
CS - Return values Case Sensitive (as entered)
TTop,TBottom - title placement [DEF=TLeft]
TLeft,TRight

DIALOG - Widget Dialog control object (nxm.sys.libg.GDialog)
GCONTROL/handle=<registryName> DIALOG <NAME> <TITLE> <P1=width> <P2=height>
<P3=buttonList> <P4=noCloseList[null]>
NOTE: A CANCEL button in <buttonList> will NOT send a message.

A DIALOG control must include a /HANDLE=name switch to add it to the
registry. The dialog is then populated by instantiating controls with
/PANEL=name specifying which dialog to add them to. When a dialog is
processed, the message data is a table of the embedded controls including a
menu named DIALOG which contains the state of the action button
(i.e. msg.data.dialog.value).
Since NeXtMidas 3.0.1, the one-based index of the pressed button is stored
in message info (i.e. msg.info)

FILE - File selector (nxm.sys.libg.GPrompt/nxm.sys.libg.GFiles)
GCONTROL FILE <NAME> <TITLE> <P1=seed[""]> <P2=filter[*.tmp|prm]>
<P3=auxlist[AUX.WRITE]> <P4=cols[50]> <P5=rows[15]>

The <seed> is the current selected file. The <filter> is a single filter
(like *.tmp) with additional extensions separated by a |.

Flags:
Path - Include path in displayed filename
AuxID - Include AUX ID in displayed filename
Qual - Include QUAL data ({AUX="+aux+"}) in displayed filename
Ext - Selection data includes extension
SingleAux - Only allow a single AUX to be selected from the AUX list
HideOpts - Hide the list of options

The standard FILE popup (such as PLOT popup for adding new files to the
displayed PLOT), contains lines for the following:
File - The selected filename
Filter - Filter on file names (typically extensions)
AuxList - Aux's to look for files
Option - Show PATH, AuxID, or QUAL in the selected file name
PATH - Selection data includes path
AUXID - Selection data is of form: <AUX>/<name> (e.g. web use)
QUAL - Selection data is of form: <name>{AUX="+aux+"}

Example:
gcontrol FILE filechooser "Files" world.prm "*.tmp|prm" "DAT|CWD" 60 10

LABEL - Roll-up/roll-down. Non-label controls below this are hidden
and shown by clicking on this widget. (nxm.sys.libg.GLabel)
GCONTROL LABEL <NAME> <TITLE> <P1=Hidden|Closed|Open|AlwaysOpen[Open]>

When a LABEL control is created, all controls added up to the next LABEL
will belong to a group identified by the first label's <NAME>. To add a
control to a group that is not the current one, use the /GRP=name switch.
A LABEL has a setAction() method to control how the label appears:
0=label only, 1=label and contents, -1=nothing.
Clicking on the label toggles between active=0 and active=1. By default, no
message is sent to the macro's processMessage handler when a LABEL is
clicked. To enable LABEL message sending, assert /MSG=yes.

Prior to NeXtMidas 2.1.0: <P1=Hide|Off|On [On]>, old values are deprecated,
please change them.

LINE - Draws a horizontal line across the control panel (nxm.sys.libg.GLine)
(Since NeXtMidas 2.9.1)
GCONTROL LINE <NAME> <TITLE> <P1=COLOR> <P2=THICKNESS> <P3=PERCENTAGE>
<P4=POSITION>
COLOR - String form of color [Theme foreground color]
THICKNESS - Thickness of line in pixels [Default Border Width]
PERCENTAGE - Percentage of the control panel to draw across [100]
POSITION - Where to draw from (LEFT, RIGHT, or [CENTER])

Example to draw a green line 5 pixels thick across the central half of the
control panel:
gcontrol LINE myLine "" "GREEN" 5 50 "CENTER"

LIST - List selector (nxm.sys.libg.GList)
GCONTROL LIST <NAME> <TITLE> <P1=String of entries> <P2=width in chars [40]>
<P3=height in lines [20]>

MENU - Menu of items (nxm.sys.libg.GMenu)
GCONTROL MENU <NAME> <TITLE> <P1=item list> <P2=default item>

Flags: Button,Toggle,ChkBox - toggle allows multiple selections
TTop,TLeft,TRight,TBottom,TOff - title placement
OneRow,ToggleList - format options
CS - Return values Case Sensitive
(as entered)

NOTE: Do not use the Rollup flag, it is mean to be an internal state toggle
for popup menus when collapsed (rolled up) or expanded (opened).
Instead, use GCONTROL LABEL with a Closed state.

PANEL - Widget panel to host another graphical primitive (nxm.sys.libg.GPanel)
GCONTROL PANEL <NAME> <TITLE> <P1=width_pixels[200]> <P2-height_pixels[200]>

PIPEMON - Pipe monitor for debugging pipes or simple status displays
(nxm.sys.libg.GPipeMonitor)
GCONTROL PIPEMON <NAME> <TITLE ["NOPIPE"]>

Flags: Slider - show slider bar with read/write pointers
Showrate - show numeric value of data rate in display (MByte/sec)

PROMPT - Text prompt and entry (nxm.sys.libg.GPrompt)
GCONTROL PROMPT <NAME> <TITLE["Input"]> <P1=DEF["default"]>
<P2=length=# chars[10]>

Flags: Password - The prompt text field is a password field. All text is
hidden (dummy echo chars displayed instead). Plain text
may be obtained via getValue (e.g. gc.idprompt.value).
(Since NextMidas 2.9.0)

LimitChars - Enforce a max limit for the number of input characters
to whatever is specified in LEN=.
(Since NeXtMidas 2.9.0)

NoWarn - Do not display a warning to the user if the user is
trying to exceed the character limit set in LimitChars.
(Since NeXtMidas 2.9.0)

PROGRESS - Graphical Progress Monitor/Abort Dialog (nxm.sys.libg.GProgress)
GCONTROL PROGRESS <NAME> <TITLE> <P1=button list["Run,Pause,Exit">
<P2=display text["Job Completion Status"]>
<P3=width> <P4=height>

QUERY - Query control object for debug or control of an object
(nxm.sys.libg.GQuery)
GCONTROL QUERY <NAME> <TITLE ["QUERY"]> <P1=object name> <P2=property list>

Flags: Filter - apply default filter to limit introspection

STEXT - Multi-line styled text/HTML display object (nxm.sys.libg.GSText)
(Since NeXtMidas 3.1.1)
GCONTROL STEXT <NAME> <TITLE> <P1=styled text string> <P2=columns> <P3=rows>

TABLE - Table Dialog control object (nxm.sys.libg.GDialog)
GCONTROL TABLE <NAME> <TITLE ["Table"]> <P1=values table> <P2=config table>

TEXT - Multi-line text display object (nxm.sys.libg.GText)
GCONTROL TEXT <NAME> <TITLE> <P1=text string> <P2=columns> <P3=rows>

LVAL - Int (32-bit)
TVAL - Time
DVAL - Double
FVAL - Float
(x)VAL - Value control widget. (nxm.sys.libg.GValue)
The (x) is one of: T-Time, D-Double, F-Float, or L-Int
GCONTROL (x)VAL <NAME> <TITLE> <P1=DEF[0.5]> <P2=MIN[0.0]> <P3=MAX[1.0]>
<P4=INCrement[(MAX-MIN)/20]>
Flags: NoNumb - do Not display the numeric value
Gauge - display as a clickable empty/full gauge
Slider - display as slider bar
VuMeter - display as blocked gauge
Minimum - display minimum value
Maximum - display maximum value
Percent - display as percent
Hex - display as hex
Discrete - allow values only where val%inc==0
MsgOnDrag - send slider msg while slider is moving [DEF=TRUE]
RightJustify - allow users to right justify (Since NeXtMidas 3.7.0)

Note: Setting P3 to -1 makes the MAX value unlimited.

Note: The default values for TVAL are <P1=DEF[0.0]> <P2=MIN[0.0]>
<P3=MAX[-1.0]> <P4=INCrement[1.0]>. (Since NeXtMidas 3.5.1)

Toggles
=======
Buttons and Menus can be implemented as Toggles. Toggles, since they allow
multiple concurrent item selections, use a MASK value for selecting items,
not an index. Therefore, users should be aware when setting the value of a
toggle to use the recommended syntax for setting MASK values. For example:

gcontrol/toggle button myButt "Title" "A,B,C" "A|C" ! Correct
gcontrol/toggle button myButt "Title" "A,B,C" "C" ! Correct
gcontrol/toggle button myButt "Title" "A,B,C" "+C" ! Correct
gcontrol/toggle button myButt "Title" "A,B,C" "~C" ! Correct
gcontrol/toggle button myButt "Title" "A,B,C" "|C|" ! Correct
gcontrol/toggle button myButt "Title" "A,B,C" "ALL" ! Correct
gcontrol/toggle button myButt "Title" "A,B,C" "NONE" ! Correct
gcontrol/toggle button myButt "Title" "A,B,C" 3 ! WRONG

Also, since toggles uses an 32-bit integer mask value (with values <0
being special), a toggle is limited to 31 items.

Setting Menu Colors
===================
Menu item colors can be manipulated with a Table of colors for each item in
the menu:
{ITEM1=RED,ITEM2=BLUE,...ITEMn=GREEN}

The following code-snippet is used in many of the test macros in the
nxm.sys.test directory.
...
pipe on
panel/controls=gc
gcontrol menu main "Exit with Status = " "PASS,FAIL"
set gc.main.itemColors {PASS=GREEN,FAIL=RED}
pipe off
...

Disabling Gcontrols
===================
Since NeXtMidas 2.9.1, it is possible to disable certain GControls. The
controls that can be disabled are Labels, Prompts, Values (dVal, lVal, etc),
and Menus (Buttons, Menus, and Choices). Disabling the control is the same as
setting the flags NOMSG and NOEDIT, plus the control text changes color
(default is gray) to depict this change. To disable:

set gc.ControlID.enabled false
-or -
gcontrol button myButt "Label" "A,B,C" TABLE={ENABLED="FALSE"}

To re-enable the control:

set gc.ControlID.enabled true

To toggle the enabled state of the control:

invoke gc.ControlID.toggleEnabled()

To change the color of the disabled text (does not refresh automatically):

set gc.ControlID.disabledColor "<COLOR>"

Disabling Individual Menu Items
===============================
Since NeXtMidas 2.9.1, it is possible to disable individual menu items. This
includes buttons. The disabled items will have their text change color (default
is to GRAY) and will not send a message or otherwise be selected when clicked.
To disable an item:

set gc.MenuID.disableItem "<ItemText>"

To re-enable a disabled item:

set gc.MenuID.enableItem "<ItemText>"

To disable multiple items:
set gc.MenuID.disabledItems "<Item1Text,Item4Text>"
- or -
gcontrol button myButt "LABEL" "A,B,C,D" "A" TABLE={DISABLEDITEMS="B,C"}

To change the color of a disabled items (does not effect currently disabled
items):

set gc.MenuID.disabledItemColor "<COLOR>"

Since NeXtMidas 3.5.1, if the default item is disabled, the default will be set
to none.

Formatting xVal and PipeMon Values
==================================
The /FMT= switch can be used with [x]VAL and PIPEMON controls to format the
displayed numerical values of the control. There are a variety of acceptable
inputs to this switch, as well as the special patterns:
HH:MM:SS - Show in hours:minutes:seconds
DMS - Show in deg'min'sec format (i.e 33'22'11)
? - Question marks are replaced with blanks and trigger the
use of a multiplier

Units are defined as the String to the right of the last blank space in the
input String. (e.g. "## MHz" the units are MHz).

See nxm.sys.lib.Format.java for more details.

Examples:
1. A two column toggle menu with checkbox.
gcontrol menu MYMENU "Selections" "A,B,C,D,E,F" /nc=2 /flags=chkbox|tright

2. Same as above but using switches instead of flags
gcontrol menu MYMENU "Selections" "A,B,C,D,E,F" /nc=2 /chkbox /tright

3. A simple DIALOG box from the SD360 macro
gc/temp/handle=dlog dialog "DIALOG" "Test Dialog Box" 300 -6
gc/panel=dlog choice shape "Shape" reg.waveform.shapeList reg.waveform.shape
gc/panel=dlog button wind "Window " reg.fft.windowList reg.fft.window &
/tleft /nc=3
gc/panel=dlog dvalue sfreq "SineFreq" sfreq -sr sr sr/20
gc/panel=dlog text text "TextInfo" "A test message" 30 3
gc/panel=dlog menu form "Format " "SF,CF,SI,CI" reg.waveform.format &
/tleft /nc=4
gc/panel=dlog list list "TextList" "A,B,C,D,E,F,G,Another Long One" 30 3

4. Use inline 'TABLE=' format to set gcontrol options
gcontrol/tleft menu MAIN "Exit with Status = " "PASS,FAIL" &
table={ITEMCOLORS={PASS=GREEN,FAIL=RED}}

5. Create a CHOICE Widget and set its tool tip text.
gcontrol choice choiceWidget "CHOICES" "Choice1,Choice2" "Choice2"
/input /tooltip="Some Text"

6. Example to display html styled text inside a gcontrol widget:
res mystr "<html><body>My HTML BOLD string</body></html>"
gcontrol STEXT gstext "HTML/Styled Text Below" mystr 24 25 /title

7. Disable a gcontrol widget from updating the status/title bar text. This
is usually from mouse hovers.
gcontrol prompt prompt1 "PROMPT 1" "Text" /noReadoutUpdates
- or -
set gc.prompt1.NoReadoutUpdates true

8. Display the current date and time in a gcontrol widget:
timex now currTime
gcontrol TVAL gcDateTime "Date & Time" currTime 1 -1 1

9. Display the current date and time in a gcontrol widget:
timex now currTime
gcontrol TVAL gcDateTime "Date & Time" currTime min=1 max=-1 inc=1

10. Display the current time in a gcontrol widget:
timex now currTime sod=secOfDay
gcontrol TVAL gcTime "Time" secOfDay min=1 max=-1 inc=1

The demo.mm and nxm.sys.test_gcontrol.mm macros have more examples of each
widget type. The macro test_gcontrol_table.mm has more examples of the inline
set method ('TABLE=').

Messages:
Received:
EXIT - Destroy control
REFRESH - Refresh control on screen
SHOWN - Same as REFRESH
Sent:
All widgets can send messages by the id <NAME>
(x)VAL - INFO = GValue.CHANGED_BY_POLL or GValue.CHANGED_BY_CLICK

Switches:
/BORDER Turns on the widget border.
/CS MENU,CHOICE,BUTTON - Return values case-sensitive (as-entered)
/DIALOG Treats the control as part of a dialog.
/EDIT= Widget is editable [true]
/EVENTFILTER= Window event filter mask (e.g. NoMouse,NoKeyboard,NoMove,
NoPushPop,NoMiddleMouse). For complete list of values see
nxm.sys.libg.MWindow.eventFilterList. (Since 3.3.1)
/FLAGS= One or more ORed flags selected from the common|specific lists
See above for a description of how flags can be entered as named
switches as well.
/FMT= Text format specifier of the form xxx.xx(<TYPE>=[x]VAL or PIPEMON)
Can be used with /MULT switch to control format.
DEFAULTS -> TVAL="HH:MM:SS", LVAL="#0", DVAL="##0.###E0"
See note above for more details.
/GC=<table> Look in given table for a key <NAME> to set the default value for
this control. This is useful for holding all the controls' state
in one table.
/GRP= Name of control group (LABELed section) to which GCONTROL belongs
/HANDLE= Handle of control's entry in results table (for /TEMP)
/HEADLESS Suggests headless operation.(Does not guarantee true headless
operation at this time.)
/IDEF= Sets default value as an integer. This overrides the default used
with most controls that is read in as a string.
/INPUT= When TRUE, allow input as well as to pick from CHOICE list.
CHOICE ONLY [DEF=FALSE]
/INPUTBORDER={PERM,MO} Draw either a permanent (PERM) or mouseover (MO) border
around widget to indicate user's ability to right-click and enter
text. Valid for editable CHOICE (w/input flag), (x)VAL, and PROMPT
widgets.
/LEGACY Temporarily override the fix for Bug 205 (hard to use popups).
(The /LEGACY switch will be removed in the future.)
/LH= Line height in pixels [0==>automatic]
/MON= Name of result parameter to poll for changes <TYPE>=xVAL or PROMPT.
Note that for (x)VAL widgets, a change via a click can be
distinguished from an external (result) change via the info field.
For a click change the info field has a value of:
GValue.CHANGED_BY_CLICK
and for a result change the info field has a value of:
GValue.CHANGED_BY_POLL
/MSG Send message upon change [false for <TYPE>=LABEL, otherwise true]
/MULT= Convert units using scientific notation prefix. (<TYPE>=[x]VAL).
Arguments for this switch can be passed in three ways:
1) n, where n is one of -12,-9,-6,-3,3,6,9,12: (e.g. 6 is Mega)
2) One of: pico,nano,micro, milli,Kilo,Mega,Giga,Tera
3) One of: 'p','n','u','m','K','M','G','T'
/NC= Number of columns {<TYPE>=MENU} [0==>automatic]
/NOALTTITLE Disables gcontrols automatically updating the text of the
title/status bar on events such as mouse hovers. Since 3.3.0.
/NODEPRESS Selected button is not shown as depressed
/NOMSG Disables sending of a message when updated
/NONUMB Do not display numbers on (x)VAL.
/NOREADOUTUPDATES Disables mouse hovers updating the title bar readout
/NOSTATE Button does not change state when pressed
/PANEL= Panel to contain widget ["PANEL"]
/TEMP Widget is temporary [false]
/TEXT Include text in control (<TYPE>=[x]VAL) [true]
/THEME= NOTE: This affects the GLOBAL theme! Use /WTHEME to affect only
this gcontrol's theme. Refer to /WTHEME below for list of options.
/TIMEOUT= Sets an ALERT to automatically close after the specified number of
seconds have passed (no timeout if <= 0) (NeXtMidas 1.9.2)
/TITLE Turns on the title for the widget.
/TOOLTIP= Sets the ToolTipText in a Swing Widget, or adds the text to the
title bar readout.
/UNITS= Units string to append to value in appropriate widgets
/WAIT= Wait for control to complete its function (implies /TEMP)
/WFS= Override Widget Font Size [DEF=12]
/WH= Control height in pixels [0==>automatic]
/WIN= Override the parent window.
/WTHEME= Affect only this gcontrol's theme and not the global theme.
(NeXtMidas 2.7.0) Color scheme name selected from list:
Desktop,Default,WoB,GoB,BoW,Browser,Gear1,Gear2,Gear3,Gear4,NAK
or a table creates a custom theme. Table keys are:
CBG - background color
CFG - foreground color
CWBG - widget background color
CWTS - widget top shade
CWBS - widget bottom shade
CWMS - widget middle shade
CWFH - current widget foreground highlight (Roll down name color)
CWFG - current widget foreground color
CWTI - current widget title color
Note1: Since NeXtMidas 3.0.0, it is possible to set a component
color based off another color in the current theme(_THEME_). E.g.
gc button myBtn "Title" "A,B" "A" /wtheme={CWTI=_THEME_CWFG}
Note2: Since NeXtMidas 3.1.1, this overrides /THEME= switch.
/WW= Control width in pixels [0==>automatic]

See Also: PANEL, nxm.sys.libg.GWidget, nxm.sys.libg.GMenu, nxm.sys.libg.GValue
See Also: nxm.sys.test.test_gcontrol.mm

</pre>

[[Category:NXM_Explain]]

GCONTROL - Revision history

ConvertBot: Macro interface for creating control panel entries