ConvertBot: Creates a pop-up window.

2020-04-27T22:04:36Z

Creates a pop-up window.

New page

Creates a pop-up window.
<pre>
<RESULT> - The result name in which to capture the user's input. [DEF=<null>]
<FUNC> - The name of the pop-up function. See FUNCTIONS below. [DEF=YESNO]
<MESSAGE> - The message to prompt the user with. [DEF="A Popup"]
<TYPE> - The type of popup message (ERR,INFO,WARN,QUEST,PLAIN) [DEF=PLAIN]
<OPTIONS> - The options for a <FUNC>=Choice/Buttons/Mask [Def=""]
<DEFAULTS> - The default values for <FUNC>=Text/Mask/Login [Def=""]

Tag-only parameters:
[FILTER] - The file name filter to use with the <FUNC>=FILE. [Def="*"]
[AUXLIST] - The AUX list to show with the <FUNC>=FILE. [Def=AUX.READ]
[PATHOPT] - The output option for including the path when
<FUNC>=FILE is used. [Def=AuxQual]
FullPath - Display full path to file
NoPath - Display filename without path
AuxPath - Display "<aux>/<file"
AuxQual - Display "<file{AUX=<aux>}"

This command creates different types of pop-up windows through an easy-to-use
interface to Java's JOptionPane class and the related Swing pop-ups. This is
intended for use by macros only. Primitives should use the Swing classes
directly.

For all functions, if the user chooses "Cancel" or closes the pop-up window
without selecting an option the result <RESULT> will be set to "CANCEL".

The <TYPE> determines how the message is handled (and more specifically defines
the icon used). Use TYPE="PLAIN" to get an "undecorated" (no icon) message.
The available types are:
TYPE="ERRor" The message is an error message.
TYPE="INFOrmation" The message is an info message.
TYPE="WARNing" The message is a warning message.
TYPE="QUESTion" The message is a question.
TYPE="PLAIN" Do not use one of the above types.

The uppercase letters in <TYPE> names indicates minimum required text.

+--------------------------------------------------------------------------+
| Note: In NeXtMidas 2.2.0 the POPUP intrinsic was moved from UCL to SYS. |
| In NeXtMidas 2.3.0 the POPUP intrinsic was converted to a primitive|
| so it could be used in a non-blocking context. This explain file |
| documents the post-2.3.0 functionality. While the new version of |
| POPUP is backwards-compatible, macros that use the new features |
| (including /BLOCKING=, /WPOS=, messages, <FUNC>=Login/Mask/Alert |
| /Buttons, default values, etc.) will not run properly in old |
| versions of NeXtMidas. |
+--------------------------------------------------------------------------+

FUNCTIONS:
BUTTONS - Creates a popup with a set of buttons. <OPTIONS> is a comma-
separated list of button names. The name of the button pressed
will be put into result <RESULT>.

CHOICE - Creates a choice pop-up window where the user can choose between
a given set of choices <OPTIONS>. The user's entry will be put
into result <RESULT>. (<OPTIONS> is a comma-separated list of
options.)

COLOR - Creates a color-selection window where the user can choose a
color from a palate. The hex value of the color will be placed
into result <RESULT> (in 0x+Alpha+RGB format).

FILE - Same as <FUNC>="FILE/M"

FILE/J - TBD: A Java-friendly file selection box where the user can
choose a file from the popup. This differs from FILE/M in
that it only supports files on the local file system. If
[PATHOPT] is specified, it must be equal to "FullPath".

FILE/M - A Midas-friendly AUX-aware file selection box where the user
can choose a file from the popup.

LOGIN - Brings up a login window which prompts for user ID and password.
<DEFAULTS> can be used to set a default value for the user ID.
A string will be returned in table form with the values input
("{USER=<user>,PASS=<pass>}").

MASK/S - Creates a popup with a set of check boxes for a user to select
from. <OPTIONS> is a comma-separated list of option names. The
mask value for the options set will be put into result <RESULT>
(e.g. "|A|B|C|"). The <DEFAULTS> can be used to set the default
mask value (e.g. "|A|B|"). (MASK/S was added in NeXtMidas 2.5.0)

MASK - Similar to MASK/S except that it is limited to 32 input options.
This limitation is due to the INFO= field for the message being
set to the 32-bit integer mask value matching the selected
options.

*** Always use MASK/S unless you need the integer mask. ***

PASSWORD - Creates a password text-entry pop-up window. This is identical
to TEXT, except that when the user types the password it will
show up as stars ("***"). Use the LOGIN function to prompt for
both user name and password.

OK - Presents the message with only an "Ok" button.

OKCANCEL - Same as to FUNC="Ok" but with an added "Cancel" button.

TEXT - Creates a text-entry pop-up window. The user's entry will be put
into result <RESULT>. <DEFAULTS> can be used to provide an
initial value for the input.

YESNO - Creates a popup with the message <MESSAGE> and the buttons "Yes"
and "No". The name of the button pressed will be put into result
<RESULT>.

YESNOCANCEL - Same as to FUNC="YesNo" but with an added "Cancel" button.

NOTES:
* If the input is canceled the value will be set to "CANCEL".

* If the user closes the window by clicking on the 'X' in the upper corner of
the window it will be treated as a cancel even if no cancel button is shown.
(This even applies to <FUNC>=Alert which has no buttons!)

* If the user closes the window by clicking the right mouse button (RMB) on
the dialog box (when /OPTIONS=RmbOk) it will be treated as an "Ok" even if
no "Ok" button is shown.

MESSAGES:
Messages Sent
<MsgName> - Message sent when popup is closed (sent only if /MSGID= is
set). The /MSGNAME= switch sets the name of the message.
The message's DATA field will be set to the value of the
user input or "CANCEL" if input was canceled. The INFO field
will be set to:
INFO=-2 - Input canceled by message.
INFO=-1 - Input canceled by user.
INFO=0 - Normal input from user.
INFO=<mask> - Mask value as integer for <FUNC>=MASK (but
not MASK/S)
INFO=<num> - Choice index (1..N) for <FUNC>=Choice/Buttons
INFO=<clr> - RGB value of color for <FUNC>=Color
(Note that in the case of <FUNC>=Mask and <FUNC>=Color INFO
could be set to a negative value even if the input was not
canceled. For these check to see if DATA is set to "CANCEL").

Messages Received
CANCEL - Cancels input from the dialog box. (The INFO and DATA fields
are ignored.)

EXAMPLES:
1. Running from the command line.
popup name Text "What is your name?" Quest "^env.user"
popup quest Text "What is quest?" Quest
popup color Choice "What is your favorite color?" Quest "Red,Green,Blue"

2. Running inside a processMessage, block both user interaction (Mouse) and
the macro (Macro).
popup/blocking="Mouse|Macro" &
SAVEFILE YesNo "Save file before exit?" "Question"

3. Running inside a processMessage, block user interaction (Mouse) but not
the rest of the macro (Macro).
popup/blocking=Mouse/msgid=main/msgname="CONNECT" ,, Login &
"Enter user is and pass for database access." ,, "^env.user"

4. Show a popup with a default value. It should come up under the mouse.
popup/wpos="Mouse" fname Text "New file name" Quest "^defName"

5. THIS WON'T WORK: Show a non-blocking macro and then use the result it set.
popup/blocking=None myres YesNo "Are you sure?" "Question"
if myres eqs yes then
...
else
...
endif
This will not work because POPUP will return immediately if /BLOCKING=None
and the value of myres will not be set until later. To make this example
work, use /BLOCKING="Macro" or /BLOCKING="Macro|Mouse".

6. Create a popup message but limit the width of the text to 10 characters
per line.
popup/popwidth=10 mypopup yesnocancel "Do you believe in the magic of &
a young girls heart?" question "" ""

SWITCHES:
/BG - Run the primitive backgrounded (this overrides /BLOCKING and
runs the primitive without blocking the macro). [DEF=FALSE]
/BLOCKING= - Blocking options (NeXtMidas 2.2.0 functionality matches
/BLOCKING=Macro, use /BLOCKING=None for none or /BLOCKING=Def
for default): [DEF=Mouse]
Macro - Block execution of the macro while waiting for
input (user clicks in the panel will be added to
the message queue for processing later).
Mouse - Block user interaction in the rest of the panel
while waiting for input (any user clicks in the
panel will be ignored).
/CANCELMSG - Send a message even when CANCEL button is chosen [DEF=FALSE]
/MSGID= - If set the popup will send a message to the named command with
the user input (usually /MSGID=MAIN). [DEF=<not_set>]
/MSGNAME= - The name for message (only with /MSGID switch). [Def=POPUP]
/POPWIDTH= - (2.7.3) Sets the max width (per line)of the text message in
the popup.
/TITLE= - Set the window title [DEF=NeXtMidas or the macro name]
/WIN= - Sets the parent window. [DEF=PANEL]
/WPOS= - Sets the position of the popup: [DEF=CENTER]
Center - The popup is automatically sized and centered
over the panel.
Mouse - The popup is automatically sized positioned
under the mouse.
(x,y) - The popup is automatically sized positioned at
the given (x,y) coordinate (relative to panel).
(x,y,w,h) - The popup is manually sized and positioned with
the given coordinates (x,y) and size (w,h).

</pre>

[[Category:NXM_Explain]]

POPUP - Revision history

ConvertBot: Creates a pop-up window.