POPUP

From ICE Enterprises
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).