Class: TPushButton

Declaration: MomentaryControls.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TMomentaryControl

Inherited By:

None.

Purpose:

TPushButton derives from TMomentaryControl and is a concrete class. TPushButton adds to its parent class the concept of a text label and an optional picture label, and it implements the full MControl layout protocol for these labels. This class also provides a real look with an optional default button state.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

Not normally derived. You would typically derive directly from TMomentaryControl.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TPushButton::TPushButton

TPushButton ()
TPushButton (TLabel * label, TLabel * picturelabel =NIL)
TPushButton (MMomentaryControlState * state, TLabel * label =NIL, TLabel * picturelabel =NIL)
TPushButton (const TPushButton & copy)

Interface Category:

API.

Purpose:

Default constructor.
Creates a new TPushButton that adopts the specified label.
Creates a new TPushButton that adopts the specified state and the specified label.
Copy constructor. This constructor copies the state and label from the specified object.

Calling Context:

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

Parameters:

Takes no parameters.
TLabel * label -The main label used in the check box.
TLabel * picturelabel =NIL -The picture label to include with the main label.
MMomentaryControlState * state -The state the control manipulates.
const TPushButton & copy -The button to be copied.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPushButton::~TPushButton

virtual ~ TPushButton ()

Interface Category:

API.

Purpose:

Destructor. This function also deletes any adopted label or picture label.

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: TPushButton::operator=

TPushButton & operator =(const TPushButton &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

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

Parameters:

const TPushButton & -The object to be copied.

Return Value:

A non-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: TPushButton::operator>>=

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

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

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

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: TPushButton::operator<<=

virtual TStream & operator <<= (TStream &)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

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

Return Value:

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

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPushButton::GetPreferredSize

virtual TGPoint GetPreferredSize (GCoordinate maximumMainDimension =kInfinity) const >Interface Category: API.

Purpose:

Returns the minimum size required by this push button to display its picture label, label, and state to the user.

Calling Context:

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

Parameters:

GCoordinate maximumMainDimension =kInfinity -This parameter is defined in the MControl virtual member function and is currently ignored.

Return Value:

Returns the preferred size for this push button.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides the inherited MControl function.

Member Function: TPushButton::SetPressed

virtual void SetPressed (bool)

Interface Category:

API.

Purpose:

Redraws the control, showing the control pressed feedback. The control is pressed when the user holds the mouse button down over it.

Calling Context:

Called during interaction on the control.

Parameters:

Boolean -The flag indicating whether to set this control to pressed or unpressed. true sets the control to pressed; false sets it to unpressed.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides the inherited MControl function.

Member Function: TPushButton::SetDefault

virtual void SetDefault (bool flag =true)

Interface Category:

API.

Purpose:

Specifies whether the look of the button should be that of the default button in a dialog box, based on the value of the Boolean flag. This does not hook the button up to the enter key--that has to be done by the containing dialog.

Calling Context:

Call this function directly.

Parameters:

bool flag =true -Specifies whether to look like a default button.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPushButton::IsDefault

virtual bool IsDefault () const

Interface Category:

API.

Purpose:

Determines whether this push button has the default button look.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if button looks like a default button, false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPushButton::AdoptLabel

virtual void AdoptLabel (TLabel * label)

Interface Category:

API.

Purpose:

Adopts the specified label to display to the user. This function calls HandleStateChanged.

Calling Context:

Call this function directly.

Parameters:

TLabel * label -The label to be adopted. This can be any TLabel derived class.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPushButton::OrphanLabel

virtual TLabel * OrphanLabel ()

Interface Category:

API.

Purpose:

Removes this control's reference to its currently adopted label.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the orphaned label.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPushButton::AdoptPictureLabel

virtual void AdoptPictureLabel (TLabel * label)

Interface Category:

API.

Purpose:

Adopts a picture label to be used along with the text label. This label is arranged with regard to the MMomentaryControlState label according to the layout returned from MControl::GetControlLayout.

Calling Context:

Call this function directly.

Parameters:

TLabel * label -The picture label to be adopted.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPushButton::OrphanPictureLabel

virtual TLabel * OrphanPictureLabel ()

Interface Category:

API.

Purpose:

Orphans the adopted picture label.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the orphaned label.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPushButton::GetPictureLabel

virtual TLabel * GetPictureLabel () const

Interface Category:

API.

Purpose:

Returns a pointer to the adopted picture label.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a polymorphic pointer to a TLabel object or an object that inherits from TLabel.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPushButton::DrawContents

virtual void DrawContents (TGrafPort & port) const

Interface Category:

API.

Purpose:

Draws the control.

Calling Context:

Called by the View system when the view needs to redraw.

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:

Overrides the inherited TView function.

Member Function: TPushButton::GetMargin

virtual GCoordinate GetMargin () const

Interface Category:

API.

Purpose:

Returns the margin to be reserved between the text label and the picture label.

Calling Context:

Called from Layout.

Parameters:

Takes no parameters.

Return Value:

Returns the margin.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPushButton::Layout

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

Interface Category:

API.

Purpose:

Lays out this control. If the control is not IsFixedResize, this function calls SetAllocatedArea to set the new preferred size.
Calculates the layout, given the actual bounds of the control. This layout is sensitive to the layout parameter given to the MControl::SetControlLayout. (MControl is a parent of TMomentaryControl.) So, for example, a kLeftToRight layout results in the graphic label on the left and the other label on the right.

Calling Context:

Called from SetAllocatedArea when the layout needs recalculating.
Called by GetPreferredSize and from the first Layout function.

Parameters:

Takes no parameters.
const TGRect & actualBounds -The bounds in which to layout the control. A zero bounds assumes a preferred size layout.
TGRect & graphicBounds -The location to put the picture label.
TGRect & labelBounds -The location to put the label.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPushButton::HandleAllocatedAreaChanged

virtual void HandleAllocatedAreaChanged (const TGArea & newArea)

Interface Category:

API.

Purpose:

Handles the situation where the push button control view's allocated area has changed. Calls Layout to relayout the control, and also redraws the control.

Calling Context:

Called by the framework when the push button's allocated area is changed. If you derive the TPushButton and override this same function in your derived class, be sure to call TPushButton::HandleAllocatedAreaChanged in your implementation.

Parameters:

const TGArea & newArea -A reference to the new TGArea object.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides the inherited TView function.

Member Function: TPushButton::NeedsClipping

virtual bool NeedsClipping ()

Interface Category:

API.

Purpose:

Tells whether this push button control needs to be clipped to fit within its bounds.

Calling Context:

Called by the framework during a View system refresh to determine whether a TLinkedClipPort needs to be created before calling the TPushButton's DrawContents to ensure that all drawing that happens in the TPushButton's DrawContents is clipped to the TPushButton's current allocated area.

Parameters:

Takes no parameters.

Return Value:

Returns true if it needs clipping, false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides the inherited TView function.

Member Function: TPushButton::HandleStateChanged

virtual void HandleStateChanged ()

Interface Category:

API.

Purpose:

Handles notification that the push button control state has changed. This involves updating the control with the new state. If a change affects the layout, this function calls Layout to relayout the control. Similarly, if a change affects the display of the control, this function redraws it.

Calling Context:

Called from MDelegatingMomentaryControl:: StateChanged, which is called when a notification is received from the state object that the state has changed.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides the inherited TMomentaryControl function.

Member Function: TPushButton::GetLabel

virtual const TLabel * GetLabel () const

Interface Category:

API.

Purpose:

Returns a pointer to the label last adopted, copied or streamed in. If no label was adopted, it returns the label by calling MDelegatingMomentaryControl::GetLabel.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a constant polymorphic pointer to a TLabel object or an object that inherits from TLabel. If no label is used, the return value is NIL.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPushButton::SetEnabled

virtual void SetEnabled (bool)

Interface Category:

API.

Purpose:

Enables or disables this push button control according to the specified Boolean flag, and redraws the control to provide visual feedback regarding its new enabled or disabled state. A disabled control is not interactive, while an enabled control functions normally. All controls can be enabled or disabled; by default, controls are enabled.

Calling Context:

Called directly by clients or derived classes.

Parameters:

bool -The flag indicating whether to enable or disable this control--true enables the control; false disables it.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides the inherited MControl function.

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