Class: TBooleanControlGroup

Declaration: BooleanControlGroups.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TView, MControl, MActionTarget, MBooleanControlActionHandler

Inherited By:

None.

Purpose:

A TBooleanControlGroup provides a grouping mechanism for Boolean controls such as radio buttons. It enforces mutual exclusivity on the Boolean controls in a group, guaranteeing that, at most, one Boolean control is turned on at any time. A user of this class has the option of either taking complete responsibility for laying out the Boolean controls within the group or adopting a container view into the group (such as a TBoxView) that performs some automatic layout on Boolean controls adopted into the group. Just like other HI controls, the TBooleanControlGroup has a control state (MIntegerControlState) whose value corresponds to the ordinal value of the Boolean control that is turned on. The ordinal values of the Boolean controls correspond to the order in which the Boolean controls are adopted into the group. As for other controls, you can adopt your own control state derived class that implements some special functionality when the group changes state (that is, when a Boolean control within the group changes state). To create a TBooleanControlGroup, either use the convenience functions of TDialogUtilities (MakeRadioButtonGroup, MakeBooleanControlGroup, MakeRadioButtonInGroup) or create an object from scratch by instantiating it, adopting one or more Boolean controls into it, and adopting the group into a parent view. Once you have created a TBooleanControlGroup, your application can get its state value at any time.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

This class is designed to be used directly; there is normally no need to derive from TBooleanControlGroup unless you want to modify its functionality.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Other Considerations:

None.

Member Function: TBooleanControlGroup::TBooleanControlGroup

TBooleanControlGroup ()
TBooleanControlGroup (bool oneControlAlwaysSelected, MIntegerControlState * adoptedGroupState =NIL)
TBooleanControlGroup (const TGArea & viewArea, bool oneControlAlwaysSelected =true, MIntegerControlState * adoptedGroupState =NIL)

Interface Category:

API.

Purpose:

If you are not using TDialogUtilities helper member functions, call one of these constructors.

Default constructor.
Constructs a control group in which the mutual exclusivity of controls can be set with oneControlAlwaysSelected, and in which the control state can be set to adoptedGroupState. oneControlAlwaysSelected controls whether Boolean controls can be interactively turned off or if the only way to turn one off is by turning another on. This setting doesn't affect the ability to turn all Boolean controls off programmatically.
Constructor that additionally specifies the view area.

Calling Context:

Called by the stream-in operators and directly.
Call this function directly.
Call this function directly.

Parameters:

Takes no parameters.
bool oneControlAlwaysSelected -If true, a Boolean control in the group can be interactively turned off only by turning another one on (thus, there must be one control selected at all times). If false, you can interactively turn off Boolean controls. This setting doesn't affect the ability to turn all Boolean controls off programmatically.
MIntegerControlState * adoptedGroupState =NIL -The control state to be adopted.
const TGArea & viewArea -The area in which the control group will get laid out.
bool oneControlAlwaysSelected =true -If true, a Boolean control in the group can be interactively turned off only by turning another one on (thus, there must be one control selected at all times). If false, you can interactively turn off Boolean controls. This setting doesn't affect the ability to turn all Boolean controls off programmatically.
MIntegerControlState * adoptedGroupState =NIL -The control state to be adopted.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

TDialogUtilities provides convenient functions (MakeRadioButtonGroup, MakeBooleanControlGroup, MakeRadioButtonInGroup) as an alternative to instantiation with these constructors. If you do not specify an area for the group or call SetAllocatedArea on the group at some point, the group automatically resizes itself to the preferred bounds of its container, if one exists. If you accept the default value for oneControlAlwaysSelected, then a Boolean control in the group can be turned off interactively only by turning another one on. A default state is created to maintain the state value if you don't adopt one yourself.

Member Function: TBooleanControlGroup::~TBooleanControlGroup

virtual ~ TBooleanControlGroup ()

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:

The destructor doesn't delete its Boolean controls. They are deleted by the view destructor. The destructor deletes any other objects it owns.

Member Function: TBooleanControlGroup::AdoptControl

virtual void AdoptControl (TBooleanControl *)

Interface Category:

API.

Purpose:

Adds the control to the grouping mechanism and adopts it into the container view (if one exists) or the group view. Boolean controls are indexed within the group from 0 to n-1 according to the order in which you adopt them. Note: Boolean controls have their own states. You can set a Boolean control's state to true before adopting it if you want it to be the selected one in the group. You can adopt a control state into the Boolean control before adopting it into the group if you want the Boolean control state to do something in addition to the group control state when the Boolean control is set. The order of execution is: group state followed by Boolean control state. Once you have adopted a Boolean control into the group you cannot access its control state via GetState until you orphan it again.

Calling Context:

Call this function directly. Call this instead of calling AdoptChild directly on the group.

Parameters:

TBooleanControl * -The control to be adopted into the group.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The converse of this function is OrphanControl.

Member Function: TBooleanControlGroup::OrphanControl

virtual TBooleanControl * OrphanControl (long index)
virtual TBooleanControl * OrphanControl (const TBooleanControl &)

Interface Category:

API.

Purpose:

Removes the control from the grouping mechanism and orphans it from its parent view.

Specifies the control by its index number.
Specifies the control by a reference to it.

Calling Context:

Call this function directly. Call this instead of calling OrphanChild directly on the group.
Call this function directly. Call this instead of calling OrphanChild directly on the group.

Parameters:

long index -The same number that GetSelected returns when this control is the selected one. When controls are adopted into the group, they are assigned an index, beginning at 0 and incrementing when a new control is adopted.
const TBooleanControl & -A reference to the control to be orphaned.

Return Value:

TBooleanControl * OrphanControl -The orphaned control.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

After you orphan a control, you can access its control state again via GetState. This function is the converse of AdoptControl. This function will decrement the index of any adopted or bound control that has a higher index than the one being orphaned.

Member Function: TBooleanControlGroup::AdoptContainerView

virtual void AdoptContainerView (TView *)

Interface Category:

API.

Purpose:

Provides a mechanism for automatic layout of controls. Call AdoptContainerView before adopting Boolean controls if you want them adopted into a container view rather than the group. This is useful if you want a container view such as a TBoxView to automatically layout the group's Boolean controls.

Calling Context:

Call this function directly. Each time you call this function, any Boolean controls already in the group are orphaned from their current parent and adopted into this container (unless you pass NIL, in which case the Boolean controls are adopted into the group view). The container view is resized to the group's allocated area upon its adoption.

Parameters:

TView * -The view to be adopted for the group.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Don't confuse this with SetContainerView, which is a helper function called for you by AdoptContainerView. Clients should call AdoptContainerView, not SetContainerView.

Member Function: TBooleanControlGroup::GetControl

virtual TBooleanControl * GetControl (long index) const

Interface Category:

API.

Purpose:

Provides access to a control in the group, for example, if you want to modify its layout.

Calling Context:

Call this function directly.

Parameters:

long index -The ordinal number of the control--the same number that GetSelected returns when this control is the selected one. When controls are adopted into the group, they are assigned an index, beginning at 0 and incrementing whenever a new control is adopted.

Return Value:

TBooleanControl * GetControl -The control with the specified index, or NIL if there is no control with the specified index.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The Boolean control's state becomes inaccessible upon adoption into the group, so do not attempt to access the state until after you've removed the Boolean control from the group.

Member Function: TBooleanControlGroup::GetSelectedControl

virtual TBooleanControl * GetSelectedControl () const

Interface Category:

API.

Purpose:

Provides access to the selected control, for example, if you want to modify its layout.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

TBooleanControl * selectedControl -The control that is presently selected in the group, or NIL if no control is currently selected.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

If you want the index number of, rather than a pointer to, the selected control, use GetSelected. The Boolean control's state becomes inaccessible upon adoption into the group so do not attempt to access the state until after you've removed the Boolean control from the group.

Member Function: TBooleanControlGroup::SetSelected

virtual void SetSelected (const TBooleanControl &)
virtual void SetSelected (long index)

Interface Category:

API.

Purpose:

Allows you to set the the state value of the group programmatically. The state value of the group is the index number of the control that is selected. For a control in a TBooleanControlGroup, being selected means that it is turned on and all the other controls in the group are turned off.

Specifies the control by a reference to it.
Specifies the control by its index number.

Calling Context:

Call these functions directly.

Parameters:

const TBooleanControl & controlToSelect -Allows you to specify the control by a reference to it.
long index -Allows you to specify the control by its ordinal number. When controls are adopted into the group, they are assigned an index, beginning at 0 and incrementing when a new control is adopted. The index must be an ordinal value of one of the Boolean controls in the group or else the group state becomes invalid.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function turns off the currently selected Boolean control before turning on the specified Boolean control. GetSelected is the converse of this function and returns the ordinal value of the Boolean control that is turned on.

Member Function: TBooleanControlGroup::DeselectAll

virtual void DeselectAll ()

Interface Category:

API.

Purpose:

Turns off all the controls in the group.

Calling Context:

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:

When all Boolean controls are deselected, GetSelected returns kInvalidIndex.

Member Function: TBooleanControlGroup::GetSelected

virtual long GetSelected () const

Interface Category:

API.

Purpose:

Returns the ordinal value of the Boolean control that is turned on.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The ordinal number of the Boolean control that is selected, or kInvalidIndex if none of the controls are selected. When controls are adopted into the group, they are assigned an ordinal index, beginning at 0 and incrementing when a new control is adopted.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

SetSelected allows you to programmatically change the value that this function returns.

Member Function: TBooleanControlGroup::GetControlCount

virtual long GetControlCount () const

Interface Category:

API.

Purpose:

Returns the number of Boolean controls in the group.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The number of Boolean controls in the group.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TBooleanControlGroup::AdoptState

virtual void AdoptState (MIntegerControlState * adoptedGroupState)

Interface Category:

API.

Purpose:

Adopts a control state for the group.

Calling Context:

Call this function directly.

Parameters:

MIntegerControlState * adoptedGroupState -The control state to be adopted for the group.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

When a TBooleanControlGroup is deleted, it deletes any states previously linked in using AdoptState, but not states that were linked in using SetState. Also note that AdoptState deletes any states previously linked in using AdoptState, but not states that were linked in using SetState. The converse of this function is OrphanState. The state previously adopted can be read with GetState.

Member Function: TBooleanControlGroup::OrphanState

virtual MIntegerControlState * OrphanState ()

Interface Category:

API.

Purpose:

Orphans the control state previously adopted by the group.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

MIntegerControlState * orphanedState -The orphaned control state.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is the converse of AdoptState. The state previously adopted (and therefore available to be orphaned) can be read with GetState.

Member Function: TBooleanControlGroup::SetState

virtual void SetState (MIntegerControlState * sharedGroupState)

Interface Category:

API.

Purpose:

Assigns a control state to the group. Use this function when the control state is to be shared with other controls.

Calling Context:

Call this function directly.

Parameters:

MIntegerControlState * sharedGroupState -The state to be assigned to the group.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function deletes any states previously linked in using AdoptState, but not states that were linked in using SetState. This function is the converse of GetState. SetSelected allows you to specify a control to be the selected one. This changes the value contained inside the group control state object to the index number of the control you select.

Member Function: TBooleanControlGroup::GetState

virtual const MIntegerControlState * GetState () const

Interface Category:

API.

Purpose:

Reports the control state currently assigned to the group.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

const MIntegerControlState * theGroupState -The control state currently assigned to the group. Guaranteed to be non-NIL.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is guaranteed to return a non-NIL value because the group creates a default state if none is adopted or set. This function is the converse of SetState.

Member Function: TBooleanControlGroup::SetEnabled

virtual void SetEnabled (bool)

Interface Category:

API.

Purpose:

Enables or disables the group. As a result of this call, the group enables or disables all of its Boolean controls according to the flag passed. A disabled control is not interactive, while an enabled control functions normally.

Calling Context:

You do not need to call this function directly; let the framework call it for you.

Parameters:

bool -true to enable the controls, false to disable them.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides the inherited MControl function. Note: GetEnabled is not overridden.

Member Function: TBooleanControlGroup::GetBounds

virtual void GetBounds (TGArea & area) const

Interface Category:

API.

Purpose:

Returns the preferred bounds of the group view. That is, the preferred bounds of the container, if one exists.

Calling Context:

Call this function directly.

Parameters:

TGArea & area -The preferred bounds of the group view.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides the inherited TView function. There is no corresponding SetBounds function.

Member Function: TBooleanControlGroup::operator>>=

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

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

TStream & destination -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: TBooleanControlGroup::operator<<=

virtual TStream & operator <<= (TStream & source)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

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

Return Value:

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

Exceptions:

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

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TBooleanControlGroup::BindControlToGroup

virtual void BindControlToGroup (TBooleanControl * alias)

Interface Category:

API.

Purpose:

Includes a control in the grouping mechanism while leaving control of the view hierarchy to the client. This function is provided for advanced programmers who need to create Boolean control groups with specialized view hierarchies. When controls are adopted or bound into the group, they are assigned an index, beginning at 0 and incrementing when a new control is adopted.

Calling Context:

TBooleanControlGroup's framework calls this function for you when you call AdoptControl. You generally do not need to call this function directly, unless you want to create a specialized view hierarchy.

Parameters:

TBooleanControl * alias -The control whose state will be bound to the group.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The converse of this function is UnbindControlFromGroup. When you use this function you are responsible for adopting the Boolean control (via AdoptChild) into the group's view hierarchy. Boolean controls needn't be direct subviews of the group, but they must be adopted somewhere into the hierarchy beneath the group.

Member Function: TBooleanControlGroup::UnbindControlFromGroup

virtual TBooleanControl * UnbindControlFromGroup (long index)
virtual TBooleanControl * UnbindControlFromGroup (const TBooleanControl &)

Interface Category:

API.

Purpose:

Removes a control from the grouping mechanism without affecting its position in the view hierarchy. This function is provided for advanced programmers who need to create Boolean control groups with specialized view hierarchies.

Specifies the control by its index.
Specifies the control by a reference to it.

Calling Context:

Call this function directly, but do so only if you previously called BindControlToGroup.
Call this function directly, but do so only if you previously called BindControlToGroup.

Parameters:

long index -The ordinal number of the control to be unbound.
const TBooleanControl & -A reference to the control to be unbound.

Return Value:

TBooleanControl * boundControl -The control that has just been unbound from the group.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is the converse of BindControlToGroup. This function decrements the index of any adopted or bound control that has a higher index than the one being unbound.

Member Function: TBooleanControlGroup::HandleAllocatedAreaChanged

virtual void HandleAllocatedAreaChanged (const TGArea & newArea)

Interface Category:

API.

Purpose:

Overridden to give the container view (if any) a chance to re-layout when the group re-lays out.

Calling Context:

Do not call this function directly; let the framework call it for you.

Parameters:

const TGArea & newArea

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides the inherited TView function.

Member Function: TBooleanControlGroup::HandleBooleanControlAction

virtual bool HandleBooleanControlAction (TBooleanControlAction & action)

Interface Category:

API.

Purpose:

Maintains mutual exclusivity and keeps the group state updated.

Calling Context:

Do not call this function directly; let the framework call it for you. Called in response to a change in the setting of a Boolean control.

Parameters:

TBooleanControlAction & action -The Boolean control action generated by the Boolean control.

Return Value:

Returns true if it handled the action (that is, the action was the special type generated by a Boolean control in this group when its value changes).

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TBooleanControlGroup::NeedsClipping

virtual bool NeedsClipping ()

Interface Category:

API.

Purpose:

Overridden to always return false; this function tells the framework whether the group's view needs clipping. A TBooleanControlGroup should never need to draw outside its view, so its drawing never needs to be checked for clipping. Overriding this function in this way speeds up the class' drawing routines.

Calling Context:

You never need to call this function. You might need to override this function if you had a derived variation on TBooleanControlGroup that needed to draw outside the group's view--a highly unlikely combination of development choices.

Parameters:

Takes no parameters.

Return Value:

Returns false.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides the inherited TView function.

Member Function: TBooleanControlGroup::HandleStateChanged

virtual void HandleStateChanged ()

Interface Category:

API.

Purpose:

Handles notification that the Boolean control group's state has changed. It gives the group an opportunity to update its state when a change occurs behind its back.

Calling Context:

Called from AdoptState, SetState, OrphanState, and StateChanged. Do not call this function directly; let the framework call it for you.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is protected.

Member Function: TBooleanControlGroup::SetContainerView

virtual void SetContainerView (TView *)

Interface Category:

API.

Purpose:

Assigns the container view to a view handle data field.

Calling Context:

Called for you when the container is adopted.

Parameters:

TView * containerView -The container view.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is protected. The converse of this function is GetContainerView. This is only a helper function for use by AdoptContainerView.

Member Function: TBooleanControlGroup::GetContainerView

virtual TView * GetContainerView () const

Interface Category:

API.

Purpose:

Reports the container view of the group.

Calling Context:

Usually called for you.

Parameters:

Takes no parameters.

Return Value:

A pointer to the container view.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function reads what SetContainerView assigns. This function is protected.

Member Function: TBooleanControlGroup::HandleAfterConnectionToViewRoot

virtual void HandleAfterConnectionToViewRoot ()

Interface Category:

API.

Purpose:

The default implementation of this function delegates to TView, establishes a notification connection to the control state, and attempts to auto-resize the group to its preferred bounds if you haven't allocated any area to it explicitly.

Calling Context:

Do not call this function directly; let the framework call it for you. Called by the framework after connection to the view root.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This protected function overrides the inherited TView function.

Member Function: TBooleanControlGroup::HandleBeforeDisconnectionFromViewRoot

virtual void HandleBeforeDisconnectionFromViewRoot ()

Interface Category:

API.

Purpose:

Delegates to TView, and breaks the notification connection with the control state.

Calling Context:

Do not call this function directly; let the framework call it for you. Called by the framework just before it disconnects from the view root.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This protected function overrides the inherited TView function.

Member Function: TBooleanControlGroup::GetOpaquelyDrawnArea

virtual void GetOpaquelyDrawnArea (TGArea & opaqueArea)

Interface Category:

API.

Purpose:

A TView override that indicates how much of the allocated area of the view (in this case, the TBooleanControlGroup view) draws opaquely. The TView default behavior is to specify that the entire allocated area is drawn opaquely. A TBooleanControlGroup object is a view, but it doesn't actually draw anything in its area; it's transparent (the drawing of the controls in the group is handled separately from the control group view). This function thus returns an empty area to indicate that none of the TBooleanControlGroup's area is drawn opaquely.

Calling Context:

Called by the View system to determine the area that the view actually draws, and for optimizing damage generation and repair.

Parameters:

TGArea & opaqueArea -An empty area is returned, indicating that none of the TBooleanControlGroup's area is drawn opaquely.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides the inherited TView function.

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