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
Creating Dialog Boxes on Windows NT
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
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.
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 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.
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
Add an include statement for dialog.h to your source code.
Call the function for the type of dialog you want to create.
Use DialogInput, DialogYesNo, DialogAlert, or DialogProgress.
Specify any necessary arguments.
The order of arguments is: text, prompt, defaultAns, setup, next, prev.
(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 The following procedure shows you how to do this with the Setup Util. All functions are described in two tables following the procedure.
Add an include statement for dialog.h to your source code.
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:
To register the dialog box with a Dialog Manager, call the registerDialogNext and registerDialogLast functions.
Call the initDisplay function to initialize the display and dialog header.
If necessary, call the appropriate functions for the settings you want to define. 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.
static void initDisplay (const char *productName, const char *title);
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.
Sets the string value of Text Area 2. This area is typically used for examples.
Indicates which function to call before displaying the dialog box. If NULL is specified, no setup function is called.
Indicates which function to call when a user clicks Next. If NULL is specified, no function is called.
Indicates which function to call when a user clicks Back. If NULL is specified, no function is called.
Sets a particular name-value pair.
This function performs the same operations as the setupWriteInf functions described in Chapter 12 "Using Log Files."
Returns a particular name-value pair.
This function performs the same operations as the setupGetInf functions described in Chapter 12 "Using Log Files."
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.
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.
Go to the directory where you installed the Setup Util and open template/instmpl.rc in a development environment such as Visual C++.
Under Dialog Boxes, open IDD_TEMPLATE. Your custom dialog panel should have the same settings and dimensions as this template.
Use the UI tools to draw your dialog panels. You may find it easiest to copy and modify IDD_TEMPLATE.
To Integrate Dialogs into an Installation
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
Add an include statement for dialog.h to your source code.
Create a function to obtain and process user input.
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.
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
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."
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.
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