Class: TToggleButton

Declaration: BooleanControls.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TBooleanControl

Inherited By:

None.

Purpose:

TToggleButton derives from TBooleanControl. Boolean controls have three possible states: unknown, false, and true. When first created, they are initialized to the unknown state. For toggle buttons, false corresponds to the toggle being off and true corresponds to the toggle being on. Visually, the toggle button will look like it is sticking up (or out) of the screen surface when the toggle is off. Conversely, it will look pushed in below the screen surface when the toggle is on. The toggle button appears to descend even further below the screen surface when the user presses the mouse down on it. Because TToggleButton derives from TBooleanControl, it has a graphic label and another label.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

You do not normally derive from TToggleButton. You typically derive directly from TBooleanControl.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TToggleButton::operator=

TToggleButton & operator =(const TToggleButton &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Call this function by using the operator in an assignment statement.

Parameters:

const TToggleButton & -The object to be copied.

Return Value:

Returns a const reference to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TToggleButton::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:

TStream & -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: TToggleButton::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:

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

Exceptions:

Throws TInvalidVersionError if it encounters an object whose version number indicates it cannot be streamed in. Passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TToggleButton::DrawContents

virtual void DrawContents (TGrafPort &) const

Interface Category:

API.

Purpose:

Draws this toggle button.

Calling Context:

Called by the view system when this toggle button needs redrawing.

Parameters:

TGrafPort & -The graf port into which to draw.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TToggleButton::CreateGraphicLabel

virtual TGraphicLabel * CreateGraphicLabel () const

Interface Category:

API.

Purpose:

Returns NIL because the toggle button graphic cannot be represented by a single label.

Calling Context:

Called by TBooleanControl when a graphic label is first needed for layout.

Parameters:

Takes no parameters.

Return Value:

Returns NIL.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TToggleButton::~TToggleButton

virtual ~ TToggleButton ()

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: TToggleButton::GetDefaultGraphicSize

virtual void GetDefaultGraphicSize (TGPoint & size) const

Interface Category:

API.

Purpose:

Reports the size that the toggle button requires for the graphic, thus ensuring that space will be accounted for in the layout performed by TBooleanControl.

Calling Context:

Called by TBooleanControl during layout.

Parameters:

TGPoint & size -This function will fill in this variable with the default size of the graphic label. The x-component of the point is the desired width, and the y-component of the point is the desired height.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

If a graphic label has been adopted, this function will return its size. Otherwise it will return kDefaultGraphicSize, the static const for the TToggleButton class, which might be a zero size.

Member Function: TToggleButton::Layout

virtual void Layout ()
virtual void Layout (const TGRect & actualBounds, TGRect & graphicBounds, TGRect & labelBounds) const

Interface Category:

API.

Purpose:

Lays out the toggle button. If the control is not fixed size, this function calls SetAllocatedArea to set the new preferred size.
Calculates the layout given the actual bounds of the control. Relative location of the two labels is governed by the last call of MControl::SetControlLayout. For example, a kLeftToRight setting of MControl::ELayout results in the graphic label on the left and the other label on the right. TToggleButton overrides the behavior supplied by TBooleanControl, by finishing the layout by centering the combination of the two labels in the center of the actualBounds.

Calling Context:

The framework calls this function for you, but you may call it yourself, if you have a special need for it.

The framework (ForceRedraw) calls this function when the layout needs recalculating; you do not need to call it directly.
The framework (GetPreferredSize) calls this function when the layout needs recalculating; you do not need to call it directly.

Parameters:

Takes no parameters.
const TGRect & actualBounds -The bounds within which to layout the toggle button. A zero bounds will assume a preferred size layout.
TGRect & graphicBounds -The location at which to put the graphic label.
TGRect & labelBounds -The location at which to put the label.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

IsFixedSize reports whether the control is fixed size.

Member Function: TToggleButton::GetPreferredSize

virtual TGPoint GetPreferredSize (GCoordinate maximumMainDimension =kInfinity) const

Interface Category:

API.

Purpose:

Reports the minimum size required to display the toggle button.

Calling Context:

Called by Layout, if the control is not a fixed size. You can also call this function directly.

Parameters:

GCoordinate maximumMainDimension =kInfinity -If you override the default value (kInfinity), the function might ignore this parameter passed to it, since you shouldn't use it to wrap parts of the control onto additional lines.

Return Value:

TGPoint preferredSize -The x-value of the point is the width, and the y-value the height of the minimum size needed.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TToggleButton::GetGraphicLabel

virtual const TGraphicLabel * GetGraphicLabel () const

Interface Category:

API.

Purpose:

Provides read-only access to the graphic label displayed by the toggle button.

Calling Context:

You can call this function directly. The framework calls it also.

Parameters:

Takes no parameters.

Return Value:

const TGraphicLabel * graphicLabel -The graphic label associated with the toggle button, or NIL if there is none.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The returned value will be NIL if there is no graphic label. Use AdoptGraphicLabel to install a graphic label into the toggle button.

Member Function: TToggleButton::OrphanGraphicLabel

virtual TGraphicLabel * OrphanGraphicLabel ()

Interface Category:

API.

Purpose:

Removes but does not delete the graphic label from a toggle button.

Calling Context:

You can call this function directly.

Parameters:

Takes no parameters.

Return Value:

TGraphicLabel * orphanedGraphicLabel

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Use the converse function, AdoptGraphicLabel to install a graphic label into the toggle button. You are responsible for deleting the graphic label you orphan.

Member Function: TToggleButton::AdoptGraphicLabel

virtual void AdoptGraphicLabel (TGraphicLabel * labelToAdopt)

Interface Category:

API.

Purpose:

Installs a graphic label into the toggle button. Unlike the check box and radio button, the toggle button allows you to specify any graphic label. This is similar to the picture label supported by TPushButton. The graphic label will be laid out relative to the TBooleanControl label according to the current MControl::ELayout setting.

Calling Context:

You can call this function directly.

Parameters:

TGraphicLabel * labelToAdopt

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function deletes any previously installed graphic label, performs a layout of the control, and marks it as needing to be redrawn. Related functions are OrphanGraphicLabel and GetGraphicLabel.

Member Function: TToggleButton::TToggleButton

TToggleButton ()
TToggleButton (TLabel * labelToAdopt, TGraphicLabel * graphicLabelToAdopt =NIL)
TToggleButton (MBooleanControlState * stateToAdopt, TLabel * labelToAdopt =NIL, TGraphicLabel * graphicLabelToAdopt =NIL)
TToggleButton (const TToggleButton & copy)

Interface Category:

API.

Purpose:

Default constructor.
Creates a new toggle button and adopts the specified label and graphic label.
Creates a new toggle button and adopts the specified state, label, and graphic label.
Copy constructor.

Calling Context:

Called by the stream-in operators and by clients or derived classes.
Called to adopt a label and graphic label at construction time.
Called to adopt a state, label, and graphic label at construction time.
Called to copy an object.

Parameters:

Takes no parameters.
TLabel * labelToAdopt
TGraphicLabel * graphicLabelToAdopt =NIL
MBooleanControlState * stateToAdopt
TLabel * labelToAdopt =NIL
TGraphicLabel * graphicLabelToAdopt =NIL
const TToggleButton & copy -The source object to copy.

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.