Message, MsgBox & MsgBox0 Commands and Functions

Purpose

Displays a message in a dialog box, waits for the user to click a button, and returns a value indicating which button the user clicked.

Syntax

retval = MsgBox[0](prompt)

retval = MsgBox(prompt[, flags][, title][, helpfile, context])

MsgBox[0] prompt[, flags][, title][, helpfile, context][, retval]

Message prompt[, title][, flags][, retval]

[retval =] Message(prompt)

retval = Message(prompt, title, flags)

prompt, title, helpfile: sexp
retval, flags, context: iexp

Description

MsgBox displays a message dialog box which is owned by the current active Form while MsgBox0 doesn't have an owner, the handle of the parent being set to 0. MsgBox0 is particularly useful when the owner-owned relationship isn't wanted and the message box is not forced in the foreground of the form. Whether by design or error, GFA Basic only supports the MsgBox0 function with a single parameter, but it does support the MsgBox0 command in full.

The MsgBox[0] syntax has these arguments:

When both helpfile and context are provided a Help button is added and context-sensitive Help is provided for the dialog box. However, no value is returned until one of the other buttons is clicked. In addition, when the Help button is visible, the user can press F1 to view the Help topic (WinHlp) corresponding to the context.

NOTE: With the demise of the Winhlp (.hlp) file format, helpfile and context will not work on Windows Vista (2007) onwards (unless you have installed a older version of WinHlp32.exe). To add help to a message box, see the examples in Known Issues below.

If the dialog box displays a Cancel button, pressing the ESC key has the same effect as clicking Cancel.

Message is similar to MsgBox and uses the same parameter values with the main difference being the omission of a link to a WinHlp help file through helpfile and context; instead, add MB_HELP to flags and catch the returned WM_HELP message in the parent window's _Message event - the pointer to the HELPINFO structure is stored in wParam. (Note: As with MsgBox, from Windows Vista onwards, trying to access a WinHlp file can cause a fatal error - see below for workarounds.)

Formatting & Button Options

Any constant marked with an asterisk (*) is not recognised as an internal value and will need to be either added as a constant with your program or used as a numerical value with the MsgBox function and/or command.

Button Options

The following set the array of buttons used in the message box (See example 1 in Known Issues to see how to customise the button captions):

It is possible to specify is the default (has focus) with one of the following:

If the button specified as default is not present, focus is shifted to first Button

Icon Options

The icon to be displayed in the mesage box is determined by:

Modal Settings

The following constants allow you to change to Modal status of the window:

Miscellaneous Settings

Below are more settings that can be combined with those above:

Return values

The following are accepted return values:

Example

Local a%, b$, c$, n%

a% = MB_ABORTRETRYIGNORE

b$ = "This is a message"

c$ = "GFA-BASIC 32"

n% = MsgBox(b$, a%, c$)

MsgBox c$, , , , , n%

Message b$, "", a%, n%

Remarks

For an alternative style of message box, see GFA Basic's own version called Alert.

It is possible to display a message box with a check box which gives the option not to show the message again by using the SHMessageBoxCheck() API. A quick example is below:

Declare Function SHMessageBoxCheck Lib "Shlwapi" Alias "SHMessageBoxCheckA" (ByVal hwnd As Handle, ByVal Prompt As String, _

ByVal Title As String, ByVal Flags As Long, ByVal DefaultID As Long, ByVal RegVal As String)

OpenW 1

Local r% = SHMessageBoxCheck(Win_1.hWnd, "Do you want to save this file?", "Save File?", MB_YESNO, IDYES, "Test")

Message "Return Value was" & r% & #13#10 & "Do you want to see the new registry value?", "", MB_YESNO, r%

If r% = IDYES

SaveSetting "HKCU\software\microsoft\windows\currentversion\applets\regedit", "", "lastkey", Str, _

"HKCU\Software\Microsoft\Windows\CurrentVersion\Explorer\DontShowMeThisDialogAgain"

~ShellExec("regedit.exe")

EndIf

If the checkbox is ticked when the message box closes, a Registry key named after RegVal is added to the HKCU\Software\Microsoft\Windows\CurrentVersion\Explorer\DontShowMeThisDialogAgain key with the value 'NO'. To show the message again, either delete this key or change the value to 'YES'.

For more details on SHMessageBoxCheck, see MSDN.

MsgBox (and MsgBox0) uses Me as a parent and is displayed on Me’s (usually the curernt) monitor, except in GLLs, where Me is unavailable, when MsgBox0 alone should used instead.

Known Issues

As noted above, with MsgBox[0] from Windows Vista onwards, the helpfile and context parameters no longer link to the deprecated WinHlp32.exe help files. Similarly, neither does using Message or the internally declared MessageBox() with the MB_HELP flag; in fact, this should not be used as, in certain circumstances, it can cause serious errors.

There are two alternatives to this problem:

  1. The first is a workaround which converts one of the other buttons into a Help button and uses the return value to branch off to the help page. This example is especially interesting as it also shows how to customise the button names.

    // Acknowledgements to Peter Heinzig

    Form F0 = , , , 400, 300 : DoEvents

    RedrawMsgBox:

    Ocx Timer Tim : Tim.Interval = 3 : Tim.Enabled = 1

    If MsgBox("Tralala", MB_OKCANCEL, " ") = IDCANCEL // Cancel is now Help

    // Call your helpfile/page.

    GoTo RedrawMsgBox

    EndIf

    F0.Close

     

    Sub Tim_Timer // Use to Change text in messagebox

    ~SendDlgItemMessage(GetActiveWindow(), IDCANCEL, WM_SETTEXT, 0, "Help") // "Cancel" => "Help"

    Set Tim = Nothing // Cancel Timer as task done

    EndSub

  2. The second method is longer and uses the MessageBoxIndirect() API:

    Type MSGBOXPARAMS

    - Long Size, Owner, hInstance

    - Long Text, Caption, Style, Icon, ContextHelpId

    - Long MsgBoxCallBack, LanguageId

    EndType

    OpenW 1 : Debug.Show

    Local mbp As MSGBOXPARAMS, a$ = "This is a trial MessageBox", b$ = "Trial Help"

    mbp.Size = SizeOf(MSGBOXPARAMS)

    mbp.Owner = Win_1.hWnd

    mbp.hInstance = Null

    mbp.Text = V:a$

    mbp.Caption = V:b$

    mbp.Style = MB_OK | MB_HELP

    mbp.Icon = Null

    mbp.ContextHelpId = 12

    mbp.MsgBoxCallBack = ProcAddr(HelpRoutine)

    Print MessageBoxIndirect(mbp)

    Do : Sleep : Until Win_1 Is Nothing

     

    Procedure HelpRoutine(helpptr%)

    Local hi As HELPINFO

    MemCpy V:hi, helpptr%, SizeOf(HELPINFO)

    Debug hi.ContextId

    Type HELPINFO

    - Long Size, ContextType, CtrlId

    - Long ItemHandle, ContextId

    MousePos As POINT

    EndType

    Type POINT

    - Long x, y

    EndType

    EndProcedure

    For more information on the possible values in the MSGBOXPARAMS structure, see MSDN.

For more information on linking to HTML Help Files, see Accessing HTML Help Files.

See Also

Alert, Prompt, CommDlg, DlgCenter, DlgCenterHook.

{Created by Sjouke Hamstra; Last updated: 23/02/2022 by James Gaite}