SWITCH
Jump to navigation
Jump to search
Define static switches or get a switch value into a results parameter
<NAME> Name of the switch <VALUE> Switch value for SET; Switch value label for GET (default) and DEL <FUNC> Action to perform (GET[DEF], GETALL, SET, or DEL) <DEF> Default value if switch is not present <SDEF> Default value if only a state switch is present SWITCH is the mechanism by which macros define their own switches and branch in response to switches. Functions: GET - Gets a particular switch and stores its value in a result Syntax: SWITCH <NAME> <VALUE> GET <DEF> <SDEF> <NAME> The name of the switch (e.g. "MYSWITCH") <VALUE> The label of the result to store the value of the switch in (e.g. "MYVALUE") <DEF> The default value if the switch is not specified <SDEF> The default value to use if the switch is given as a state switch (usually "true" or "1"). If not set, the empty string ("") will be used. SET - The SET function works the same as the GET, but has the effect of setting the highest precedence for the value of the switch. This was done to allow commands within a macro to NOT inherit values of designated switches. See example. (Since NeXtMidas 2.9.0) Syntax: SWITCH <NAME> <VALUE> SET <NAME> The name of the switch (e.g. "MYSWITCH") <VALUE> The value to set the switch to, or the label of the result containing the value DEL - The DEL function allows the user to delete any current value for the switch. This also allows for users to not inherit a values of designated switches, but does not set a value in turn. See example. (Since NeXtMidas 2.9.0) Syntax: SWITCH <NAME> <VALUE> DEL <NAME> The name of the switch (e.g. "MYSWITCH") <VALUE> The label of the result to store the previous value of the switch (since neXtMidas 3.1.3) GETALL - Gets all switches and stores their values in a result. Note that this function works by looking at all switches passed in on the macro's command line rather than looking only for a pre-defined set of switches. (Since NeXtMidas 2.9.0) Syntax: SWITCH ,, <VALUE> GETALL ,, <SDEF> <VALUE> The name of the table to put the switches in. If the table exists, the contents of the table will be used as default values (like <DEF> with GET) <SDEF> The default value to use if the switch is given as a state switch (usually "true" or "1"). If not set, the empty string ("") will be used. In NeXtMidas, most switches can be tested in logical test directly, as with if /C then ... else ... endif The same syntax works on numeric or string values, as with if /FN eqs "MYFILE" or if /N gt 4 The switch statement is useful for applying defaults to switches that may or may not be present, as with switch FN fnlabel get "MYFILE" or switch N nlabel get 20 which applies the defaults "MYFILE" and 20 to those switches, if they are not applied. String valued switches that supply the <SDEF> parameter will set the value to <DEF> if the switch is not present, or <SDEF> if the switch is present but no =value is given. SWITCH inheritance: 1. Switches right after the command (no space in-between) are inherited by primitive and intrinsic commands called by the command. e.g. MYMACRO/ASWITCH arg1 arg2 2. Switches at END of argument list are the same as the above but they are also inherited by macro commands called by the command. e.g. MYMACRO arg1 arg2 /ASWITCH SWITCH precedence (order): 1. Macro command line (passed in when macro is run) 2. Commands (macros,primitives,intrinsics) in the macro 3. Command dictionary (commands.cnf) 4. Macro Defaults (on startmacro line) eg. startmacro/switch Examples: 1. Set fnlabel to "NOFN" if no switch is present, or "MYFILE" if just /FN is present. If /FN=<text> is present, fnlabel will have the value of <text>. switch FN fnlabel get "NOFN" "MYFILE" 2. A switch command with its own switch has the effect of setting the default: switch MYSW myres /MYSW=10 3. Allow child macro to see a pipes created in calling macro mymacro/sharemask=pipes 4. Set the value of a switch regardless of what is passed in on the command line (ignore precedence): switch name="MYSWITCH" value=15 func=set 5. Delete a current switch but store its value, if it exists. switch name="MYSWITCH" value=savedVal func=del 6. Get all switches passed to the macro switch ,, mytable ,, GETALL ,, 1 7. Use the switches passed to the macro to override a set of defaults set t:mytable {SWITCH1="VALUE1",SWITCH2="VALUE2"} switch ,, mytable ,, GETALL ,, 1 Switches: /CS - Get a case-sensitive value (for FUNC=GET) without requiring user to quote strings. (Since 3.1.2) /QUIET - Disable verbose messages (overrides universal /VERBOSE switch). (Since 3.3.0) Graphical Command Switches: Applies to anything that extends nxm.sys.lib.MWindow, like PLOT, LIST2, GCONTROLS, etc. /DISPLAY= - Make window come up in specified display mode: Icon, Back, Front, or Maximized. (Since 3.1.1) /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) /ICON - Make window come up in icon state. (Since 3.1.0) /NOALTTITLE - Disables automatic updates to the status/title bar text from events such as mouse hovers. (Since 3.3.0) /NOPUSHPOP - Disable window push/pop out/in of panel. The /EVENTFILTER= switch takes precedence over this. /SHARETHEME - Whether or not to have all graphical components share the same Theme. (Since 3.3.0) /THEME= - Specifies the THEME to use. See EXPLAIN LOOKANDFEEL. /WDISP= - Specifies the Window DISPlay to use (i.e. specifies which monitor for systems with 2+ monitors). /WFS= - Window or widget font size. /WIN= - Specifies the name of WINdow (or panel) in the registry that will host this window. If the window name is not specified, or included in panel config, a new frame is is created. /WIN.<cmd>= - Similar to /WIN. /WIN.NEW - Always open in a new frame. /WPOS=(x,y,w,h) - Window position in pixels. Width and height are optional. /WTITLE= - Window title. Macro Switches: /MSGDEBUG=mask - Enable debugging printout of messages processed (e.g. received) by macro. Default for just specifying as a state switch is NAME|INFO|DATA|QUALS|FID|TID. [DEF=NONE] (Since 2.7.1) /SHAREMASK= - Control whether or not a child macro (a macro called from another macro) can see the parent's (calling macro) pipes. Currently the only options are "PIPES". [DEF=NONE] (Since 2.7.3) Pipe and File Switches: /AUX= - Specifies which AUX to use for file. The {AUX=<aux_name>} file qualifier takes precedence over this. /PS= - Pipe Size in bytes. [DEF=131072] /TLL= - TimeLine length [DEF=128] /TLT= - TimeLine tolerance [DEF=0.1] Universal Switches for all command (when handled by NeXtMidas proper): /BG - Run command in BackGround. [DEF=FALSE] /CMDOPENTIMEOUT=- Provides a way for a command run in a pipe section to NOT wait for a very slow open() to complete before running the next command in the pipe section. [DEF=-1 for effectively infinite] (Since NeXtMidas 2.7.4) /CMDRUNMODE= - Provides a way for a command to override its default run mode behaviors. An example of this is running a primitive to completion in a pipe section. Possible values: Default - Use default behavior (this is the default) RunToCompletion - Run command to completion rather than following the normal pipe section rules, note that this does override /BG. (Since NeXtMidas 3.5.4) /ID= - Associate an ID to a command. Only primitive, host primitive, or macro IDs are used for message passing, entry in the registry, etc. [DEF=based on command name] /MSGID= - Sets the ID of the registry entry that will process messages sent by this command. Using /MSGID=MAIN will send all messages to the macro's processMessage procedure. [DEF=none] /POLL= - Time (in seconds) between process loops (e.g. reads of a file) when there are no data to process. [DEF=ENV.PAUSE] /VERBOSE - Produce more screen (verbose) output. [DEF=FALSE in macro, TRUE at shell prompt]