GCONTROL
Jump to navigation
Jump to search
Macro interface for creating control panel entries
<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 <i>with</i> <b>styled</b> <font color=#ff0000>& HTML</font> <font color=#00ff00>tags</font>.</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 <b>BOLD string</b></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