Class: TBooleanControl

Declaration: BooleanControls.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TSimpleView, MMouseEventHandler, MControl, MDelegatingBooleanControl

Inherited By:

TCheckBox TMinimizer TRadioButton TToggleButton TZoomBox

Purpose:

TBooleanControl is an abstract base class deriving from TSimpleView, MMouseEventHandler, MControl, and MDelegatingBooleanControl. TBooleanControls are views that present a label and a Boolean state to the user. The Boolean state is usually represented by some sort of graphic (known as the graphic label), where the graphic has a normal look and a selected look. The graphic label and the other label are arranged in relation to one another according to the MControl::ELayout setting. Boolean controls have three possible states: unknown, false, and true. When first created, they are initialized to the unknown state. This class creates a TBooleanInteractor if the state is enabled and the control is clicked on by a pointing device. This class should be derived from to implement a concrete look.

Instantiation:

Abstract base class; do not allocate.

Deriving Classes:

Classes deriving from TBooleanControl must implement CreateGraphicLabel and GetDefaultGraphicSize, but they do not have to provide a graphic label. Classes deriving from TBooleanControl may wish to override GetGap, CreateInteractor, HandleStateChanged, Layout, GetLayout, GetGraphicSize, and GetGraphicLabel.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TBooleanControl::TBooleanControl

TBooleanControl ()
TBooleanControl (TLabel * label)
TBooleanControl (MBooleanControlState * state, TLabel * label =NIL)
TBooleanControl (const TBooleanControl & copy)

Interface Category:

API.

Purpose:

Default constructor.
Creates a new Boolean control and adopts the specified label.
Creates a new Boolean control, adopts the specified state object, and adopts the specified label.
Copy constructor.

Calling Context:

TBooleanControl is an abstract base class, so all of its constructors are called by derived class constructors.

Parameters:

Takes no parameters.
TLabel * label -The label to be adopted.
MBooleanControlState * state -The state object to be adopted.
TLabel * label =NIL -The label to be adopted. Optional.
const TBooleanControl & copy -The object to be copied.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

TBooleanControl is an abstract base class--all the constructors are protected. Do not instantiate this class.

Member Function: TBooleanControl::~TBooleanControl

virtual ~ TBooleanControl ()

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

TBooleanControl & operator =(const TBooleanControl &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

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

Parameters:

const TBooleanControl & -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: TBooleanControl::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: TBooleanControl::operator<<=

virtual TStream & operator <<= (TStream &)

Interface Category:

API.

Purpose:

Stream-in operator.

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: TBooleanControl::AdoptLabel

virtual void AdoptLabel (TLabel * label)

Interface Category:

API.

Purpose:

Adopts the specified label to display to the user and marks the layout as invalid.

Calling Context:

You can call this function directly.

Parameters:

TLabel * label -The label to be adopted. This parameter can be a TLabel object or an object that inherits from TLabel.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Subsequent calls to ForceRedraw will update the layout and, if IsFixedSize returns false, the bounds of the control.

Member Function: TBooleanControl::OrphanLabel

virtual TLabel * OrphanLabel ()

Interface Category:

API.

Purpose:

Removes this control's reference to its currently adopted label, and marks the layout as invalid.

Calling Context:

You can 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:

Subsequent calls to ForceRedraw will update the layout and, if IsFixedSize returns false, the bounds of the control.

Member Function: TBooleanControl::GetLabel

virtual const TLabel * GetLabel () const

Interface Category:

API.

Purpose:

Returns a pointer to the label last adopted, copied or streamed in.

Calling Context:

Called by DrawContents and by the Layout functions. You can also 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: TBooleanControl::SetFixedSize

virtual void SetFixedSize (const TGPoint & size)

Interface Category:

API.

Purpose:

Sets this control to a fixed size. When a control is set to a fixed size it will remain at the specified size, regardless of any changes to other parameters such as the label and the graphic size.

Calling Context:

You can call this function directly.

Parameters:

const TGPoint & size -The new fixed size for this control. The x-component indicates the width of the graphic label, and the y-component indicates the height.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function calls SetAllocatedArea to establish the fixed size of the control. Use SetAutoResize to undo the affect of SetFixedSize and allow the control resize itself to fit its label and graphic label.

Member Function: TBooleanControl::IsFixedSize

virtual bool IsFixedSize () const

Interface Category:

API.

Purpose:

Reports whether a fixed size has been set for this control.

Calling Context:

Called by Layout. You can also call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if this control is a fixed size, false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Use SetFixedSize or SetAutoResize to regulate the result of this function.

Member Function: TBooleanControl::SetAutoResize

virtual void SetAutoResize ()

Interface Category:

API.

Purpose:

Resizes this control to the minimum size required to display its label and graphic label, and allows it to be automatically resized in the future.

Calling Context:

You can 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:

This function calls SetAllocatedArea to set the control to its minimum size. This function is the converse to SetFixedSize which keeps the size of the control fixed to a specified width and height.

Member Function: TBooleanControl::SetGraphicSize

virtual void SetGraphicSize (const TGPoint & size)

Interface Category:

API.

Purpose:

Sets the desired size of the graphic label and marks the layout as invalid.

Calling Context:

You can call this function directly.

Parameters:

const TGPoint & size -The new size for the graphic label. The x-component indicates the width of the graphic label, and the y-component indicates the height.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Subsequent calls to ForceRedraw will update the layout and, if IsFixedSize returns false, the bounds of the control.

Member Function: TBooleanControl::GetGraphicSize

virtual TGPoint GetGraphicSize () const

Interface Category:

API.

Purpose:

Returns the size of the graphic label. If SetGraphicSize has not been called, this function returns a default size specified by the TBooleanControl derived class.

Calling Context:

The framework (Layout) calls this function; you may call it yourself, also, if you have a special need for it.

Parameters:

Takes no parameters.

Return Value:

Returns a TGPoint containing the current size of the graphic label. The x-component indicates the width of the graphic label, and the y-component indicates the height.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TBooleanControl::GetGap

virtual GCoordinate GetGap () const

Interface Category:

API.

Purpose:

Returns the gap between the graphic label and the label. Classes deriving from TBooleanControl override this function if they want to change the default of 5 units.

Calling Context:

The framework (Layout) calls this function.

Parameters:

Takes no parameters.

Return Value:

Returns the current gap between the graphic label and the label.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TBooleanControl::GetPreferredSize

virtual TGPoint GetPreferredSize (GCoordinate maximumMainDimension =kInfinity) const

Interface Category:

API.

Purpose:

Returns the minimum size required by this control to display its graphic 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 function and is currently ignored.

Return Value:

Returns the preferred size for this control.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TBooleanControl::MouseDown

virtual bool MouseDown (TMouseDownEvent & mouseEvent)

Interface Category:

API.

Purpose:

Receives mouse-down events that occur inside the control and starts an interactor on the control (using CreateInteractor). Classes deriving from TBooleanControl can override this function to implement specific mouse-down handling.

Calling Context:

Called by the Input System framework; you do not need to call it directly yourself.

Parameters:

TMouseDownEvent & mouseEvent -The event that caused this function to be called.

Return Value:

Returns true if this control handled the mouse-down event, false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TBooleanControl::CreateInteractor

virtual TInteractor * CreateInteractor (const TGPoint & pt)

Interface Category:

API.

Purpose:

Creates an interactor for interacting on the control. Classes deriving from TBooleanControl can override this function to return different interactors.

Calling Context:

The framework calls this function when a mouse-down event is received. You do not need to call it directly yourself.

Parameters:

const TGPoint & pt -The location where the mouse-down event occurred.

Return Value:

Returns a TInteractor object or an object that inherits from TInteractor. TBooleanControl's implementation of this function returns a TBooleanControlInteractor which should be adequate for most bool controls.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TBooleanControl::HandleStateChanged

virtual void HandleStateChanged ()

Interface Category:

API.

Purpose:

Handles notification that the state object's state has changed. This function updates this control with the new state and calls ForceRedraw.

Calling Context:

This function is called by the framework (from StateChanged) when a notification is received from the state object that the state has changed. You never need to call it directly yourself.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TBooleanControl::ForceRedraw

virtual void ForceRedraw () const

Interface Category:

API.

Purpose:

Redraws this control. Calls Layout first, if necessary.

Calling Context:

Called by the framework (via HandleStateChanged) or you can 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: TBooleanControl::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:

The framework calls this function for you when the user interacts with the control via pointing device or keyboard equivalent. You may also call this function directly yourself.

Parameters:

bool -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:

None.

Member Function: TBooleanControl::SetBooleanState

virtual void SetBooleanState (MBooleanControlState :: EBooleanState newState)

Interface Category:

API.

Purpose:

Sets the state of this control's state object by calling SetBooleanState on its state object. This function redraws the control to indicate the new state.

Calling Context:

Called at the end of a user interaction. You can also call this function directly.

Parameters:

MBooleanControlState :: EBooleanState newState -The new state for this control's state object.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TBooleanControl::IsEnabled

virtual bool IsEnabled () const

Interface Category:

API.

Purpose:

Reports whether or not this control's state object is enabled. IsEnabled is defined in MDelegatingBooleanControl and MControl--both of which are parent classes to TBooleanControl. This function resolves the ambiguity by delegating to the MDelegatingBooleanControl function.

Calling Context:

Called by MouseDown to see if an interaction can take place. You can also call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if this control's state object is enabled, false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TBooleanControl::DrawContents

virtual void DrawContents (TGrafPort &) const

Interface Category:

API.

Purpose:

Draws this control.

Calling Context:

Called by the framework's view system when this control needs to redraw. You may call it yourself, also, if you have a special need for it.

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: TBooleanControl::Layout

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

Interface Category:

API.

Purpose:

Lays out this control. 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. This layout is sensitive to the last layout parameter given to the MControl::SetControlLayout. (MControl is a parent of TBooleanControl). So for example, a kLeftToRight layout results in the graphic label on the left and the other label on the right. After controlling the layout of the two labels relative to each other, the MControl::ELayout setting then controls the layout of the two as a combined unit inside the actualBounds, if the actualBounds is not NIL. By performing this layout in TBooleanControl, all classes deriving from TBooleanControl can share this logic by calling GetLayout.

Calling Context:

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

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

Parameters:

Takes no parameters.
const TGRect & actualBounds -The bounds within which to layout the control. 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: TBooleanControl::CreateGraphicLabel

TGraphicLabel

Interface Category:

API.

Purpose:

The framework definition of this function is that it creates and returns the graphic label that is used as part of the control's presentation. TBooleanControl supplies no default implementation of this function; deriving classes which you instantiate must implement this function. Implementations are allowed to return NIL sometimes or always.

Calling Context:

The framework calls this function once when the graphic is first needed.

Parameters:

Takes no parameters.

Return Value:

Returns a graphic label.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is a pure virtual function and must be overridden by classes deriving from TBooleanControl before the derived classes get instantiated into objects.

Member Function: TBooleanControl::GetLayout

virtual void GetLayout (TGRect & graphicBounds, TGRect & labelBounds) const

Interface Category:

API.

Purpose:

Returns the layout information previously calculated by the Layout function.

Calling Context:

Classes deriving from TBooleanControl can call this function directly.

Parameters:

TGRect & graphicBounds -The location to put the graphic label as returned by this function.
TGRect & labelBounds -The location to put the label 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: TBooleanControl::HandleAllocatedAreaChanged

virtual void HandleAllocatedAreaChanged (const TGArea & newArea)

Interface Category:

API.

Purpose:

Prompts the control to adjust its layout when its parent view changes the area allocated to the control.

Calling Context:

The framework calls this function; you should not call it directly.

Parameters:

const TGArea & newArea

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TBooleanControl::GetDefaultGraphicSize

virtual void GetDefaultGraphicSize (TGPoint & size) const

Interface Category:

API.

Purpose:

Reports the default size of the control's display. Since this is a pure virtual function, you must override it to return the default size.

Calling Context:

The framework calls this function.

Parameters:

TGPoint & size -This function fills in the default size for the control. The x-component of the point is the width, and the y-component of the point is the height.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TBooleanControl::Animate

virtual void Animate ()

Interface Category:

API.

Purpose:

Programatically select the control as if the user clicked on the control with a pointing device. This can be used to select a control through a keyboard based interface.

Calling Context:

This member function is currently not used by the framework -but it maybe used later when the framework supports a keyboard interface.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This member function simulates a mouse click over the control which results in SetPressed(true), SetBooleanState(xxxx), then SetPressed(false), were xxxx is the toggled state.

Member Function: TBooleanControl::NeedsClipping

virtual bool NeedsClipping ()

Interface Category:

API.

Purpose:

Reports whether any drawing done by this control needs view system assistance to ensure that the drawing is clipped to the area of the control. Objects that return false (the supplied default) will get their drawing performed faster, but without checking to prevent them from over-drawing things outside themselves. The default allocation constructor, supplied by TBooleanControl, initializes objects to report that they do not need clipping done by the view system.

Calling Context:

The framework calls this function when drawing the control.

Parameters:

Takes no parameters.

Return Value:

Returns true if the control ever draws outside its bounds.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TBooleanControl::SetControlLayout

virtual void SetControlLayout (MControl :: ELayout layout)

Interface Category:

API.

Purpose:

Sets the orientation of the control's graphic elements with respect to each other (right-to-left, left-to-right, top-to-bottom, or bottom-to-top). If that newly set orientation is different from the previously determined one, recalculates the positions of the graphic elements and posts an indication of the need to redraw the control.

Calling Context:

You can call this function directly.

Parameters:

MControl :: ELayout layout -The orientation of the control's graphic elements with respect to each other (right-to-left, left-to-right, top-to-bottom, or bottom-to-top)

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function overrides MControl's SetControlLayout function.

Member Function: TBooleanControl::SetVisibility

virtual void SetVisibility (bool visible)

Interface Category:

API.

Purpose:

Controls whether the control is visible or invisible when inside the viewable area of the display.

Calling Context:

You can call this function directly.

Parameters:

bool visible -Returns true to make the control visible, false to make it invisible.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function passes the visibility to both MControl and TView--two base classes which both have their own SetVisibility functions.

Member Function: TBooleanControl::GetVisibility

virtual bool GetVisibility () const

Interface Category:

API.

Purpose:

Reports whether the control is visible or invisible when inside the viewable area of the display.

Calling Context:

You can call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if the control is visible, otherwise false.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Because two base classes--MControl and TView--have their own GetVisibility functions, this function removes any ambiguity as to which will report a TBooleanControl's visibility; it delegates visibility reporting to TView.

Member Function: TBooleanControl::SetEnabled

virtual void SetEnabled (bool)

Interface Category:

API.

Purpose:

Enables the control. In the process, this function enables the control's label and its graphic label if it has them, and then posts a flag showing that its display needs to be redrawn.

Calling Context:

You can call this function directly. The framework calls it to enable controls, also.

Parameters:

bool enabled -true enables the control, false disables it.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TBooleanControl::HandleBeforeDisconnectionFromViewRoot

virtual void HandleBeforeDisconnectionFromViewRoot ()

Interface Category:

API.

Purpose:

Handles the tasks needed to be performed just prior to disconnecting a control from the view system.

Calling Context:

The framework calls this function for you; you do not need to call it directly yourself.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TBooleanControl::HandleAfterConnectionToViewRoot

virtual void HandleAfterConnectionToViewRoot ()

Interface Category:

API.

Purpose:

Handles the tasks needed to be performed just after connecting a control to the view system.

Calling Context:

The framework calls this function for you; you do not need to call it directly yourself.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TBooleanControl::GetBounds

virtual void GetBounds (TGArea & area) const

Interface Category:

API.

Purpose:

Reports the preferred bounds of the control rather than the current allocated area, so that the control can grow and shrink when adopted into a TLayoutView derived class.

Calling Context:

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

Parameters:

TGArea & area -Filled by this function with the bounds of the control.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

If the control has a fixed size, this function reports it, otherwise it reports the preferred size.

Member Function: TBooleanControl::GetGraphicLabel

virtual const TGraphicLabel * GetGraphicLabel () const

Interface Category:

API.

Purpose:

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

Calling Context:

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

Parameters:

Takes no parameters.

Return Value:

const TGraphicLabel * graphicLabel -Can be NIL.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

If no graphic label is associated with the control when this function is called, it will call CreateGraphicLabel and return the result, which can be NIL.

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