Class: MBooleanControlState

Declaration: BooleanControls.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MCollectible

Inherited By:

TShowLinksState TBooleanActionState

Purpose:

MBooleanControlState is an abstract base class that has Boolean state and is acted upon by a Boolean control when that control is manipulated by the user. A Boolean control state object can act on another object known as its client object or its target object. In other words, Boolean control states are functors that translate Boolean control protocol into the protocol of some target object. Boolean control state objects are adopted by a Boolean control. When the user manipulates the control that adopted the state object, the control changes the state object's state through calls to SetBooleanState. The state object, in turn, changes the state of its target object. When a control adopts a state object, the control asks the state object for any notification interests on its target object that the control can connect to. If the state object returns a notification interest, the control connects itself directly to the target object via the returned notification interest. If the target object changes state on its own (for example, through user interaction on some other objects), the target object directly notifies the control. When the control receives notification of state change directly from the target object, the control uses the state object to determine the target object's new state and updates its appearance accordingly. Because MBooleanControlState is an abstract base class, it must be derived from in order to be used within a Boolean control. TToggleButton, TRadioButton, and TCheckBox interact with an MBooleanControlState-derived class.

Instantiation:

Abstract base class; do not allocate.

Deriving Classes:

This class must be derived from to be used in a Boolean control. Classes deriving from MBooleanControlState should override GetBooleanState, SetBooleanState, IsEnabled, and AddInterests.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: MBooleanControlState::MBooleanControlState

MBooleanControlState ()
MBooleanControlState (const MBooleanControlState &)

Interface Category:

API.

Purpose:

Default constructor.
Copy constructor.

Calling Context:

Called by the stream-in operators.
Called to copy an object.

Parameters:

Takes no parameters.
const MBooleanControlState & -The object to be copied.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

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

Member Function: MBooleanControlState::~MBooleanControlState

virtual ~ MBooleanControlState ()

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

MBooleanControlState & operator =(const MBooleanControlState &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

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

Parameters:

const MBooleanControlState & -The object to be copied.

Return Value:

MBooleanControlState & -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: MBooleanControlState::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: MBooleanControlState::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: MBooleanControlState::GetBooleanState

virtual EBooleanState GetBooleanState () const

Interface Category:

API.

Purpose:

Returns the current state of the target object. The target object's state can be one of the values defined by EBooleanState: kUnknown, false, or true. For example, if the target object is a text selection, the state may indicate whether or not every character in the selection has the bold text style attribute. If some characters have the style and some don't, this function returns kUnknown. If none of the characters have the style, this function returns false, and lastly, if all the characters were bold, this function returns true. Classes deriving from MBooleanControlState override this function to translate between the Boolean control's protocol and the protocol of the target object. The Boolean control interacting with this state object will present the result of this function to the user in some fashion.

Calling Context:

Called by the Boolean control using this state object.

Parameters:

Takes no parameters.

Return Value:

Returns an EBooleanState value indicating the current state of the target object.

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 MBooleanControlState.

Member Function: MBooleanControlState::SetBooleanState

virtual void SetBooleanState (EBooleanState newState)

Interface Category:

API.

Purpose:

Changes the state of this state object's target object. The target object's state can be one of the values defined by EBooleanState: kUnknown, false, or true. For example, if the target object is a text selection, the state may translate a change to false to mean to remove the bold text style attribute from all characters in the text selection. Likewise, it may translate a change to true to mean to set the bold text style attribute on all characters in the text selection. Classes deriving from MBooleanControlState override this function to translate between the Boolean control's protocol and the protocol of the target object. The Boolean control interacting with this Boolean control state will present the result of this function to the user in some fashion.

Calling Context:

The Boolean controls call this function when the user manipulates the Boolean control containing this state object. This function will never be called until IsEnabled returns true.

Parameters:

EBooleanState newState -The new state of the target object.

Return Value:

None.

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 MBooleanControlState.

Member Function: MBooleanControlState::IsEnabled

virtual bool IsEnabled () const

Interface Category:

API.

Purpose:

Determines whether or not the target object of this Boolean control state is enabled. A return value of true indicates that the target object is enabled and can accept state changes (the Boolean control owning this state object may call SetBooleanState). A return value of false indicates that the target object is disabled and can not accept state changes (the control owning this state object may not call SetBooleanState). MBooleanControlState's implementation of this function always returns true. Classes deriving from MBooleanControlState can implement this function if it is not always valid to call SetBooleanState.

Calling Context:

Boolean controls call this function during initialization or when a notification is received from this state object.

Parameters:

Takes no parameters.

Return Value:

Returns true if the target object is enabled and SetBooleanState can be called, false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MBooleanControlState::AddInterests

virtual void AddInterests (TSetOf < TInterest > & set)

Interface Category:

API.

Purpose:

The framework defines the responsibility of an AddInterests function to be to establish a notification connection between the state object and an arbitrary set of other objects capable of such a connection. The framework uses AddInterests to establish a connection from the state object to the Boolean control that owns it. Such a connection is used to notify the control that the state associated with it has changed. The ability to create such connections to other objects allows you to override AddInterests to connect a control so that it is automatically notified if a logical state changes outside the user's control, or indirectly as a result of the user manipulating something else. The AddInterests function of a control state allows the control-state object to serve as a conduit of notifications from other target objects to the Boolean control. When the control receives a notification, it will update its presentation according to new state values returned from the control state. The default implementation, supplied by MBooleanControlState, of AddInterests is an empty function. This empty function (passively) leaves an empty set (of TInterests) passed to it by reference, empty. By leaving that empty set empty, AddInterests indicates that no notification connection is to be established. Classes deriving from MBooleanControlState can implement this function and provide one or more TInterest objects if they want to establish a notification connection with the Boolean control that owns this state object.

Calling Context:

AddInterests is called by the Boolean control that owns the state object when it is the right time to create the notification connection.

Parameters:

TSetOf < TInterest > & set -The set of interests for the Boolean control to connect to.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MBooleanControlState::SetPressed

virtual void SetPressed(bool pressed)

Interface Category:

API.

Purpose:

Notifies the state of changes in the pressed state of the control. The default implementation, supplied by MBooleanControlState, does nothing. Derived classes supply useful behavior.

Calling Context:

Boolean controls call this function when the user interacts with the control.

Parameters:

bool pressed -Returns true if the control is being pressed, false otherwise.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MBooleanControlState::GetLabel

virtual const TLabel* GetLabel() const

Interface Category:

API.

Purpose:

The framework defines the responsibility of this function to be the provision of read-only access to a control's label. The default implementation, supplied by MBooleanControlState, always returns NIL. Derived classes supply useful implementations.

Calling Context:

Boolean controls call this function when the state is adopted into the control and when the control receives state change notifications.

Parameters:

Takes no parameters.

Return Value:

The label returned from this function overrides any label that has been adopted into the control directly.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is only used if the developer wants to dynamically change the label at runtime. The developer should ensure that this label is localizable. The label is not adopted; it is owned by the state.

Member Function: MBooleanControlState::SetControlView

virtual void SetControlView(const TViewHandle& owner)

Interface Category:

API.

Purpose:

Provides the state with a handle to the control itself. This handle will be stored by this class and used by GetControlView.

Calling Context:

Boolean controls call this function when the state is adopted into the control.

Parameters:

const TViewHandle& owner -A handle to the control itself.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MBooleanControlState::GetControlView

virtual TView* GetControlView()

Interface Category:

API.

Purpose:

Queries the view that has been previously set by SetControlView.

Calling Context:

You can call this function directly.

Parameters:

Takes no parameters.

Return Value:

TView* -The control's view, or NIL if there is no control.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MBooleanControlState::CanSetToFalse

virtual bool CanSetToFalse () const

Interface Category:

API.

Purpose:

The framework calls this function to discover whether the control can be set to false (off) by the user. The default implementation, supplied by MBooleanControlState, always returns true. This is how a radio button group can be implemented where there must be at least one button selected.

Calling Context:

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

Parameters:

Takes no parameters.

Return Value:

Returns true if the user should be allowed to set the state of the control to false. The default is true.

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.