Class: MDelegatingMomentaryControl

Declaration: MomentaryControls.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

None.

Inherited By:

TMomentaryControl TMomentaryMenuItem

Purpose:

MDelegatingMomentaryControl is a mixin class that defines protocol for adopting a momentary control state and for delegating to that state. This class also defines protocol for establishing a notification connection between the control and its adopted state. This class is the base class for all momentary controls.

Instantiation:

Abstract base class; do not allocate.

Deriving Classes:

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

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: MDelegatingMomentaryControl::MDelegatingMomentaryControl

MDelegatingMomentaryControl ()
MDelegatingMomentaryControl (MMomentaryControlState * state)
MDelegatingMomentaryControl (const MDelegatingMomentaryControl &)

Interface Category:

API.

Purpose:

Default constructor.
Creates a new delegating momentary control that 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. You can also call this function directly.
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.
MMomentaryControlState * state -The state object to be adopted.
const MDelegatingMomentaryControl & -The object to be copied.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MDelegatingMomentaryControl::~MDelegatingMomentaryControl

virtual ~ MDelegatingMomentaryControl ()

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

MDelegatingMomentaryControl & operator =(const MDelegatingMomentaryControl &)

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

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

virtual void AdoptState (MMomentaryControlState * 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 function calls.

Calling Context:

Call this function directly.

Parameters:

MMomentaryControlState * state -The state to be adopted.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MDelegatingMomentaryControl::SetState

virtual void SetState (MMomentaryControlState * state)

Interface Category:

API.

Purpose:

SetState 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 is not automatically deleted, (2) the state object is not streamed out, and (3) if this MDelegatingMomentaryControl is copied, the state object is copied, not cloned.

Calling Context:

Call this function directly.

Parameters:

MMomentaryControlState * 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:

None.

Member Function: MDelegatingMomentaryControl::GetState

virtual MMomentaryControlState * GetState () const

Interface Category:

API.

Purpose:

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

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a pointer to the current state object. This function can return NIL.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MDelegatingMomentaryControl::OrphanState

virtual MMomentaryControlState * 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 MDelegatingMomentaryControl. This function does not delete the orphaned state object.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a pointer to the orphaned state object. This member function returns NIL if no state object was adopted.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MDelegatingMomentaryControl::Select

virtual void Select ()

Interface Category:

API.

Purpose:

Selects this control's state object by calling Select on the state object. This is primarily a convenience function for calling Select on this control's state object. State object functions can be called directly by calling the appropriate function on the object returned by GetState.

Calling Context:

Called directly by clients or derived classes.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MDelegatingMomentaryControl::IsEnabled

virtual bool IsEnabled () const

Interface Category:

API.

Purpose:

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

Calling Context:

Called directly by clients or derived classes.

Parameters:

Takes no parameters.

Return Value:

Returns the result from the state object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MDelegatingMomentaryControl::SetPressed

virtual void SetPressed(bool pressed)

Interface Category:

API.

Purpose:

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

Calling Context:

Called by momentary controls when the user interacts with the control.

Parameters:

bool pressed -Specifies whether 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: MDelegatingMomentaryControl::GetLabel

virtual const TLabel* GetLabel() const

Interface Category:

API.

Purpose:

Determines if a label is available for use by the control. This is primarily a convenience function for calling GetLabel on this control's state object. State object functions can be called directly by calling the appropriate function on the object returned by GetState.

Calling Context:

Called by momentary controls when the state is adopted into the control and when the control receives state change notifications.

Parameters:

Takes no parameters.

Return Value:

The label is returned by calling GetLabel on control's state object. 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: MDelegatingMomentaryControl::SetControlView

virtual void SetControlView(const TViewHandle& owner)

Interface Category:

API.

Purpose:

Provides the state a handle to the control itself. This is primarily a convenience function for calling SetControlView on this control's state object. State object functions can be called directly by calling the appropriate function on the object returned by GetState.

Calling Context:

Called by momentary controls 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: MDelegatingMomentaryControl::GetControlView

virtual TView* GetControlView()

Interface Category:

API.

Purpose:

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

Calling Context:

Called directly by clients or derived classes.

Parameters:

Takes no parameters.

Return Value:

Returns a pointer to 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: MDelegatingMomentaryControl::SetRequestProcessor

virtual void SetRequestProcessor (TRequestProcessor * proc)

Interface Category:

API.

Purpose:

Sets the request processor, which 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 StateChanged is 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: MDelegatingMomentaryControl::StateChanged

virtual void StateChanged (const TNotification &)

Interface Category:

API.

Purpose:

Notifies this control that its state object has changed state and enables this control to participate in a member function connection to the state object. This function calls HandleStateChanged.

Calling Context:

Called when an object sends a notification containing an interest that the state object returned from AddInterests.

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:

SetRequestProcessor must be called before this function to establish a notification connection.

Member Function: MDelegatingMomentaryControl::HandleStateChanged

virtual void HandleStateChanged ()

Interface Category:

API.

Purpose:

Handles notification that the state object's state has changed. By default, does nothing. Classes deriving from MDelegatingMomentaryControl 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:

This function is protected.

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