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

The following forward declarations and typedefs appear at the top of dialog.h.


Dialog Class

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

             }


DialogAction

Handler for Dialog callbacks.

typedef DialogAction (*DLG_CALLBACK) (Dialog *);



Functions

The dialog.h library contains these functions.


DialogManager Class

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();

virtual ~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.

static void enableWinMode();

static void disableWinMode();

static void newPage();

void setDefaultScript(InstallInfo *script);

InstallInfo *getDefaultScript() const;


start
Starts the Dialog Manager.

virtualint start() = 0;


cont
Continues the dialogs where they were previously left off.

virtual int cont() = 0;


clear
Removes all dialogs owned by this Manager.

virtual void clear() = 0;


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.

virtual void restore() = 0;


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;


Dialog Class

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

  • A prompt

  • The default answer, which is displayed in square brackets

  • An input area

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 setText (const char *);

void setText2(const char *);

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.

void setInputLen(int length);


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; }


Display

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

  • showString displays a given string and returns

  • showProgress displays a given string at a specific location

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().

DialogAction show();

void showText();

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.

int getInput();


Dialog::getPassword
A specialized function similar to getEvent except that the input is not echoed to the screen.

int getPassword();


Protected Functions

next
Callback for RETURN (next). Returns True if the operation succeeds, False if there is an error.

DialogAction next();


prev
Callback for BACK (prev). Should always go back to the previous dialog.

void prev();

Bool _visited;

Bool _hidden;

Bool _show;

Bool _enable8BitInput;

char _buf[MED_BUF];



Dialog Creation Functions

The following dialog functions are provided as part of the Setup Util. They allow for easy creation of standard dialog boxes.


DialogYesNo

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();


DialogInput

Creates a standard dialog used to collect input.

DialogInput:public Dialog

DialogInput ()
   {}

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();


DialogAlert

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();


DialogProgress

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