A.3.6.4 Displaying Dialogs

The INF script language has built-in commands, dialog templates, and shell scripts that provide a mechanism for displaying simple message box dialogs. To display custom dialogs, create a DLL that displays the dialog and returns the user’s input.

The subroutn.inf file located in the Windows NT System32 directory contains a SetupMessage shell section that displays a message box dialog. Call SetupMessage from a driver’s oemsetup.inf file using the following syntax:

shell “subroutn.inf” SetupMessage LangID Template Message

LangID

Specifies the language in which messages are displayed, for example, ENG, SPN. You can use the STF_LANGUAGE variable, which is set by Setup to specify the language selected by the user or the default language on the system.

Template

Specifies the number of buttons, the default button, and the icon. Specify one of the following:

WARNING

Displays OK and Cancel buttons, and the ! icon. The Cancel button is the default.

STATUS

Displays an OK button and the Info icon.

NONFATAL

Displays an OK button and the ! icon.

FATAL

Displays an OK button and the Stop icon

Message

Specifies the text to display.

SetupMessage returns two values. The first return value indicates success or failure. It returns STATUS_SUCCESSFUL, STATUS_FAILURE, or STATUS_NOLANGUAGE if the LangID argument specifies an unsupported language. If the first return value is STATUS_SUCCESSFUL, the second return value indicates the button pressed (either OK or CANCEL).

For example, these lines from an INF script display the dialog shown below, and handle the return values:

shell "subroutn.inf" SetupMessage $(!STF_LANGUAGE) WARNING+
              "Looks like trouble. Do you want to continue?"
ifstr(i) $($R0) != STATUS_SUCCESSFUL
    goto HandleError
endif
ifstr(i) $($R1) == "OK"
    goto ContinueOperation
else-ifstr(i) $($R1) == "CANCEL"
    goto BailOut
endif
 

For additional customization of the message box dialog, you can use the ui start command as shown in the following example. Note that the string specified after ui start is required, but has no significance.

read-syms CustomMessageDlg      ; setup the message box variables
ui start "CustomMessageBox"
ifstr(i) $(DLGEVENT) == "ABORT" ; DLGEVENT indicates button pressed
    goto AbortProcedure
else-ifstr(i) $(DLGEVENT) == "RETRY"
    goto RetryProcedure
else-ifstr(i) $(DLGEVENT) == "IGNORE"
    goto IgnoreProcedure
else
    exit
endif
 
[CustomMessageDlg]
DlgType = "MessageBox"
    STF_MB_TITLE = "Message Box Dialog"
    STF_MB_TEXT  = "Message Text"
    STF_MB_TYPE  = 6    ; display Abort, Retry, and Ignore buttons
    STF_MB_ICON  = 5    ; ! icon
    STF_MB_DEF   = 2    ; default button is Retry
 

For the MessageBox dialog, the STF_MB_TITLE variable is optional, but all other variables in the following table must be set. Determine the button pressed by examining the DLGEVENT variable, which is set to one of the following strings: “ABORT”, “CANCEL”, “IGNORE”, “NO”, “OK”, “RETRY”, or “YES”.

DlgType = MessageBox

STF_MB_TITLE = Title

Specifies the title of the dialog box. Can be blank.

STF_MB_TEXT = Message

Specifies the message text.

STF_MB_TYPE = Type

Specifies the combination of buttons. Type is one of the following:

1 OK button

2 OK and Cancel buttons

3 Yes and No buttons

4 Yes, No, and Cancel buttons

5 Retry and Cancel buttons

6 Abort, Retry, and Ignore buttons

STF_MB_DEF

Specifies the default button (1, 2, or 3)

STF_MB_ICON = Icon

Specifies the icon to display. Icon is one of the following:

1 No icon

2 Info icon

3 Stop icon

4 ? icon

5 ! icon