Previous Contents Index Next |
Setup Util Programmer's Guide |
Chapter 18 Dialog.h Library Reference
This chapter describes dialog.h, the library containing UNIX dialog box classes. It contains the following sections:
Forward Declarations and Typedefs
Forward Declarations and Typedefs
The following forward declarations and typedefs appear at the top of dialog.h.
Actions that are associated with a Dialog and performed by a Dialog Manager.
typedef enum { DIALOG_SAME, // Return to the current dialog
DIALOG_PREV, // Return to previous dialog
DIALOG_NEXT, // Go to next dialog
DIALOG_EXIT, // Exit dialog manager
DIALOG_ERROR, // Exit - catastrophic error - should not occur
DIALOG_TERMINATE //Exit - terminate program
typedef DialogAction (*DLG_CALLBACK) (Dialog *);
The dialog.h library contains these functions.
This abstract class defines a Dialog Manager for onscreen dialogs. The Dialog Manager is responsible for sequencing through all dialogs based on the DialogActions they return. Typically, Dialog Managers are only used in complex installers. In other situations, the Dialog Manager is part of the main program.
Public Definitions
DialogManager();
setInstallMode
Sets the installation mode. Possible values are <x, y, and z>
void setInstallMode (InstallMode mode)
{ _installMode = mode; }
installMode
Returns the installation mode.
InstallMode installMode () const
{ return _installMode; }
setInstallType
Sets the installation type.
void setInstallType (InstallType type)
{ _installType = type; }
installType
Returns the installation type.
InstallType installType () const
{ return _installType; }
Initialization
Call these functions before navigating through the dialogs.
void setDefaultScript(InstallInfo *script);
InstallInfo *getDefaultScript() const;
start
Starts the Dialog Manager.
cont
Continues the dialogs where they were previously left off.
clear
Removes all dialogs owned by this Manager.
add
Adds a dialog to the Manager's list. The added dialog follows the current dialog.
virtual void add (Dialog *) = 0;
addLast
Adds a dialog to the end of the Manager's list.
virtual void addLast (Dialog *) = 0;
resetLast
Removes all dialogs following the current one.
virtual void resetLast () = 0;
restore
Restores a dialog that was previously displayed.
setParent
Sets the parent of this Dialog Manager.
virtual void setParent(void *) = 0;
parent
Gets the parent of this Dialog Manager.
virtual void *parent() const = 0;
Class for defining virtual onscreen dialogs. A dialog is composed of the following:
A header
Text Area 1, which contains instructions
Text Area 2, which typically contains an example Three callback functions are associated with each dialog. These are supplied by the Dialog implementer.
SetUp, which is executed before a dialog is displayed
Next, which is executed after the user has submitted input.
Back, which is executed when the user wants to return to the previous dialog. In general, Next() is always necessary, Setup() is sometimes needed, and Back() is rarely used. Specify NULL if you are not supplying a specific callback.
Public Contructor
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);
Dialog::initDisplay
Call this static function to initialize the display and the dialog header. You must do this before you create your first dialog.
Optionally, you can supply a product name to use when initializing the header. If you do not supply a value, the Common Install Shell will use "Server Products."
static void initDisplay(const char *productName, const char *title);
static void initDisplay(const char *productName);
Dialog::set[Text, Text2, Prompt, DefaultAns]
Sets the string values of Text Area 1, Text Area 2, Prompt, and Default Answer. Takes - const char *text as an input.
void setPrompt (const char *);
void setDefaultAns (const char *);
Dialog::defaultAns
Returns the default answer.
const char *defaultAns() const
{ return _defaultAns; }
Dialog::enable8BitInput
Enables conversion of input from local to UTF8. Takes int length as an input. This must be a positive number less than or equal to 1024.
void enable8BitInput()
{_enable8BitInput = True; }
Dialog::disable8BitInput
Disables conversion of input from local to UTF8. Takes int length as an input. This must be a positive number less than or equal to 1024.
void disable8BitInput()
{_enable8BitInput = False; }
Dialog::setInputLen
Sets the maximum length of the input buffer. By default, the input buffer is set to 1024 bytes. Takes int length as an input. This must be a positive number less than or equal to 1024.
Dialog::set[SetupAction, NextAction, PrevAction]
Sets the callbacks. Takes the callback function DLG_CALLBACK as an input.
void setSetupAction(DLG_CALLBACK f);
void setNextAction(DLG_CALLBACK f);
void setPrevAction(DLG_CALLBACK f);
Dialog::setUserData
Sets the user data callbacks. Takes the callback function DLG_CALLBACK as an input.
void setUserData(const char *name, const char *value);
void setUserData(const char *name, long value);
Dialog::getUserData
Gets the user data callbacks.
const char *getUserData(const char *name);
int getUserData(const char *name, long & value);
Dialog::registerDialog[Next, Last]
Registers a dialog with the given Dialog Manager. Takes DialogManager and, optionally, flag as an input. A flag is an arbitrary value used to instruct the Dialog Manager on how to manage this dialog. You must configure your Dialog Manager to interpret this value. Use a flag value of 0 as the default.
void registerDialogNext(DialogManager *);
void registerDialogLast(DialogManager *);
Dialog::manager()
Get a given dialog's manager.
DialogManager *manager()
{ return _dlgMgr; }
These functions are used to display dialog boxes.
Dialog::show[Text,String,Progress]
Displays all or part of the dialog.
show displays the whole dialog
showText shows the text areas and then waits for input All four functions take DialogManager as an input.
show returns DialogAction NEXT_DIALOG, PREV_DIALOG, and ERROR_DIALOG
Before using these functions, you must call DialogManager::enableWinMode().
static void showString(const char *);
static void showProgress(const char *);
static void pause(const char * = NULL);
disableBackPage
Disables Control-B. This is only valid for one input prompt.
static void disableBackPage();
Dialog::execute
Executes a Dialog by calling Dialog::show. Returns NEXT_DIALOG, PREV_DIALOG, SAME_DIALOG, EXIT_DIALOG, or ERROR_DIALOG
Before using this function, you must call DialogManager::enableWinMode().
virtual DialogAction execute() = 0;
Dialog::input
Returns the input buffer
const char *input() const
{ return _buf; }
Dialog::isVisited
Returns True if the dialog has been visited. Otherwise, returns False.
Bool isVisited() const
{ return _visited; }
Dialog::[un]visited
Marks a dialog as visited or unvisited.
void visited()
{ _visited = True; }
void unVisited()
{ _visited = False; }
Dialog::isHidden
Returns True if the dialog is hidden. Otherwise, returns False.
Bool isHidden() const
{ return _hidden; }
Dialog::[un]hidden
Indicates whether a dialog needs to be displayed
void hidden()
{ _hidden = True; }
void unHidden()
{ _hidden = False; }
Dialog::getInput
Gets input. The input buffer is filled with the input as appropriate.
Dialog::getPassword
A specialized function similar to getEvent except that the input is not echoed to the screen.
Protected Functions
next
Callback for RETURN (next). Returns True if the operation succeeds, False if there is an error.
prev
Callback for BACK (prev). Should always go back to the previous dialog.
The following dialog functions are provided as part of the Setup Util. They allow for easy creation of standard dialog boxes.
Creates a dialog used to collect Yes or No answers.
DialogYesNo:public Dialog
DialogYesNo ()
{}
DialogYesNo(const char *text, const char *prompt, const char *defaultAns, DLG_CALLBACK setup = 0, DLG_CALLBACK next = 0, DLG_CALLBACK prev = 0);
DialogAction execute();
Creates a standard dialog used to collect input.
DialogInput (const char *text, const char *prompt, const char *defaultAns, DLG_CALLBACK setup = 0, DLG_CALLBACK next = 0, DLG_CALLBACK prev = 0, Bool allow8BitInput = False);
DialogAction execute();
Creates a pop-up dialog. Displays a message, waits for input, then returns to the current dialog.
DialogAlert:public Dialog
DialogAlert()
{}
DialogAlert(const char *message);
DialogAction execute();
Creates a dialog used to display the progress of an activity.
DialogProgress:public Dialog
DialogProgress():_newPage(False)
{}
~DialogProgress()
{}
DialogAction execute();
/* Display the progress string */
void showProgress(const char *text);
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