Previous     Contents     Index     Next     
Setup Util Programmer's Guide



Chapter 5   Creating Dialogs


This chapter shows you how to create dialog boxes with the Setup Util. It contains the following sections:



Understanding Setup Util Dialog Boxes

Many installers copy information or configure a product differently depending on how a user answers setup questions. Sometimes, an operation requires a warning message. In order to handle many different information gathering and delivery processes, the Setup Util provides a set of functions for creating and implementing dialog boxes.

On UNIX, dialog boxes are created from within the Setup Util and only contain text. The Setup Util includes several standard dialog box functions for use with the Common Install Shell on UNIX. These allow you to request information, ask yes or no questions, and display alert messages.

You can also use the Setup Util to create custom UNIX dialog boxes. When doing so, you can use either your main program or the Setup Util Dialog Manager to determine how and when to display the dialogs. The dialog boxes and their associated actions are created using additional Setup Util functions.

On Windows NT, dialog boxes are created as part of a DLL containing pre-installation, post-installation, and uninstallation programs. Unlike UNIX, they are displayed as part of a graphical wizard.

Working with a Dialog Manager



The Setup Util defines an abstract class called DialogManager to instantiate dialog boxes and handle navigation through them. Upon execution, each dialog box returns a value that determines whether the Dialog Manager updates the current screen, advances, backtracks, or exits.

You do not need to use a Dialog Manager to write an installer with the Setup Util. Instead, you can incorporate all dialog code into your installer's main program. However, if your installer is complex or you don't want to use main to handle dialog boxes, follow the instructions in this section to create and use a Dialog Manager.


Creating a Dialog Manager

If you decide to use a Dialog Manager in your installer, you should initialize it before you begin creating dialog boxes.


To Initialize a Dialog Manager

  1. Include dialog.h in your installer code.

  2. Call DialogManager() before you create any dialog boxes.


Using a Dialog Manager

Once you have initialized a Dialog Manager, you can utilize a number of functions. These are summarized in the following table.


Table 5-1 Functions contained in the DialogManager class

Function Name

Syntax

Description

setInstallMode  

void setInstallMode (InstallMode mode)  

Sets the installation mode. Possible values for mode are Silent, Binary, and Interactive.  

installMode  

InstallMode installMode () const  

Returns the current installation mode.  

setInstallType  

void setInstallType (InstallType type)  

Sets the installation type. Possible values for type are Express, Typical, and Custom.  

installType  

InstallType installType () const  

Returns the current installation type.  

enableWinMode  

static void enableWinMode();  

Indicates that you are going to begin displaying dialogs. You must call this function before opening any dialog boxes.  

disableWinMode  

static void disableWinMode();  

Specifies a UNIX installation. You must call this function before opening any dialog boxes on UNIX.  

newPage  

static void newPage();  

Initializes a new dialog.  

setDefaultScript  

void setDefaultScript(InstallInfo *script);  

Sets the default installation script for use during silent installation  

getDefaultScript  

InstallInfo *getDefaultScript() const;  

Gets the default installation script for use during silent installation.  

start  

virtual int start() = 0;  

Starts and stops the Dialog Manager. Possible values are 0 (stop) and 1 (start).  

cont  

virtual int cont() = 0;  

Continues the sequence of dialog boxes where they were last left off.  

clear  

virtual void clear() = 0;  

Clears all dialog boxes handled by this Dialog Manager.  

add  

virtual void add() = 0;  

Adds a dialog to the list handled by the Dialog Manager. The new dialog box follows the current dialog.  

addLast  

virtual void addLast(Dialog *) = 0;  

Adds a dialog to the end of the list handled by the Dialog Manager. The new dialog box follows the last existing dialog.  

resetLast  

virtual void resetLast() = 0;  

Clears all dialog boxes after the current dialog.  

restore  

virtual void restore() = 0;  

Restores previous dialog boxes. This lets the user move backward through the installer screens.  

setParent  

virtual void setParent(void *) = 0;  

Sets the parent of this Dialog Manager.  

parent  

virtual void *parent() const = 0;  

Gets the parent of this Dialog Manager.  



Creating Dialog Boxes on UNIX



The Setup Util provides built-in functions for creating the following types of dialog box:

  • Input, which is used to collect information from a user

  • Yes or No, in which a user answers a yes or no question

  • Alert, which displays an alert message

You can also use the Util to update a progress string such as "Step x of 5" or create custom dialogs.

Each dialog, regardless of type, takes several arguments. These are described in Dialog Box Arguments" below.


Dialog Box Arguments

The following table lists the arguments you can specify when creating a dialog box with the Setup Util.


Table 5-2 Arguments for standard Setup Util dialog box functions.

Parameter

Description

text  

A text string containing instructions or information for the user.  

prompt  

A text string specifying what the user should enter.  

defaultAns  

A text string containing the default answer to prompt.  

setup  

The name of a function to execute before displaying the dialog box. The value "0" indicates that there is no function to execute.  

next  

The name of a function to execute after the user has entered an answer to prompt and clicked Next. The value "0" indicates that there is no function to execute.  

prev  

The name of a function to execute when a user wants to return to the previous screen. The value "0" indicates that there is no function to execute.  


Standard Dialog Boxes

The Setup Util provides functions for four pre-defined dialog box functions: DialogInput, DialogYesNo, DialogAlert, and DialogProgress. Each of these functions can take any of the arguments specified in Dialog Box Arguments" above.


To Create a Standard Dialog Box

  1. Add an include statement for dialog.h to your source code.

  2. Call the function for the type of dialog you want to create.

    Use DialogInput, DialogYesNo, DialogAlert, or DialogProgress.

  3. Specify any necessary arguments.

    The order of arguments is: text, prompt, defaultAns, setup, next, prev.

  4. (Optional) Register your dialog box with a Dialog Manager by calling the registerDialogNext and registerDialogLast functions. For more information about these functions, see Table 5-3 below.

This sample code creates an input dialog box called welcome:


#include "dialog.h"
show()
{
   DialogInput *welcome =
      new DialogInput("Welcome to Sample Server",
                     "Click Next to continue",
                      NULL,
                      NULL,
                      NULL,
                      NULL);
   welcome->execute();
}

There are a number of ways to customize standard dialog boxes. For more information, see Custom Dialog Boxes below.


Custom Dialog Boxes

The four standard dialog boxes work for most installer screens. Nonetheless, you may want to write custom code for specialized dialogs or to generate installer text. When creating a custom dialog box, you must do the following:

  • Create a dialog.

  • (Optional) Register the dialog with a Dialog Manager

  • Initialize the display and dialog header

  • Define settings for the dialog

  • Display the dialog.

The following procedure shows you how to do this with the Setup Util. All functions are described in two tables following the procedure.


To Create a Custom Dialog Box

  1. Add an include statement for dialog.h to your source code.

  2. Use one of the following constructors to create a dialog box.

    If you want to specify your dialog options when you create the dialog box, use this constructor:


    Dialog (const char *text = 0,
            const char *prompt = 0,
            const char *defAns = 0,
            DLG_CALLBACK setup = 0,
            DLG_CALLBACK next = 0,
            DLG_CALLBACK prev = 0);

    If you want to specify your dialog options later, use this constructor:


    Dialog ();

  3. To register the dialog box with a Dialog Manager, call the registerDialogNext and registerDialogLast functions.

  4. Call the initDisplay function to initialize the display and dialog header.

  5. If necessary, call the appropriate functions for the settings you want to define.

  6. Invoke the display functions to show the dialog box.

Table 5-3 lists the Setup Util functions you can use to create dialog boxes.


Table 5-3 Functions you can use when creating custom dialog boxes.

Function Name

Syntax

Description

initDisplay  

static void initDisplay (const char *productName, const char *title);

static void initDisplay (const char *productName);  

Initializes the display and dialog header. If productName is not specified, the default product name "prefix Server Products" is used.

If title is not specified, the default header "prefix Server Family" is used.  

setText  

void setText (const char *);  

Sets the string value of Text Area 1.  

setText2  

void setText2 (const char *);  

Sets the string value of Text Area 2. This area is typically used for examples.  

setPrompt  

void setPrompt (const char *);  

Sets the string value of the prompt.  

setDefaultAns  

void setDefaultAns (const char *);  

Sets the string value of the default answer to the prompt.  

defaultAns  

const char *defaultAns() const

{ return _defaultAns; }  

Returns the default answer.  

enable8BitInput  

void enable8BitInput ()

{ _enable8BitInput = True; }  

Allows users to input 8-bit characters.  

disable8BitInput  

void disable8BitInput ()

{ _enable8BitInput = False; }  

Prevents users from entering 8-bit characters.  

setInputLen  

void setInputLen(int length);  

Sets the length of the input buffer.  

setSetupAction  

void setSetupAction(DLG_CALLBACK f);  

Indicates which function to call before displaying the dialog box. If NULL is specified, no setup function is called.  

setNextAction  

void setNextAction(DLG_CALLBACK f);  

Indicates which function to call when a user clicks Next. If NULL is specified, no function is called.  

setPrevAction  

void setPrevAction(DLG_CALLBACK f);  

Indicates which function to call when a user clicks Back. If NULL is specified, no function is called.  

setUserData  

void setUserData(const char *name, const char *value);

void setUserData(const char *name, long value);  

Sets a particular name-value pair.

This function performs the same operations as the setupWriteInf functions described in Chapter 12 "Using Log Files."  

getUserData  

const char *getUserData(const char *name);

int getUserData(const char *name, long & value);  

Returns a particular name-value pair.

This function performs the same operations as the setupGetInf functions described in Chapter 12 "Using Log Files."  

registerDialogNext  

void registerDialogNext(DialogManager *);  

Registers the next dialog box with the Dialog Manager.  

registerDialogLast  

void registerDialogLast(DialogManager *);  

Registers the previous dialog box with the Dialog Manager.  

manager  

DialogManager *manager()

{ return _dlgMgr; }  

Returns a Dialog Manager object.  

Many of the functions listed in Table 5-3 are used to define text strings that apply to different parts of a UNIX dialog box.

Table 5-4 lists the Setup Util functions you can use to display dialog boxes.


Table 5-4 Functions you can use to display dialog boxes.

Function Name

Syntax

Description

show  

DialogAction show();  

Draws a dialog box.  

showText  

void showText();  

Displays the string values for Text Area 1, Text Area 2, and Prompt.  

showString  

static void showString(const char *);  

Displays a single string value.  

showProgress  

static void showProgress(const char *);  

Updates the progress indicator.  

pause  

static void pause(const char * = NULL);  

Writes the text string "Press Return to continue" to the screen and waits for user input.  

disableBackPage  

static void disableBackPage();  

Prevents users from clicking Back to return to a previous dialog box.  

execute  

virtual DialogAction execute() = 0  

Performs any setup functions and displays the dialog box.  

input  

const char *input() const  

Returns the input buffer.  

isVisited  

Bool isVisited() const  

Returns True if the user has visited this dialog before.  

visited  

void visited()  

Marks a dialog box as visited.  

unVisited  

void unVisited()  

Marks a dialog box as unvisited.  

isHidden  

Bool isHidden() const  

Returns True if the dialog is not currently displayed.  

hidden  

void hidden()  

Marks a dialog box as hidden.  

unHidden  

void unHidden()  

Marks a dialog box as unhidden.  

getInput  

int getInput();  

Gets user input. Shows the characters entered by the user.  

getPassword  

int getPassword();  

Gets user input. Shows * for each character entered by the user.  

next  

DialogAction next();  

Advances to the next dialog box. If a function has been specified using setNextAction, it is invoked now.  

prev  

void prev();  

Goes to the previous dialog box. If a function has been specified using setPrevAction, it is invoked now.  



Creating Dialog Boxes on Windows NT



The Setup Util does not provide classes for creating Windows NT dialog boxes. Instead, it provides a dialog framework to which you can add specialized panels. You must create all panels using a development environment such as Visual C++, include them in your DLL, and then integrate them into an installation using the Setup Util.


Designing and Integrating Dialogs

In order to use dialog boxes in a Windows NT installer, you must first design the dialogs and then integrate them into the installer framework.


To Design a Dialog

  1. Go to the directory where you installed the Setup Util and open template/instmpl.rc in a development environment such as Visual C++.

  2. Under Dialog Boxes, open IDD_TEMPLATE. Your custom dialog panel should have the same settings and dimensions as this template.

  3. Use the UI tools to draw your dialog panels. You may find it easiest to copy and modify IDD_TEMPLATE.

  4. Include all panels in your DLL.


To Integrate Dialogs into an Installation

  1. Set the package information file directives as detailed in



Gathering and Processing Input

Most of the time, you will want to use dialog boxes to collect information from a user. The Setup Util makes gathering user input easy.


Collecting User Input on UNIX

The Setup Util can gather information from UNIX dialog boxes and then pass it to specialized functions that you create.


To Collect User Input from a UNIX Dialog Box

  1. Add an include statement for dialog.h to your source code.

  2. Create a dialog.

  3. Create a function to obtain and process user input.

  4. Specify the name of the function you created in step 3 as the value for the next argument of the Dialog Class.

The following example shows how to request and store a uid.


#include "dialog.h"
char * user_id[100];
DialogAction welcomeNext(Dialog *me)
{
   const char *buf = me->input();
   const char *uid;
   if (buf[0] == 0)
      strcpy(user_id, me->defaultAns());
   else
      strcpy(user_id, buf);
   return DIALOG_NEXT;
}
show()
{
   DialogInput *welcome =
      new DialogInput("Welcome to Mars!",
                      "Please enter your user id",
                      "anonymous",
                       NULL,
                       welcomeNext);
   welcome->execute();
}


Collecting User Input on Windows NT

On Windows NT, user input does not pass through Setup Util classes. Though the Common Install Shell uses the function specified by AskOptions to navigate through your dialogs, all reading and processing of information is handled by functions that you develop.


To Collect User Input on Windows NT

  • Use the Windows Util to develop functions for gathering and processing data from dialog boxes.



Customizing Common UI Text

In addition to creating your own dialog boxes, you can also customize the text that appears in Common Install Shell screens. This includes the welcome screen, license, and other dialogs that are not written by individual product teams.


Customizing UNIX Text

UNIX does not have a standard way for customizing resource text across platforms. As a result, the Setup Util uses text files to handle the task.


To Customize Common UI Text on UNIX

  1. Create a text file that maps UI element IDs to text strings. Use \n to indicate a line break.

    For example, to change the text on the server root selection screen, you would create the following line:

    dialog_serverroot_text = This program will extract Example Server and \ninstall it into the directory you specify below.

    For a complete list of UI element IDs, see Chapter 21 "Uxres.h Library Reference."

  2. Add the Resource directive to your master information file.

    Specify the path to the mappings file you created above as the value.

    For instructions on how to use directives, see Chapter 3 "Information Files."


Customizing Windows NT Text

On Windows NT, all UI text is contained in a resource file. You can use standard development tools to edit it.


To Customize Common UI Text on Windows NT

  1. Open instmpl.rc in a C++ development environment.

  2. Modify the desired text strings.


Previous     Contents     Index     Next     
Copyright (C) 2005 Red Hat, Inc. All rights reserved.
This material may be distributed only subject to the terms and conditions set forth in the Open Publication License, v1.0 or later (the latest version is presently available at http://www.opencontent.org/openpub/

Last Updated September 21, 2001