# gMsgBox

Definition: | include xpGUI.e gMsgBox(gdx parent, [rtn handler=NULL,] string [title="Error",] [msg, ] [attributes="", ] dword_seq args={})
Description: | INCOMPLETE: [?requires a new paranormalise_rtmaa() routine?] ? Does not resize or reposition or reparent correctly on subsequent invocations. [should probably destroy/resuse controls/gdx entries...] ? The OK button is not right-aligned. The popup is not [yet / properly or in fact at all] modal. ? Parameters not finalised, no serious attempt at wordwrap or an icon or any other attributes as yet. ? Multiple buttons (plus a callback to handle which clicked) would be one obviously desired enhancement. Shows a modal dialog containing a message with (by default) an OK button. ? parent: Identifier of the dialog to use as a parent, primarily to control focus when the message box is closed. Can be NULL. ? I might yet ditch parent & use the currently active window, and allow stacked msgboxen... ? handler: (optional) A procedure to be invoked when a button is clicked, see HANDLER. ? action: a standard ACTION, with USER_DATA set to an integer, 1..length(BUTTONS)? title: (optional) Text to be shown on the popup window’s header. Default "Error". msg: Text to be shown on the label, a msg=sprintf(msg,args) may occur when args!={}, can be set via MSG. ? For more information on the attributes and args parameters see gSetAttributes(), and below. At least one of msg or attributes [with MSG set] must be specified. This is a paranormalised routine (see technicalia)
pwa/p2js: | Not yet supported....
Example: |
    --? see demo\xpGUI\gTreeView.exw for a better example (when F1|2 pressed)
    include xpGUI.e
    gMsgBox(NULL,`gMsgBox`,`This is a simple %s window.`,{`message box`})
    gMainLoop()
Notes: | This is a relatively straightforward (hll) convenience wrapper for a gDialog containing a [gCanvas,] gLabel, and one or more gButton. Should this not meet your precise needs, just simply roll your own. For JavaScript compatibility reasons this does not "stop the world", instead control returns immediately and normal processing continues. Attempts to display more than one gMsgBox at the same time will result in a fatal error. ?? b1 is set as the "DEFAULTENTER". The "DEFAULTESC" is set to the last non-NULL of b1, b2, and b3. ??X Returns 1, 2 or 3 to indicate which button was selected. (this text nicked from IupAlarm...)
Attributes: | ? Not yet implemented. Since the application never gets to see the prvate gdx being used, these can only be set via the implicit gSetAttributes() of the initial call, likewise all are effectively non-readable.
TITLE | (optional) The popup title. Default: "Error".
IMAGE | (optional) A gImage to be placed before the MSG.
MSG | (not optional, but can be set via the msg parameter) The main/central text of the popup.
BUTTONS | (optional) A comma-delimited string containing the text of any button(s) to be shown. Default: "OK". ? An error occurs if more than one button (which just closes) is present but no HANDLER has been specified.
Handlers: | ? ACTION...?
?? HANDLER | procedure handler(integer btn[, string title]) btn: a 1-based index corresponding to BUTTONS. title: (optional) the text corresponding to BUTTONS. The popup is automatically closed before the handler is invoked. Can be set via the handler parameter or as "HANDLER" using an implicit leading '=' variant of gSetAttributes() - since the application never gets to see the prvate gdx being used, it cannot be set via gSetHandler(). An error occurs when there are multiple buttons but no handler has been specified. A common handler can be used for multiple popups, just so long as it can determine unequivocably what btn/title actually means in the current context (via some saved state should need be).
Technicalia | (DEV to be completed/implemented/tested) As this is a paranormalised function, and with no expectation that you should memorise this lot, except maybe "prtmaa", you can assume that all of the following are potentially perfectly valid, with the fairly obvious restrictions that any parameters must be in strict prtmaa-order, with parent non-optional, and msg or MSG must be set. While NULL can be used for the parent, you should then fully expect the keyboard focus is quite likely to go all a bit wonky. Note that args can apply to msg or attributes, and an implicit leading '=' variant of gSetAttributes() must be used to set an IMAGE.
                            gMsgBox(parent, attributes)
                            gMsgBox(parent, attributes, args)
                            gMsgBox(parent, msg)
                            gMsgBox(parent, msg, args)
                            gMsgBox(parent, msg, attributes)
                            gMsgBox(parent, msg, attributes, args)
    --X                     gMsgBox(parent, title, attributes)                          -- (see note two)
    --X                     gMsgBox(parent, title, attributes, args)                    --       ""
                            gMsgBox(parent, title, msg)
                            gMsgBox(parent, title, msg, args)
                            gMsgBox(parent, title, msg, attributes)
                            gMsgBox(parent, title, msg, attributes, args)
                            gMsgBox(parent, handler, attributes)
                            gMsgBox(parent, handler, attributes, args)
                            gMsgBox(parent, handler, msg)
                            gMsgBox(parent, handler, msg, args)
                            gMsgBox(parent, handler, msg, attributes)
                            gMsgBox(parent, handler, msg, attributes, args)
    --X                     gMsgBox(parent, handler, title, attributes)                 -- (see note two)
    --X                     gMsgBox(parent, handler, title, attributes, args)           --       ""
                            gMsgBox(parent, handler, title, msg)
                            gMsgBox(parent, handler, title, msg, args)
                            gMsgBox(parent, handler, title, msg, attributes)
                            gMsgBox(parent, handler, title, msg, attributes, args)      -- (the full set)
Note that in practice most parameters are actually defined as object, but everything is verified to be of the documented types, after being repositioned via xpGUI.e/paranormalise_rtmaa(). Also note the parent is non-optional and takes no part in the paranormalisation handling. A msg is distinguished from attributes by the presence of an '=', as per here, and that is used to determine which of the above cases actually applies. Since title has a default but msg does not, a single ('='-less) string is taken to be msg not title, and there is no way to set title as a normal parameter with MSG in attributes, and attempts to do so would probably set MSG twice and leave you with the default TITLE of "Error".