compile insert Msg_Equates
* used by Msg()
******************************************************************************
*
* Product    :  OpenInsight
* Version    :  3.5
*
* History    :  (date, initials, notes)
*   12/15/95  apk  Original programmer.
*   02/26/96  cp   Changed OK return value to "" from 0 (backwards compat.)
*   03/28/96  cp   Added MHELP$, MREQRESP$, and MBEEP$ fields
*                  Commented message structure and instructions
*   06/24/97  cp   Added G (gauge) type, removed unused equates
******************************************************************************
declare subroutine Msg          ;* Msg(Parent, MsgDef [, MsgKey, Instruction, Params])
declare function   Msg          ;* Ans = Msg(Parent, MsgDef [, MsgKey, Instruction, Params])
* message structure field definitions
equ MTEXT$          to 1        ;* the text to display in the message, multiple lines delimited by @tm, cr/lf, or "|"
equ MTYPE$          to 2        ;* the message type, defaults to "BO" (see below)
equ MMODAL$         to 3        ;* modality of message, defaults to "A" (see below)
equ MICON$          to 4        ;* icon to display (see below)
equ MDEFBTN$        to 5        ;* default button (1 for first, 2 for second, etc.)
equ MCOL$           to 6        ;* message h-pos in pixels, or -2 (center screen, the default), -1 (center parent)
equ MROW$           to 7        ;* message v-pos in pixels
equ MJUST$          to 8        ;* justification:  T (text, the default), L (left), R (right), C (center)
equ MBKCOLOR$       to 9        ;* background color (RGB value, @vm-delimited), see Utility("CHOOSECOLOR")
equ MFGCOLOR$       to 10       ;* foreground color (RGB value, @vm-delimited), see Utility("CHOOSECOLOR")
equ MTEXTWIDTH$     to 11       ;* the message width (or the response field width for response messages)
equ MCAPTION$       to 12       ;* the message title
equ MVALID$         to 13       ;* for response messages, this is the validation pattern (ie. (MD0) for integer)
equ MDEFINPUT$      to 14       ;* for reponse messages, this is the default response
equ MMASKINPUT$     to 15       ;* boolean, true for password (masked) input, false (default) for readable input
equ MBITMAP$        to 16       ;* name of a bitmap registered in repository (as it appears in the outliner)
equ MCLIPBMP$       to 17       ;* boolean, true to clip bitmaps, false to resize (see IMAGECLIP property)
equ MFONT$          to 18       ;* font structure for the text of the message
equ MLITERAL$       to 19       ;* boolean, defaults to false, true specifies that default value is a function (see below)
equ MHELP$          to 20       ;* help button, Type:@vm:Specifier:@vm:Text (see below), defaults to null (no help)
equ MREQRESP$       to 21       ;* boolean, for type "R" messages, false allows nulls (default) while true doesn't
equ MBEEP$          to 22       ;* integer, specifies beep (see MessageBeep in the Windows API)
equ MEXTENT$        to 23       ;* integer, specifies extent of the gauge (number of items to process for type="G")
equ MNUMFIELDS$     to 23
* MTYPE$ details:
*
* there are six base types, B (buttons), R (response), U (up), and D (down),
* T (timed), and G (gauge)
*
* the button type has several pre-defined button sets which are localized
* using entries from the SYSTEM_RESOURCES record in the SYSENV table; for
* non-standard labels, the buttons can be specified in a comma-delimited
* list, like "B&One,&Two,&Three" (where the & specifies the accelerator)
*
*   B Type  Description
*   ------  --------------------
*   BO      OK
*   BOC     OK/Cancel
*   BNY     Yes/No
*   BNYC    Yes/No/Cancel
*   BRC     Retry/Cancel
*   BAR     Abort/Retry
*   BARI    Abort/Retry/Ignore
*   B{list} User-defined buttons
*
* the response type displays an edit field and OK and Cancel buttons;
* the optional sub-types are C (upper-case only) and E (escape or
* cancel button returns escape character instead of default response);
* for example, the following types are valid:  "R", "RC", "RE", "RCE"
*
* for B and R types, the type can be preceded with an N to specify that
* the default value for the message is to be returned without the message
* being displayed; this is one way to change messages from interactive
* to non-interactive for batch processes; for example, instead of "BARI",
* pass "NBARI" (meaning don't display the abort/retry/ignore message)
*
* to display a message while processing, use the "U" type:
*
*   Def = ""
*   Def<MTEXT$> = "Processing..."
*   Def<MTYPE$> = "U"
*   MsgUp = Msg(@window, Def)   ;* display the processing message
*   ...
*   Msg(@window, MsgUp)         ;* take down the processing message
*
* to display a message for a specific length of time, use the "T" type:
*
*   Def = ""
*   Def<MTEXT$> = "Waiting..."
*   Def<MTYPE$> = "T2"          ;* 2-second message
*   Msg(@window, Def)
*
* the optional sub-type for T type is A (asynchronous), which displays
* the message and returns (allowing processing to continue) and takes
* the message down after the specified period of time; since this relies
* on a timer event, your event code must either complete within the
* specified period of time or you must regularly use Yield() to allow
* the processing of posted events (like the timer):
*
*   Def = ""
*   Def<MTYPE$> = "TA5"         ;* 5-second splash-screen
*   Msg(@window, Def, "SPLASHSCREEN")
*   loop
*     Done = AppLogonProcessing()
*     Yield()
*   until Done
*   repeat
*
* to display a gauge (percent bar), use the "G" type; sub-types are C (show
* cancel button) and Y (yield on each cycle):
*
*   Def = ""
*   Def<MCAPTION$> = "Processing Orders..."
*   Def<MTYPE$   > = "GC"
*   Def<MEXTENT$ > = OrderCnt
*   MsgUp = Msg(@window, Def)
*   for Order = 1 to OrderCnt
*     gosub ProcessOrder
*   * update the gauge and check if cancel was pressed
*   while Msg(@window, MsgUp, Order, MSGINSTUPDATE$)
*   next Order
*   Msg(@window, MsgUp)         ;* take down the gauge
* MMODAL$ detail:
*
*   Code         Modality     Description
*   -----------  -----------  -----------------------------
*   W            Window       only the parent is disabled
*   A (default)  Application  all OI windows are disabled
*   S            System       all applications are disabled
* MICON$ detail:
*
*   Code  Icon
*   ----  ---------------
*   null  None
*   *     Asterisk (Info)
*   ?     Question
*   !     Exclaim (Warning)
*   H     Halt (Stop sign)
*   B     User-specified bitmap (specified in MBITMAP$ field)
* MLITERAL$ details (applies only to response type messages):
*
* if MLITERAL$ is true, the Msg() function assumes that the default value is
* the name of a function which returns the default value for the message;
* for example, if you wrote a function called CURRENTUSER which returned
* the user name of the current user, you could specify CURRENTUSER as the
* default value (MDEFINPUT$) and set MLITERAL$ to true, so that the current
* user name would be the default value for the message; parameters are
* passed to the specified function depending on the number of parameters
* that are supported by the function:
*
*   # Params   Values Passed
*   ---------  --------------
*   0          None
*   1          MsgKey
*   2 or more  MsgKey, MsgDef
* MHELP$ details:
*
*   Type  Description          Specifier
*   ----  -------------        -----------------
*   Q     QuickHelp (AppNote)  Name of AppNote
*   M     Message              Name of Message
*   H     WinHelp              HelpFile,HelpID
*   S     Stored Procedure     ProcName[,Param1]
*
*   Note:  Specify the AppNote, Message, HelpFile, or ProcName as it appears
*          in the repository outliner.  For example, the OINSIGHT.HLP file is
*          registered as OINSIGHT, so specify the HelpFile as "OINSIGHT" (look
*          in the outline under "General", "Windows Components", "Help Files")
*
*   Text defaults to "&Help" or a localized equivalent
* Replaceable message parameters:
*
*   Msg(@window, "Hello, %1%, how are you %2%?", "", "", @username: @fm: "today")
* Msg() function instruction values
equ MSGINSTSTART$   to 1         ;* (default instruction)
equ MSGINSTREAD$    to 2         ;* bErr = Msg("", MsgDef, MsgID, MSGINSTREAD$)
equ MSGINSTWRITE$   to 3         ;* bErr = Msg("", MsgDef, MsgID, MSGINSTWRITE$)
equ MSGINSTLOCK$    to 4         ;* bErr = Msg("", "", MsgID, MSGINSTLOCK$)
equ MSGINSTUNLOCK$  to 5         ;* bErr = Msg("", "", MsgID, MSGINSTUNLOCK$)
equ MSGINSTBUTTON$  to 6         ;* reserved
equ MSGINSTCREATE$  to 7         ;* reserved
equ MSGINSTRESPCHG$ to 8         ;* reserved
equ MSGINSTCLOSE$   to 9         ;* reserved
equ MSGINSTTIMER$   to 10        ;* reserved
equ MSGINSTHELP$    to 11        ;* reserved
equ MSGINSTUPDATE$  to 12        ;* (see above)
* Msg() function return values from MSGINSTSTART$
equ RET_OK$         to ""
equ RET_CANCEL$     to \1B\    ;* escape character
equ RET_YES$        to 1
equ RET_NO$         to 0
equ RET_ABORT$      to 1
equ RET_RETRY$      to 2
equ RET_IGNORE$     to 3
* misc strings
equ MSGTYPE$        to "MSG"
equ MSGCLASS$       to ""

See Also

Msg()

  • No labels