ConvertBot: draws a bare window with facilities for overlaying other windows

2020-04-27T22:05:04Z

draws a bare window with facilities for overlaying other windows

New page

draws a bare window with facilities for overlaying other windows
<pre>
<FILE> - Setup file or Macro name with pane placement and properties

This primitive is a raw window with an interactive panelizer holding multiple
panes. Each panel is given an entry in the registry for other primitives to
draw into. By default, the registry entry for the table of window panes is
REG.WIN

The /SETUP switch is used to place the panel in "MACRO" mode. In macro mode,
the config file name is generated by replacing the extension on the macro file
with '.mmp' for Midas Macro Panel. If /SETUP=XYZ is specified, the extension
becomes '.mmpxyz', where 'xyz' is a user designated alternate setup. The
default for /SETUP is "" creating the extension mmp.

The /TSETUP switch is used similarly to /SETUP, but with a couple important
differences. The main difference is that "/TSETUP=XYZ" will look for a
result variable (that is a table) named XYZ, and "/TSETUP=myFile.tbl" will
look for a text file (with a table format) named myFile.tbl. The use cases
of /TSETUP are listed below:
Case 1: /TSETUP=<file>.tbl
In this case, the given file will be treated as a table and used for the
setup of the panel.
Case 2: /TSETUP=<result table>
In this case, the local result variables will be searched for the given
table variable. If not found, then the parent result variables will be
checked.
Case 3: /TSETUP with no filename or variable name (e.g. "panel/tsetup/...")
This case is treated the same as Case 1, where <file> is the base filename
of the macro.

Any graphical controls added to the panel using the WIDGET property will be
contained in a table that can be accessed through the CONTROLS property. Thus
if the panels registry name is PANEL, the value of a gcontrol widget named FREQ
can be set with the following example line:

panel/controls=gc
...
gcontrol dval freq ...
...
set gc.FREQ.value 1.33

where the /controls=gc is a reference to the REG.PANEL.CONTROLS list. Without
the /controls=gc switch, access to controls is available as:

res REG.PANEL.CONTROLS.FREQ.value 1.33

The panes in the panel are accessible through the PANES property table. For
example, to set the title on the pane named PANE1:

panel/controls=gc/panes=WIN
...
set REG.WIN.PANE1.TITLE "My Title String"

where the /panes=WIN switch specifies an entry in the REGISTRY called WIN for
the panes. Without the /panes=WIN switch, access to panes is available as:

set REG.PANEL.PANES.PANE1.TITLE "My Title String"

Normally, each pane in the panel is named with the ID of the primitive that is
to be displayed there. This is performed by the ATTACH menu item in the
EDITPANE configuration option. All configuration items may be accessed
graphically and saved to a setup file for future use.

The panel setup configuration can be saved to a standard setup file (*.mmp), a
table setup file (*.tbl), or (as of NeXtMidas 2.9.0) a table result variable.
The default setup file saved will be a .mmp file unless the /TSETUP switch
is present, in which case it will be a .tbl. In either case, the user can
change the file type by specifying the filename (with extension of either .mmp
or .tbl) in the SAVE FILE prompt.

Since NeXtMidas 2.9.0, the user can save the setup table in the results table
for future use as a result. The result variable name will be the name of the
variable that was used in TSETUP=<result>. If no result variable table was
provided, a default result variable name of "SETUPTABLE" is used and stored at
the PARENT level.

A graphical primitive (PLOT, LIST2, etc.) with a /WIN= switch will attempt to
attach to the named object. A graphical primitive that does not have a /WIN=
switch will look in the REG.WIN table for an entry matching its /ID= value.
If not found, it will create its own window frame.

NOTE: A graphical primitive using a /WIN= that refers to a non existent pane in
a panel will have a delay before coming up and will eventually display in a new
window frame.

Multiple panels with different graphical primitives can be attached to them
using the combination of the /PANES= switch on the panel and /WIN= switch on the
graphical primitive (e.g. PLOT, LIST2). For example, to have two panels and
plots of world.prm and world.shp in each panel separately:
...
! setup two panels
panel/panes=win1/setup=1 ! 1st panel using setup file <macrofile>.mpp1
panel/panes=win2/setup=2 ! 2nd panel using setup file <macrofile>.mpp2

! attach plot of world.prm to first panel (win1) on pane1 (defined in .mpp1)
plot/win=win1.pane1 world.prm
! attach plot of world.shp to second panel (win2) on pane1 (defined in .mpp2)
plot/win=win2.pane1 world.shp
...

If the /GRID={table} switch is present, an NxM grid of evenly spaced panes is
generated regardless of the mmp file contents. The table entries are
NX - number of panes in the horizontal direction
NY - number of panes in the vertical direction
ID - id + index is the pane id
NAME - name + index is the pane name
TITLE - title + index is the pane title
TS - the title size in pixels (=0 to suppress)

This primitive also has n timers where n may be set with the /NTIMERS switch.
A timer sends messages to the macro's processMessage procedure when the timer
activates. To set up an interval timer at 2 second intervals:

nM> set REG.PANEL.TIMER(0) 2

or to trigger a single event after 10 seconds:

nM> set REG.PANEL.TIMER(0) -10

The timers respond to the MAIN macro id with the message name TIMER, the timer
number (0...n) in the info field and the current TimeOfDay in the data field.

Popping Out Graphical Primitive Panes from Macro GUIs
=====================================================
Typically, unless disabled, a user can click on the 'X' at the top-right corner
of a pane in a macro to 'POP' it out of the macro onto a stand-alone panel.
Clicking the 'X' again (or closing the panel) will 'PUSH' the panel back onto
the pane.

Since 3.1.0, users can click on the 'X' while holding the CTRL key down on the
keyboard to bring up a small menu which prompts the user to select a destination
screen/display for the 'POP'. Note that users with Xinerama displays do not
have multiple displays for this purpose. This behaviour can be disabled using
option=-AdvPushPopX for all panes on the panel command line, or setting
enableAdvancedPopOut to false in any graphical primitive.

Also since 3.1.0, the 'POP' message has been expanded. The QUALS field (Table)
can now be used to set the Display (DISP) and Bounds (X,Y,W,H) as in the
following example:
res t:loc {DISP=^gc.winNo.value,BOUNDS={X=^gc.xpos.value,Y=^gc.ypos.value,&
W=^gc.width.value,H=^gc.height.value}}
message send id=myplot name="POP" info=-1 quals=loc

Control Placement
=================
By default controls will be stacked in the left pane (pane0). The /OPTIONS
switch can be used to allow the controls to be compressed when they take up
all of the vertical space. When a group of controls is opened, selecting the
COLLAPSECONTROLS option will collapse another control group to make space for
the group just opened.

If the controls still take up all of the vertical space, a scrollbar will appear
at the bottom (Since NeXtMidas 2.5.2). This should not be used with the
COLLAPSECONTROLS option.

Control Layout Updates
======================
Typically, whenever a control is updated it indicates to the panel that the
panel needs to update the layout. Updating the layout involves placing each
control and using compression to make all the controls fit.

Since NeXtMidas 2.8.2, it is possible to set the panel to hold all the layout
updates. This is typically done when doing a large number of control updates
and the user does not want the panel to re-do the layout before all the
updates are done.
set reg.panel.holdLayout true
...<do a bunch of gcontrol updates / changes>...
set reg.panel.holdLayout false

Pane Icon Control
======================
Since NeXtMidas 3.5.4, it is possible to add a second custom icon to the left
of the PUSHPOP icon and to control the action(s) of both the PUSHPOP and the
custom icon. The custom icon can be the Shaded 'X' or any symbol supported by
nxm.sys.libg.Symbol class.
Example setting the PUSHPOP icon action to both message and PushPop, the
custom icon to DIAMOND and the custom icon action to both autoCLOSE and Message:
panel/setup/controls=gc/PUSHPOPICONACTION=PushPop|Message/&
CUSTOMICONACTION=Close|Message/CUSTOMICONSYMBOL=Diamond
Example setting the custom icon to the Shaded 'X' (with a default action of
autoCLOSE). The PUSHPOP action is also left at the default of PushPop:
panel/setup/controls=gc/CUSTOMICONSYMBOL=ShadedX

Messages:
ATTACH - TBE
BORDERS - TBE
BUTTON - TBE
CFG.ADD - TBE
CFG.LINE - TBE
CFG.PANE - TBE
COMMAND - TBE
CONTROLS - TBE
CURSOR - Sets the normal cursor for panel ("Default,Wait,Hand,Move").
DEBUG - TBE
DELETE - TBE
DOPOP - TBE
DRAG - TBE
DRAGBOX - TBE
ERROR - (OUT) If the /HEADLESS tag is not set and the Shell is
detected to be headless, an error message is sent to
the macro to enable handling of the situation to
prevent the system from appearing to hang.(Since 3.5.0)
DATA = java.awt.HeadlessException
EVENTS - TBE
EXIT - TBE
KEYPRESS - TBE
LOADFILE - Loads a setup file when given full file name.
LOADSETUP - Loads a setup file when given ID (same as /SETUP switch).
LOADSETUPTABLE - Loads the setup from a given table.
MACRO - TBE
MENU - TBE
OPTIONS - TBE
PANEL - TBE
PANEL.CFG - TBE
PIPE - TBE
POINTER - TBE
REFRESH - TBE
RESIZE - TBE
SAVEFILE - Saves a setup file (.mmp) when given full file name.
SAVERESULT - Saves setup to a results variable
SAVETABLEFILE - Saves a setup file (.tbl) when given a full file name
SHOW - TBE
SHOWN - DEPRECATED
THEME - Change the theme of the control panel and its widgets
TIMER - Message occurring at a user set interval (1 to n messages)
TITLECOLOR - TBE
TITLESIZE - TBE
TITLETEXT - TBE
WINDOW - (IN) Internal message, not for general use.

Properties:
CONTROLS - returns the table of control widgets
EVENTFILTER - sets NOMOUSE|NOKEYBOARD|NOICON|NOMOVE events masks on all
controls
PANES - returns the table of window panes
TIMER(n) - sets interval (>0) or countdown (<0) timer in seconds
WIDGET - adds a control widget to the panel's control section
OPTIONS - set various options include (see /OPTIONS switch)

Examples:
The following creates a panel with a grid of panes numbered top-to-bottom and
left-to-right, titled WIN1...WIN12.
nM> panel/grid={NX=3,NY=4,TS=12,FILL=TBLR,TITLE=WIN}

Switches:
/CONTROLS=res - Specifies result name pointing to the table of control
widgets
/CUSTOMICONACTION - Action of the custom icon MESSAGE|CLOSE. The default
action is None,except where the custom icon is the
Shaded 'X'. When the icon is the Shaded 'X', the default
action is CLOSE (autoCLOSE the command and Pane and
resize the remaining Panes to fill the space)
Since NeXtMidas 3.5.4
/CUSTOMICONSYMBOL - Symbol used as the custom icon NONE,SHADEDX, or any
Symbol supported by nxm.sys.libg.Symbol (includes any
individual character) [DEFAULT=NONE]
Since NeXtMidas 3.5.4
/EXIT= - Mask of allowed EXIT events from RETURN,MENU,MESSAGE,WINDOW
[DEFAULT=ALL if piped or WINDOW otherwise]
/GRID={table} - Creates a grid of panes inside the panel. Table keys are:
NX - Number of rows [DEFAULT=4]
NY - Number of columns [DEFAULT=4]
NAME - Prefix for each pane [DEFAULT=GP]
TITLE - Prefix for pane titles, window number appended
[DEFAULT=Pane]
TS - Font (text) size [DEFAULT=10]
FILL - LRTB=Left-to-right then top-to-bottom
TBLR=Top-to-bottom then left-to-right
/HEADLESS - Do not show a window if TRUE [DEF=FALSE]
/HIDEWIDGET - Experimental switch to allow hidden widgets (ones not
supported by the current layer type) to be removed
Experimental switches can be removed in a future release.
[DEFAULT=FALSE]
/INLINE - Remove borders to allow embedding in another display
[DEFAULT=TRUE]
/JSETUP=name - Uses Java class as a setup file (e.g. SD360/jsetup)
/LOGGER - Enables display of INFO, WARN, and ERROR messages in the
bottom fixed region
/MSGID= - Message ID to which to send messages
/NOPUSHPOP - Disables user Push/Pop for a window (such as clicking the
'X' when popped out). This does not affect Push/Pop
messages from a macro).
/NOALTTITLE - Disables automatic updates to the status/title bar text
from events such as mouse hovers. This will apply to ALL
commands (plots, gcontrols, etc) in the control panel.
Since 3.3.0.
/NTIMERS - Number of timers [DEFAULT=3]
/OPTIONS=mask - Sets the options for the panel (if present).
+RotateTabs - Tabs rotate when selected.
+PushPopX - Display the Push/Pop 'X' for panes.
[enabled by default]
+CompressControls - Compress Controls to fit in window.
[enabled by default]
+CollapseControls - Collapse Control Groups to fit.
+LockSetup - Do not allow users to change setup.
+LockControls - Do not allow users to move controls.
+AdvPushPopX - (Since 3.1.0) Enable Pop Menu on
CTRl+click 'X' [enabled by default]
/PANES=res - Specifies registry name to contain the table of panes
[DEFAULT=WIN]
/PUSHPOPICONACTION - Action of the PUSHPOP icon PUSHPOP|MESSAGE
[DEFAULT=PUSHPOP] Since NeXtMidas 3.5.4
/PUSHPOPICONSYMBOL - For Internal Use Only: Symbol used as the PUSHPOP icon
PUSHPOP or SHADEDX. Allows users to revert back to the
old Shaded 'X' for the PUSHPOP icon [DEFAULT=PUSHPOP]
Since NeXtMidas 3.5.4
/SETUP=opt - Uses alternate macro setup file. Use /JSETUP to use a
Java class instead. [DEFAULT=Uses .mmp file]
/TABS - Deprecated - Use the /OPTIONS switch.
/THEME=name - Change theme to one of the predefined themes available in
nxm.sys.libg.Theme (DeskTop,Default,WoB,GoB,BoW,Browser,
Gear1,Gear2,Gear3,Gear4,Nak,etc.) [DEFAULT=ENV.THEME]
/THEME={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
Acceptable values for all table keys are name or number
strings as specified in
nxm.sys.libg.MColor.getColor(String).
(see nxm.sys.libg.MColor).
/TSETUP=tbl - Uses a Table as a setup file (can be a .tbl file).
/WMSGID= - Message ID to which to send WINDOW event messages. If not
present WINDOW message is processed by the PANEL
primitive [DEFAULT=null].
/WPOS= - Set the position of the plot when it opens, use the
syntax "WPOS=(X,Y,Width,Height)" where all values are in
pixels.

See Also: nxm.sys.libg.MColor, nxm.sys.libg.Theme, nxm.sys.libg.Symbol

</pre>

[[Category:NXM_Explain]]

PANEL - Revision history

ConvertBot: draws a bare window with facilities for overlaying other windows