Class: TGUIDialogController

Declaration: DialogController.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MCollectible, MGUIBundle

Inherited By:

None.

Purpose:

TGUIDialogController is used to manage a dialog view within a GUI Compound document presentation.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

Derive from this class if new actions are needed (besides kStandardAcceptMessage and kStandardCancelMessage) or if the default behavior of Cancel and Accept needs to be changed.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TGUIDialogController::TGUIDialogController

TGUIDialogController (TGUIBundle * bundleToAlias)
TGUIDialogController ()
TGUIDialogController (const TGUIDialogController &)

Interface Category:

API.

Purpose:

Creates a dialog controller with the specified GUI bundle.
Default constructor.
Copy constructor.

Calling Context:

You can call this function directly.
Called by the stream-in operators.
Called to copy an object.

Parameters:

TGUIBundle * bundleToAlias -The GUI bundle for the new dialog controller.
Takes no parameters.
const TGUIDialogController & -The object to copy.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The default and copy constructors are protected.

Member Function: TGUIDialogController::~TGUIDialogController

virtual ~ TGUIDialogController ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIDialogController::operator>>=

virtual TStream & operator >>=(TStream &) const

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

TStream & -The stream to which the object streams itself out.

Return Value:

Returns a reference to the stream the object streams itself out to.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIDialogController::operator<<=

virtual TStream & operator <<= (TStream &)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

TStream & -The stream from which the object streams itself in.

Return Value:

Returns a reference to the stream the object streams itself in from.

Exceptions:

Throws a TInvalidVersionError if the version of the object on the stream is unknown to the version of the shared library installed.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIDialogController::Open

void Open ()

Interface Category:

API.

Purpose:

Opens the dialog controller. Derived classes who wish to alter the default open behavior should override HandleOpen rather than this function.

Calling Context:

Called by TGUIPresenter. Clients should not call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws TDocumentException::kNILObject if the dialog controller has a NIL GUI bundle.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIDialogController::Close

void Close ()

Interface Category:

API.

Purpose:

Closes the dialog controller. Derived classes who wish to alter the default close behavior should override HandleClose rather than this function.

Calling Context:

Called by TGUIPresenter. Clients should not call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIDialogController::Hide

void Hide ()

Interface Category:

API.

Purpose:

Hides the dialog controller. Derived classes who wish to alter the default hide behavior should override HandleHide rather than this function.

Calling Context:

Called by TGUIPresenter. Clients should not call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIDialogController::Show

void Show ()

Interface Category:

API.

Purpose:

Shows the dialog controller if it is not already showing. Derived classes who wish to alter the default show behavior should override HandleShow rather than this function.

Calling Context:

Called by TGUIPresenter. Clients should not call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIDialogController::Accept

void Accept ()

Interface Category:

API.

Purpose:

Accepts the action represented by the dialog controller. This function is typically called when the user selects the OK or similar button on the dialog controller. Derived classes who wish to alter the default acceptance behavior should override HandleAccept rather than this function.

Calling Context:

Typically called in response to a selection of a dialog button.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIDialogController::Cancel

void Cancel ()

Interface Category:

API.

Purpose:

Cancels the action represented by the dialog controller. This function is typically called when the user selects the Cancel or similar button on the dialog controller. Derived classes who wish to alter the default cancel behavior should override HandleCancel rather than this function.

Calling Context:

Typically called in response to a selection of a dialog button.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIDialogController::SetDialogWindowTitleText

void SetDialogWindowTitleText (const TStandardText & text)

Interface Category:

API.

Purpose:

Sets the title of the dialog controller's window.

Calling Context:

Called by any client object.

Parameters:

const TStandardText & text -The new title for the dialog controller's window.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIDialogController::GetDialogWindowTitleText

void GetDialogWindowTitleText (TStandardText & text) const

Interface Category:

API.

Purpose:

Returns the title of the dialog controller's window.

Calling Context:

Called by any client object.

Parameters:

TStandardText & text -The title of the dialog controller's window as returned by this function.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIDialogController::SetDefaultActiveChild

void SetDefaultActiveChild (TActivatibleView *)

Interface Category:

API.

Purpose:

Sets the view that is active by default.

Calling Context:

Called by TGUIPresenter to manage view activation. Clients should not call this function directly.

Parameters:

TActivatibleView * -The default active view.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIDialogController::GetDefaultActiveChild

virtual TActivatibleView * GetDefaultActiveChild () const

Interface Category:

API.

Purpose:

Returns the view that is active by default.

Calling Context:

Called by TGUIPresenter to manage view activation. Clients should not call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the view that is active by default.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIDialogController::HandleViewAction

virtual bool HandleViewAction (TViewAction & action)

Interface Category:

API.

Purpose:

Processes a mouse click on a button in the dialog controller's window. If the parameter is either kStandardAcceptMessage or kStandardCancelMessage, then this function calls Accept or Cancel as appropriate and closes the dialog window. Otherwise, this function tries to pass the action on to the GUI bundle's presenter. Override this member function if new actions are being defined in derived classes. TGUIDialogController::HandleViewAction must be called if the action is not handled by the derived class.

Calling Context:

Called by the input system.

Parameters:

TViewAction & action -The action that caused this function to be called.

Return Value:

Returns true if this function (or the GUI bundle's presenter) handled the action.

Exceptions:

Throws TDocumentException::kNILObject if this function tries to give the action to the GUI bundle's presenter, and the presenter is NIL.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIDialogController::GetRequestProcessor

TRequestProcessor * GetRequestProcessor () const

Interface Category:

API.

Purpose:

Returns the request processor for the dialog controller.

Calling Context:

Called by SetupNotifications. Clients should not call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the request processor for the dialog controller.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIDialogController::SetDefaultButton

virtual void SetDefaultButton (TPushButton * buttonAlias)

Interface Category:

API.

Purpose:

Designates the default button. This ensures that the return key will simulate a mouse click in the designated TPushButton object. You don't have to call this function if your dialog view was created from a constructor archive.

Calling Context:

Called by any client object.

Parameters:

TPushButton * buttonAlias -The new default button.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIDialogController::SetCancelButton

virtual void SetCancelButton (TPushButton * buttonAlias)

Interface Category:

API.

Purpose:

Designates the cancel button. This ensures that the cancel key will simulate a mouse click in the designated TPushButton object. You don't have to call this function if your dialog view was created from a constructor archive.

Calling Context:

Called by any client object.

Parameters:

TPushButton * buttonAlias -The new cancel button.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIDialogController::GetDefaultButton

virtual TPushButton * GetDefaultButton ()

Interface Category:

API.

Purpose:

Returns the dialog controller's default button.

Calling Context:

Called by any client object.

Parameters:

Takes no parameters.

Return Value:

Returns the dialog controller's default button.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIDialogController::GetCancelButton

virtual TPushButton * GetCancelButton ()

Interface Category:

API.

Purpose:

Returns the dialog controller's cancel button.

Calling Context:

Called by any client object.

Parameters:

Takes no parameters.

Return Value:

Returns the dialog controller's cancel button.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIDialogController::HandleAccept

virtual void HandleAccept ()

Interface Category:

API.

Purpose:

Accepts the action represented by the dialog controller. TGUIDialogController's implementation of this function does nothing. Derived classes should override this function rather than Accept to alter the default behavior.

Calling Context:

Called from Accept.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIDialogController::HandleCancel

virtual void HandleCancel ()

Interface Category:

API.

Purpose:

Cancels the action represented by the dialog controller. TGUIDialogController's implementation of this function does nothing. Derived classes should override this function rather than Cancel to alter the default behavior.

Calling Context:

Called from Accept.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIDialogController::HandleOpen

virtual void HandleOpen ()

Interface Category:

API.

Purpose:

Opens the dialog controller. This function creates and opens the dialog window, and adds the window to the GUI bundle. Derived classes who wish to alter the default open behavior should override this function rather than Open.

Calling Context:

Called by Open. Clients should not call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws TDocumentException::kNILObject if HandleCreateDialogView returns NIL. Throws TDocumentException::kNILObject if the GUI bundle has a NIL presenter.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIDialogController::HandleClose

virtual void HandleClose ()

Interface Category:

API.

Purpose:

Closes the dialog controller. This function closes the window, removes it from the window group, and destroys it. Derived classes who wish to alter the default close behavior should override this function rather than Close.

Calling Context:

Called by Close. Clients should not call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIDialogController::HandleHide

virtual void HandleHide ()

Interface Category:

API.

Purpose:

Hides the dialog controller if it is currently open. Derived classes who wish to alter the default hide behavior should override this function rather than Hide.

Calling Context:

Called by Hide. Clients should not call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIDialogController::HandleShow

virtual void HandleShow ()

Interface Category:

API.

Purpose:

Shows the dialog controller if it is currently open. Derived classes who wish to alter the default show behavior should override this function rather than Show.

Calling Context:

Called by Show. Clients should not call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIDialogController::CreateDialogViewFromArchive

static TView * CreateDialogViewFromArchive (const TArchive & archive, const TStandardText & dialogName)

Interface Category:

API.

Purpose:

Create the view the be used for the dialog from the specific archive.

Calling Context:

You can call this function directly.

Parameters:

const TArchive & archive -The archive to retrieve the view from.
const TStandardText & dialogName -The name of the view.

Return Value:

TView * -The view retrieved from the archive.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIDialogController::AdoptDialogView

void AdoptDialogView (TView * dialogView)

Interface Category:

API.

Purpose:

Adopt the dialog view to be used by this controller.

Calling Context:

You can call this function directly.

Parameters:

TView * dialogView -The dialog view to adopt.

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.