Class: MMomentaryControlState

Declaration: MomentaryControls.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MCollectible

Inherited By:

TDialogControlStateOn MMomentaryTextCommandState MMomentaryTextPresenterCommandState TCursorToolSelectionState TClipboardCopyControlState TClipboardCutControlState TClipboardPasteControlState TCommandControlState TMomentaryActionControlState

Purpose:

MMomentaryControlState is an abstract base class. Classes deriving from MMomentaryControlState are acted upon by a momentary control when that control is manipulated by the user. Momentary control state objects potentially act on another object known as its client object or its target object. In other words, momentary control states are functors that translate momentary control protocol into the protocol of some target object. Momentary controls adopt an MMomentaryControlState and translate user input into calls to this object. An example of a momentary control is TPushButton. An example of a momentary control state is the close window state used in the window close box. This state class translates the momentary protocol into a window close operation.

Instantiation:

Abstract base class; do not allocate.

Deriving Classes:

This class must be derived from to be used in a momentary control.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: MMomentaryControlState::MMomentaryControlState

MMomentaryControlState ()
MMomentaryControlState (const MMomentaryControlState &)

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 MMomentaryControlState & -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: MMomentaryControlState::~MMomentaryControlState

virtual ~ MMomentaryControlState ()

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

MMomentaryControlState & operator =(const MMomentaryControlState &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

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

Parameters:

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

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

Interface Category:

API.

Purpose:

Stream-out operator.

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

virtual void Select ()

Interface Category:

API.

Purpose:

Classes deriving from MMomentaryControlState implement this function to act on some target object. For example, a derived class can close a window or perform the Apply function of a dialog box.

Calling Context:

Called when a momentary control is selected by the user. Selection usually means clicking down on the mouse and releasing the button while the mouse is inside the control. Selection can also occur via the keyboard.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This is a pure virtual function and must be overridden by classes deriving from MMomentaryControlState.

Member Function: MMomentaryControlState::IsEnabled

virtual bool IsEnabled () const

Interface Category:

API.

Purpose:

Determines whether this control's state object is enabled. IsEnabled is defined in MDelegatingMomentaryControl and MControl--both of which are parent classes to TMomentaryControl. This function returns true if both MDelegatingMomentaryControl and MControl return true; otherwise, it returns false.

Calling Context:

Called when the control needs to know whether to allow selections.

Parameters:

Takes no parameters.

Return Value:

Returns true if it is OK to call Select; false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MMomentaryControlState::AddInterests

virtual void AddInterests (TSetOf < TInterest > & set)

Interface Category:

API.

Purpose:

AddInterests establishes a notification connection from this state object to the momentary control that owns it. The notification connection is used to notify the control that the state has changed; outside the user's control, or indirectly as a result of the user manipulating something else. When the control receives such a notification, it calls IsEnabled and updates the presentation accordingly. MMomentaryControlState's implementation of this function provides an empty set of TInterests, indicating that no notification connection is established. Classes deriving from MMomentaryControlState can implement this function and provide one or more TInterest objects if they want to establish a notification connection with the momentary control that owns this state object.

Calling Context:

Called by the momentary control that owns this state object during initialization of the control and after this state object has been adopted into the control.

Parameters:

TSetOf < TInterest > & set -The set of interests for which to establish a notification connection with the momentary control that owns this state object. If this set is empty, no connection is established.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MMomentaryControlState::SetPressed

virtual void SetPressed(bool pressed)

Interface Category:

API.

Purpose:

Notifies the state of changes in the pressed state of the control.

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

virtual const TLabel* GetLabel() const

Interface Category:

API.

Purpose:

Determines if a label is available for use by the control. By default, does nothing and returns NIL. Derived class should override this function and return the label that is going to be used in the control. The momentary control and any derived control classes call this member function to get a label for the control. This member function is used if the developer wants to dynamically change the label at runtime.

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 for the control, if any. The default is NIL.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MMomentaryControlState::SetControlView

virtual void SetControlView(const TViewHandle& owner)

Interface Category:

API.

Purpose:

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

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

virtual TView* GetControlView()

Interface Category:

API.

Purpose:

Queries the view that has been previously set by SetControlView.

Calling Context:

Call this function directly.

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.

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