Class: TCommonDialogs

Declaration: CommonDialogs.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

None.

Inherited By:

None.

Purpose:

TCommonDialogs is an abstract base class for dialog boxes that prompt the user to make a choice or to enter requested information. These dialogs will always have minimum one button (Accept Button) displayed. When this button was selected, the TDialogState::Accept is called. Moreover, the behavior of these dialogs can be modified by passing in your own state classes derived from TDialogState.

Instantiation:

TCommonDialogs is an abstract class and cannot be instantiated.

Deriving Classes:

Do not derive from TCommonDialogs.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Other Considerations:

All custom dialog behavior is achieved through deriving classes from the appropriate dialog state. Important, the caller is responsible for memory management on all the dialogs created through the APIs of this class. The caller has to free the memory which is used by the dialogs when the dialogs are no longer needed. All custom dialog will support internationalization. Currently, it uses the Taligent System Locale to localize the text in the dialogs.

Member Function: TCommonDialogs::CreateMessageBox

static TStandardWindow * CreateMessageBox (const TText & windowTitle, const TText & message, TDialogState * adoptedState =NIL, const eDefaultButton whichDefaultButton =kAcceptButtonIsDefault, const TText & buttonTitle =kAcceptButtonDefaultTitle)

Interface Category:

API.

Purpose:

Creates a dialog window with the supplied title, message, state, default button, and button title.

Calling Context:

Called to create a dialog message window with a message and an accept button.

Parameters:

const TText & windowTitle -The title for the window.
const TText & message -The message to display in the box.
TDialogState * adoptedState =NIL -The state associated with this dialog.
const eDefaultButton whichDefaultButton =kAcceptButtonIsDefault -The default button selection.
const TText & buttonTitle =kAcceptButtonDefaultTitle -The title for the default button.

Return Value:

A pointer to the window created.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

All custom dialog behavior is achieved through deriving classes from the appropriate dialog state.

Member Function: TCommonDialogs::CreateSimpleQuestionDialog

static TStandardWindow * CreateSimpleQuestionDialog (const TText & windowTitle, const TText & message, TDialogState * adoptedState =NIL, const eDefaultButton whichDefaultButton =kAcceptButtonIsDefault, const TText & acceptButtonTitle =kAcceptButtonDefaultTitle, const TText & cancelButtonTitle =kCancelButtonDefaultTitle)

Interface Category:

API.

Purpose:

Creates a dialog window that contains a message for the user, a default accept button, and a cancel button.

Calling Context:

Called to create a dialog message window with a message, a default accept button, and a cancel button.

Parameters:

const TText & windowTitle -The title for the window.
const TText & message -The message to display in the box.
TDialogState * adoptedState =NIL -The state associated with this dialog.
const eDefaultButton whichDefaultButton =kAcceptButtonIsDefault -Defines the default button.
const TText & acceptButtonTitle =kAcceptlButtonDefaultTitle -The text for the accept button.
const TText & cancelButtonTitle =kCancelButtonDefaultTitle -The text for the cancel button.

Return Value:

A pointer to the window created.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

All custom dialog behavior is achieved through deriving classes from the appropriate dialog state.

Member Function: TCommonDialogs::CreateAcceptRejectCancelDialog

static TStandardWindow * CreateAcceptRejectCancelDialog (const TText & windowTitle, const TText & message, TAcceptRejectCancelDialogState * adoptedState =NIL, const eDefaultButton whichDefaultButton =kAcceptButtonIsDefault, const TText & acceptButtonTitle =TStandardText ( "Yes" ), const TText & rejectButtonTitle =TStandardText ( "No" ), const TText & cancelButtonTitle =kCancelButtonDefaultTitle)

Interface Category:

API.

Purpose:

Creates a dialog window that contains a message, a default accept button, a reject button, and a cancel button.

Calling Context:

Called to create a dialog message window with a message, a default accept button, a reject button, and a cancel button.

Parameters:

const TText & windowTitle -The title for the window.
const TText & message -The message to display in the box.
TAcceptRejectCancelDialogState * adoptedState =NIL -The state associated with this dialog.
const eDefaultButton whichDefaultButton =kAcceptButtonIsDefault -Defines the default button.
const TText & acceptButtonTitle =TStandardText ( "Yes" ) -The text for the accept button.
const TText & rejectButtonTitle =TStandardText ( "No" ) -The text for the reject button.
const TText & cancelButtonTitle =kCancelButtonDefaultTitle -The text for the cancel button.

Return Value:

A pointer to the window created.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

All custom dialog behavior is achieved through deriving classes from the appropriate dialog state.

Member Function: TCommonDialogs::CreateRequestTextDialog

static TStandardWindow * CreateRequestTextDialog (const TText & windowTitle, const TText & prompt, TRequestTextDialogState * adoptedState

NIL, const eDefaultButton whichDefaultButton =kAcceptButtonIsDefault, const TText & initialText =TStandardText :: GetEmptyText (), const TText & acceptButtonTitle =kAcceptButtonDefaultTitle, const TText & cancelButtonTitle =kCancelButtonDefaultTitle, const TGPoint & editableTextSize =kDefaultEditableTextControlSize, GCoordinate errorMessageHeight =kDefaultErrorMessageHeight)

Interface Category:

API.

Purpose:

Creates a dialog window that contains a message, an editable text area for user input, a default accept button, and a cancel button.

Calling Context:

Called to create a dialog message window with an editable text area, a default accept button, and a cancel button.

Parameters:

const TText & windowTitle -The title for the window.
const TText & prompt -The prompt for the dialog box.
TRequestTexTDialogState * adoptedState =NIL -The state associated with this dialog.
const eDefaultButton whichDefaultButton =kAcceptButtonIsDefault -Defines the default button.
const TText & initialText =TStandardText :: GetEmptyText () -The initial text for the dialog window.
const TText & acceptButtonTitle =kAcceptButtonDefaultTitle -The text for the accept button.
const TText & cancelButtonTitle =kCancelButtonDefaultTitle -The text for the cancel button.
const TGPoint & editableTextSize =kDefaultEditableTextControlSize -The size of the text input area. The kDefaultEditableTextControlSize is just big enough to hold on line of input text.
GCoordinate errorMessageHeight =kDefaultErrorMessageHeight -The default height for the message.

Return Value:

A pointer to the window created.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

All custom dialog behavior is achieved through deriving classes from the appropriate dialog state.

Member Function: TCommonDialogs::CreateRequestFileSystemEntityDialog

static TStandardWindow * CreateRequestFileSystemEntityDialog (const TText & windowTitle, const TText & prompt, TRequestFileSystemEntityDialogState * adoptedState =NIL, const TText & initialText =TStandardText :: GetEmptyText (), const TText & acceptButtonTitle =kAcceptButtonDefaultTitle, const TText & cancelButtonTitle =kCancelButtonDefaultTitle, TPathName * defaultPathName

GetDefaultPathName (), GCoordinate errorMessageHeight =kDefaultFileErrorMessageHeight)

Interface Category:

API.

Purpose:

Creates a dialog window for requesting a file name from the user. The window displays a working directory and error text. It also contains a prompt, an input area for the filename, and a cancel button.

Calling Context:

Called to create a dialog message window for requesting a filename from the user.

Parameters:

const TText & windowTitle -The title for the window.
const TText & prompt -The prompt for the user.
TRequestFileSystemEntityDialogState * adoptedState =NIL -The state associated with this dialog.
const TText & initialText =TStandardText :: GetEmptyText () -The initial text for the prompt.
const TText & acceptButtonTitle =kAcceptButtonDefaultTitle -The text for the accept button.
const TText & cancelButtonTitle =kCancelButtonDefaultTitle -The text for the cancel button.
TPathName * defaultPathName =GetDefaultPathName () -The pathname.
GCoordinate errorMessageHeight =kDefaultFileErrorMessageHeight -The default height for the message.

Return Value:

A pointer to the window created.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

All custom dialog behavior is achieved through deriving classes from the appropriate dialog state. The Accept Button(or Replace Button in some dialogs) is set to be the default button in this kind of dialog.

Member Function: TCommonDialogs::GetDefaultPathName

static TPathName * GetDefaultPathName ()

Interface Category:

API.

Purpose:

Returns the default pathname.

Calling Context:

Called to obtain the default pathname.

Parameters:

Takes no parameters.

Return Value:

Returns the default pathname.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCommonDialogs::SetDefaultPathName

static void SetDefaultPathName (const TPathName & pathName)

Interface Category:

API.

Purpose:

Sets the default pathname to the specified value.

Calling Context:

Called to set the default pathname.

Parameters:

const TPathName & pathName -The new default pathname.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Click the icon to mail questions or corrections about this material to Taligent personnel.