Class: TDialogUtilities

Declaration: DialogSupport.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

None.

Inherited By:

None.

Purpose:

TDialogUtilities defines functions that are commonly used in the use of dialog boxes. Never instantiate this class. Instead, use these functions directly to customize your dialog.

Instantiation:

Never instantiate this class.

Deriving Classes:

Do not derive from TDialogUtilities.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Other Considerations:

None.

Member Function: TDialogUtilities::ErrorBeep

static void ErrorBeep ()

Interface Category:

API.

Purpose:

Sounds a beep.

Calling Context:

Called to sound a beep. Called by class TRequestTextContent, class TRequestFileSystemEntityContent.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDialogUtilities::EnableButtonIfTextHasCharacters

static void EnableButtonIfTextHasCharacters (TPushButton & pushButton, const TText & text)
static void EnableButtonIfTextHasCharacters (TPushButton & pushButton, const TTextControl & textControl)

Interface Category:

API.

Purpose:

Enables the specified button if the specified TText object contains text. Otherwise the button is disabled.
Enables the specified button if the specified TTextControl object has text associated with it. Otherwise the button is disabled.

Calling Context:

Called to enable a button if it has text associated with it.
Called to enable a button if it has text associated with it.

Parameters:

TPushButton & pushButton -The button to enable or disable.
const TText & text -The text object.
TPushButton & pushButton -The button to enable or disable.
const TTextControl & textControl -The text control object.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDialogUtilities::AdjustButtonSizeIfDefault

static TGPoint AdjustButtonSizeIfDefault (const TGPoint & buttonSize, bool isDefault)

Interface Category:

API.

Purpose:

Converts the specified button size to include the default button outline, if isDefault is true.

Calling Context:

Called to convert the specified button size to include the default button outline, if isDefault is true.

Parameters:

const TGPoint & buttonSize -The button size.
bool isDefault -If set to true, the button size is converted.

Return Value:

A reference to the button size.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDialogUtilities::AdjustButtonLocationIfDefault

static TGPoint AdjustButtonLocationIfDefault (const TGPoint & buttonLocation, bool isDefault)

Interface Category:

API.

Purpose:

Adjusts the specified button location to include the default button outline, if isDefault is true.

Calling Context:

Called to adjust the specified button location to include the default button outline, if isDefault is true.

Parameters:

const TGPoint & buttonLocation -The button location.
bool isDefault -If set to true, the button location will be adjusted.

Return Value:

A reference to the button location.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDialogUtilities::AdjustButtonSizeToFitText

static TGPoint AdjustButtonSizeToFitText (const TGPoint & buttonSize, const TTextLabel & label)

Interface Category:

API.

Purpose:

Adjusts the button size to accommodate the specified text.

Calling Context:

Called to adjust the button size to accommodate the specified text.

Parameters:

const TGPoint & buttonSize -The button size.
const TTextLabel & label -The text to appear in the button.

Return Value:

Returns a reference to the button size.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDialogUtilities::EstimateTextSize

static TGPoint EstimateTextSize (const TText & theText, const TGPoint minimumSize)

Interface Category:

API.

Purpose:

Returns the estimated size required to accommodate the specified text.

Calling Context:

Called to obtain an estimate of the size required to accommodate the specified text. Called by class TCommonDialogs.

Parameters:

const TText & theText -The text.
const TGPoint minimumSize -The minimum size for the text.

Return Value:

Returns the estimated size required to accommodate the specified text.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDialogUtilities::MakePushButton

static TPushButton * MakePushButton (TView & parentView, const TGPoint & location, const TGPoint & size, const TText & labelText, const TSemanticActionType & message =TStandardActions :: kDefaultMessage, bool enabled =true)

Interface Category:

API.

Purpose:

Creates a push button for the specified view, at the specified location with the specified label text.

Calling Context:

Called to create and adopt a push button for a view. Called by class TCommonDialogs.

Parameters:

TView & parentView -The view to contain the button.
const TGPoint & location -The button's location.
const TGPoint & size -The button's size.
const TText & labelText -The text for the button's label.
const TSemanticActionType & message =TStandardActions::kDefaultMessage -The semantic message associated with the button's actions.
bool enabled =true -If true, the button will be enabled. If false the button will be disabled.

Return Value:

A reference to the button created.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDialogUtilities::MakeCheckBox

static TCheckBox * MakeCheckBox (TView & parentView, const TGPoint & location, const TText & labelText, MBooleanControlState :: EBooleanState initialValue =MBooleanControlState :: kFalse, const TSemanticActionType & message =TStandardActions :: kDefaultMessage)

Interface Category:

API.

Purpose:

Creates a check box for the specified view, at the specified location with the specified label.

Calling Context:

Called to create and adopt a check box for a view.

Parameters:

TView & parentView -The view.
const TGPoint & location -The check box location.
const TText & labelText -The text for the check box's label.
MBooleanControlState :: EBooleanState initialValue =MBooleanControlState :: kFalse -If true, the box will be initially appear checked.
const TSemanticActionType & message =TStandardActions :: kDefaultMessage -The semantic message associated with the check box's actions.

Return Value:

A reference to the check box created.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDialogUtilities::MakeRadioButtonGroup

static TBooleanControlGroup * MakeRadioButtonGroup (TView & parentView, const TGPoint & location, const TGPoint & size)
static TBooleanControlGroup * MakeRadioButtonGroup (TView & parentView, TDequeOf < TLabel > & adoptedRadioButtonLabels, long columns, long rows, TBoxView :: EAlign ha =TBoxView :: kLeft, TBoxView :: EAlign va =TBoxView :: kTop, const TGPoint & gap =TGPoint ( 5, 5 ), MControl :: ELayout buttonLayout =MControl :: kLeftToRight)

Interface Category:

API.

Purpose:

Creates an empty Boolean control group and adopts it into the specified view.
Creates a Boolean control group, populates it from the specified deque and adopts it into the specified view.

Calling Context:

Called to create an empty group of radio buttons for a view.
Called to create a group of radio button for a view.

Parameters:

TView & parentView -The view.
const TGPoint & location -The location of the group of buttons.
const TGPoint & size -The size of the group of buttons
TView & parentView -The view.
TDequeOf < TLabel > & adoptedRadioButtonLabels -The button group to adopt.
long columns -The number of columns of buttons.
long rows -The number of rows of buttons.
TBoxView :: EAlign ha =TBoxView :: kLeft -Controls left-to-right alignment of the buttons.
TBoxView :: EAlign va =TBoxView :: kTop -Controls top-to-bottom alignment of the buttons.
const TGPoint & gap =TGPoint ( 5 5 ) -The spacing between buttons.
MControl :: ELayout buttonLayout =MControl :: kLeftToRight -Controls left-to-right alignment.

Return Value:

A reference to the button group.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDialogUtilities::MakeBooleanControlGroup

static TBooleanControlGroup * MakeBooleanControlGroup (TView & parentView, TDequeOf < TBooleanControl > & adoptedBooleanControls, long columns, long rows, TBoxView :: EAlign ha =TBoxView :: kLeft, TBoxView :: EAlign va =TBoxView :: kTop, const TGPoint & gap =TGPoint ( 5, 5 ))

Interface Category:

API.

Purpose:

Creates a group of buttons, populates it from the specified deque and adopts it into the specified view.

Calling Context:

Called to create a group of push buttons for a view.

Parameters:

TView & parentView -The view.
TDequeOf < TBooleanControl > & adoptedBooleanControls -The Boolean control to adopt.
long columns -The number of columns of controls.
long rows -The number of rows of controls.
TBoxView :: EAlign ha =TBoxView :: kLeft -Controls left-to-right alignment of the buttons.
TBoxView :: EAlign va =TBoxView :: kTop -Controls top-to-bottom alignment of the buttons.
const TGPoint & gap =TGPoint ( 5 5 ) -The spacing between the controls.

Return Value:

A reference to the adopted Boolean control group.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDialogUtilities::MakeTextControl

static TTextControl * MakeTextControl (TView & parentView, const TGPoint & location, const TGPoint & size, const TText & initialValue =TStandardText :: GetEmptyText (), GCoordinate borderThickness =1, const TText & labelText =TStandardText :: GetEmptyText (), MControl :: ELayout layout =MControl :: kLeftToRight)

Interface Category:

API.

Purpose:

Creates a text control for a view.

Calling Context:

Called to create a text control and adopt it to a view (ie. parentView). Called by class TCommonDialogs.

Parameters:

TView & parentView -The view.
const TGPoint & location -The location of the text control.
const TGPoint & size -The size of the text control.
const TText & initialValue =TStandardText :: GetEmptyText () -The initial text for the control.
GCoordinate borderThickness =1 -The border thickness.
const TText & labelText =TStandardText :: GetEmptyText () -The label text for the control.
MControl :: ELayout layout =MControl :: kLeftToRight -Controls left-to-right alignment.

Return Value:

A reference to the text control created.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The initial text font size style for this text control is defined to be the same as the font size style for all the controls in our system (ie. FontSize =14 pt. for now). This font size may not be modified by the caller of this member function. For example, if the initialValue is a TStandardText with a font size style, this font size style is ignored. All the text entered into this text control will use the initial text font size style predefined in our system.

Member Function: TDialogUtilities::MakeStaticTextControl

static TTextControl * MakeStaticTextControl (TView & parentView, const TGPoint & location, const TGPoint & size, const TText & initialValue

TStandardText :: GetEmptyText ())

Interface Category:

API.

Purpose:

Creates a disabled text control and adopt it to a view (ie parentView). The control cannot be edited, selected, or activated. This allows user to create multi-line text message label.

Calling Context:

Called to create a static text control and adopt it to a view (ie. parentView).

Parameters:

TView & parentView -The view.
const TGPoint & location -The location of the text control.
const TGPoint & size -The size of the text control.
const TText & initialValue =TStandardText :: GetEmptyText () -The initial text for the control.

Return Value:

A reference to the static text control created.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This text control also uses the predefined font size style for all controls in our system as its text font size style. (ie, FontSize =14 pt.). The new disabled TextControl HI standard uses a different background color to indicate it is in a disabled mode. As a result, it is not suitable to use this disabled text control to display multi-line of text message. In the future releases, we will release an internal API which allows the user to create multi-line text message label.Therefore, it is better to use TCommonDialogs APIs to create the necessary dialogs in order to get the proper multi-line text display effect.

Member Function: TDialogUtilities::MakeLabelView

static TLabelView * MakeLabelView (TView & parentView, const TGPoint & location, const TText & labelText =TStandardText :: GetEmptyText (), TBorder * border =NIL)

Interface Category:

API.

Purpose:

Creates a label for a view. The label cannot be edited, selected, or activated. This member function is used to setup a single line of text message label.

Calling Context:

Called to create a label and adopt it to a view (ie parentView). Called by class TCommonDialogs.

Parameters:

TView & parentView -The view.
const TGPoint & location -The location of the label.
const TText & labelText =TStandardText :: GetEmptyText () -The text for the label.
TBorder * border =NIL -The boarder for the label. If NIL, there is no border.

Return Value:

A pointer to the label created.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDialogUtilities::MakeRadioButtonInGroup

static TRadioButton * MakeRadioButtonInGroup (TBooleanControlGroup & parentView, const TGPoint & location, const TText & labelText, MBooleanControlState :: EBooleanState initialValue =MBooleanControlState :: kFalse, const TSemanticActionType & message =TStandardActions :: kDefaultMessage)

Interface Category:

API.

Purpose:

Adds and adopts a new radio button to a radio button group.

Calling Context:

Called to add new radio button to a radio button group.

Parameters:

TBooleanControlGroup & parentView -The radio button group view.
const TGPoint & location -The location of the new button.
const TText & labelText -The text for the button's label.
MBooleanControlState :: EBooleanState initialValue =MBooleanControlState :: kFalse -If true, the button will initially be on.
const TSemanticActionType & message =TStandardActions :: kDefaultMessage -The semantic message associated with the button's actions.

Return Value:

A pointer to the new radio button.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDialogUtilities::MakeRadioButton

static TRadioButton * MakeRadioButton (TView & parentView, const TGPoint & location, const TText & labelText, MBooleanControlState :: EBooleanState initialValue =MBooleanControlState :: kFalse, const TSemanticActionType & message =TStandardActions :: kDefaultMessage)

Interface Category:

API.

Purpose:

Creates and Adopts a new radio button for the specified view.

Calling Context:

Called to create a new radio button.

Parameters:

TView & parentView -The view.
const TGPoint & location -The location of the new button.
const TText & labelText -The text for the button's label.
MBooleanControlState :: EBooleanState initialValue =MBooleanControlState :: kFalse -If true, the button will initially be on.
const TSemanticActionType & message =TStandardActions :: kDefaultMessage -The semantic message associated with the button's actions.

Return Value:

A pointer to the new button.

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.