Class: MDelegatingBooleanControl

Declaration: BooleanControls.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

None.

Inherited By:

TBooleanControl TBooleanMenuItem

Purpose:

MDelegatingBooleanControl is a mixin class that defines the protocol for adopting a Boolean control state and for delegating to that state. An MDelegatingBooleanControl relies on a control state object to set the state of the target object and to remember what the state is. (The target object is whatever the user affects by manipulating the control.) The MDelegatingBooleanControl class also defines the protocol for establishing a notification connection between a Boolean control and its adopted state. This class is the base class for all Boolean controls.

Instantiation:

Abstract base class; do not allocate.

Deriving Classes:

MDelegatingBooleanControl is a mixin class--it cannot be instantiated and must be derived from. Classes deriving from MDelegatingBooleanControl provide the request processor and override HandleStateChanged.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: MDelegatingBooleanControl::MDelegatingBooleanControl

MDelegatingBooleanControl ()
MDelegatingBooleanControl (MBooleanControlState * delegate)
MDelegatingBooleanControl (const MDelegatingBooleanControl &)

Interface Category:

API.

Purpose:

Default constructor.
Creates a new MDelegatingBooleanControl object and adopts the specified state object.
Copy constructor. If the control being copied had adopted its state object, then the state object is cloned, otherwise a pointer to the state object is copied and marked as not adopted. Non-adopted state objects are not flattened and resurrected. This function also copies the pointer to the request processor.

Calling Context:

Called by the stream-in operators or by clients.
Called when you want to adopt a state at construction time. You can also use AdoptState and SetState at any time.
Called to copy an object.

Parameters:

Takes no parameters.
MBooleanControlState * delegate -The state object to be adopted.
const MDelegatingBooleanControl & -The object to be copied.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

MDelegatingBooleanControl is a mixin class and cannot be instantiated.

Member Function: MDelegatingBooleanControl::~MDelegatingBooleanControl

virtual ~ MDelegatingBooleanControl ()

Interface Category:

API.

Purpose:

Destructor. This function also breaks the notification connection with the existing state object and deletes the state object if it was adopted.

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

MDelegatingBooleanControl & operator =(const MDelegatingBooleanControl &)

Interface Category:

API.

Purpose:

Assignment operator. If the control being copied had adopted its state object, then the state object is cloned, otherwise a pointer to the state object is copied and marked as not adopted. Non-adopted state objects are not flattened and resurrected. This function also copies the pointer to the request processor. This function breaks the notification connection with the existing state object and deletes the state object if it was adopted. This function then tries to establish a connection with the new state object.

Calling Context:

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

Parameters:

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

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

Interface Category:

API.

Purpose:

Stream-out operator. This only streams out the state object if the state object is adopted.

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: MDelegatingBooleanControl::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: MDelegatingBooleanControl::AdoptState

virtual void AdoptState (MBooleanControlState * state)

Interface Category:

API.

Purpose:

Adopts the specified state object. This class can only contain a single state object at a time. So the new state object replaces any state object previously adopted in AdoptState or set by SetState. If the previous state object had been adopted by this control, this function deletes it. If this control has a request processor, this function attempts to establish a notification connection with the new state object. This control uses the new state object for subsequent SetBooleanState and IsEnabled function calls.

Calling Context:

You can call this function directly.

Parameters:

MBooleanControlState * state -The state object to be adopted.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MDelegatingBooleanControl::SetState

virtual void SetState (MBooleanControlState * state)

Interface Category:

API.

Purpose:

Sets this control's state object. This function is the same as AdoptState, except the new state object is not adopted. This class can only contain a single state object at a time. So the new state object replaces any state object previously adopted in AdoptState or set by SetState. If the previous state object had been adopted by this control, this function deletes it. When a control has a state object that is not adopted: (1) the state object will not be automatically deleted, (2) the state object will not be streamed out, and (3) if this MDelegatingBooleanControl is copied, the state object is copied, not cloned.

Calling Context:

You can call this function directly.

Parameters:

MBooleanControlState * state -The new state object for this control.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Don't confuse this function with SetBooleanState, which sets the state object's state (from on to off for example), instead of linking a state object to a control.

Member Function: MDelegatingBooleanControl::GetState

virtual MBooleanControlState * GetState () const

Interface Category:

API.

Purpose:

Returns a pointer to the state object that was set in SetState or adopted in AdoptState.

Calling Context:

You can call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a pointer to the current state object. This function never returns NIL, because it creates (and adopts) a simple Boolean state object if none has been previously set or adopted.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MDelegatingBooleanControl::OrphanState

virtual MBooleanControlState * OrphanState ()

Interface Category:

API.

Purpose:

Removes this control's reference to the currently adopted state object so that it's no longer owned by the MDelegatingBooleanControl. This function does not delete the orphaned state object.

Calling Context:

You can call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a pointer to the orphaned state object. This function returns NIL if no state object was adopted. Note: if no state object was explicitly set or adopted and you call GetState, and then you call OrphanState, this function returns the simple bool state object created by GetState. If you the call GetState again, GetState will create another simple bool state object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MDelegatingBooleanControl::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 is primarily a convenience function for calling SetBooleanState on this control's state object. Other state object functions can be called directly by calling the appropriate function on the object returned by GetState.

Calling Context:

Clients or derived classes can call this function directly.

Parameters:

MBooleanControlState :: EBooleanState newState -The new state to pass on to the state object.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MDelegatingBooleanControl::IsEnabled

virtual bool IsEnabled () const

Interface Category:

API.

Purpose:

Determines the state of this control's state object by calling IsEnabled on its state object. This is primarily a convenience function for calling IsEnabled on this control's state object. Other state object functions can be called directly by calling the appropriate function on the object returned by GetState.

Calling Context:

Clients or derived classes can call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if the state object is enabled, false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MDelegatingBooleanControl::SetPressed

virtual void SetPressed(bool pressed)

Interface Category:

API.

Purpose:

SetPressed is called when the user is interacting with the boolean control. This is primarily a convenience function for calling SetPressed on this control's state object. Other state object functions can be called directly by calling the appropriate function on the object returned by GetState.

Calling Context:

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

Parameters:

bool pressed -Whether or not the control is being pressed.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MDelegatingBooleanControl::GetLabel

virtual const TLabel* GetLabel() const

Interface Category:

API.

Purpose:

Provides read-only access to a control's label. This is primarily a convenience function for calling GetLabel on this control's state object. Other state object functions can be called directly by calling the appropriate function on the object returned by GetState.

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:

const TLabel* -The control's label, as known by the state object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function delegates the task of getting the control's label to the control's state object. If no state object has been adopted, this function returns NIL.

Member Function: MDelegatingBooleanControl::SetControlView

virtual void SetControlView(const TViewHandle& owner)

Interface Category:

API.

Purpose:

Informs the state that the control has been placed in the owner view. This is primarily a convenience function for calling SetControlView on this control's state object. Other state-object functions can be called directly by calling the appropriate function on the object returned by GetState.

Calling Context:

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

Parameters:

const TViewHandle& owner -A handle to the owner view. (That view is the same object as the control itself.)

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MDelegatingBooleanControl::GetControlView

virtual TView* GetControlView()

Interface Category:

API.

Purpose:

Provides access to the view that has been previously set by SetControlView. This is primarily a convenience function for calling GetControlView on this control's state object. Other state object functions can be called directly by calling the appropriate function on the object returned by GetState.

Calling Context:

Clients or derived classes can call this function directly.

Parameters:

Takes no parameters.

Return Value:

TView* -The control's view.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function will return NIL if no state-object has been adopted.

Member Function: MDelegatingBooleanControl::SetRequestProcessor

virtual void SetRequestProcessor (TRequestProcessor * proc)

Interface Category:

API.

Purpose:

Sets the request processor that is required to establish a notification connection with the state object. This function must be called in order to establish the notification connection with the state object because a TRequestBasedMemberFunctionConnectionTo connection is used.

Calling Context:

This function must be called before HandleStateChanged is be called.

Parameters:

TRequestProcessor * proc -The request processor to use for serializing events, notifications, and view system updates.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MDelegatingBooleanControl::StateChanged

virtual void StateChanged (const TNotification &)

Interface Category:

API.

Purpose:

Called by the Notification framework whenever one of the interests previously returned from AddInterests is posted. StateChanged calls HandleStateChanged; override HandleStateChanged to add functionality to a class derived from MDelegatingBooleanControl.

Calling Context:

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

Parameters:

const TNotification & -The notification causing this function to be called.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MDelegatingBooleanControl::HandleStateChanged

virtual void HandleStateChanged ()

Interface Category:

API.

Purpose:

Handles notification that the state object's state has changed. Classes deriving from MDelegatingBooleanControl override this function to update their presentation of the state.

Calling Context:

Called from StateChanged.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MDelegatingBooleanControl::GetBooleanState

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

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The current Boolean state.

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.