POPUP
Jump to navigation
Jump to search
Creates a pop-up window.
<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).