Class: TMomentaryControl

Declaration: MomentaryControls.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TSimpleView, MMouseEventHandler, MControl, MDelegatingMomentaryControl

Inherited By:

TCloseBox TPushButton

Purpose:

TMomentaryControl is an abstract base class deriving from TSimpleView, MMouseEventHandler, MControl, and MDelegatingMomentaryControl. TMomentaryControl is the base class for all momentary control views. This class introduces TView protocol for drawing and for positional event distribution; MMouseEventHandler protocol for handling mouse events; and finally, MControl protocol for interacting with the control and for layout of the control. This class also defines functions for getting and setting the size of the control.

Instantiation:

Abstract base class; do not allocate.

Deriving Classes:

Classes deriving from TMomentaryControl must implement the pure virtual function TView::DrawContents.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TMomentaryControl::TMomentaryControl

TMomentaryControl ()
TMomentaryControl (MMomentaryControlState * state)
TMomentaryControl (const TMomentaryControl & copy)

Interface Category:

API.

Purpose:

Default constructor.
Creates a new momentary control and adopts the specified state object.
Copy constructor.

Calling Context:

TMomentaryControl is an abstract base class, so all of these are called by constructors in TMomentaryControl derived classes.

Parameters:

Takes no parameters.
MMomentaryControlState * state -The state object to be adopted.
const TMomentaryControl & copy -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: TMomentaryControl::~TMomentaryControl

virtual ~ TMomentaryControl ()

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

TMomentaryControl & operator =(const TMomentaryControl &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

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

Parameters:

const TMomentaryControl & -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: TMomentaryControl::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: TMomentaryControl::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: TMomentaryControl::SetFixedSize

virtual void SetFixedSize (const TGPoint & size)

Interface Category:

API.

Purpose:

Sets this control to a fixed size--when a control is set to a fixed size, it remains at the specified size, regardless of any changes to other parameters like the label and the graphic size. This function calls SetAllocatedArea to establish the fixed size of the control. Use SetAutoResize to undo the affect of SetFixedSize and have the control resize itself to fit its label and graphic label.

Calling Context:

Call this function directly.

Parameters:

const TGPoint & size -The new fixed size for this control.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMomentaryControl::IsFixedSize

virtual bool IsFixedSize () const

Interface Category:

API.

Purpose:

Determines whether a fixed size has been set for this control using SetFixedSize.

Calling Context:

Called by Layout. You can also call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if this control is a fixed size, false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMomentaryControl::SetAutoResize

virtual void SetAutoResize ()

Interface Category:

API.

Purpose:

Resizes this control to the minimum size required to display its label and graphic label. This function calls SetAllocatedArea to set the control to that size. This function is the counterpart to SetFixedSize, which keeps the size of the control fixed to a specified width and height.

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:

None.

Member Function: TMomentaryControl::HandleStateChanged

virtual void HandleStateChanged ()

Interface Category:

API.

Purpose:

Handles notification that the state object's state has changed. Makes sure that the state has this control as its control view. Classes deriving from TMomentaryControl override this function to also update the control with the new state and redraw the control.

Calling Context:

Called from StateChanged, which is called when a notification is received from the state object that the state has changed.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides the inherited MDelegatingMomentaryControl function.

Member Function: TMomentaryControl::CreateInteractor

virtual TInteractor * CreateInteractor (const TGPoint & pt)

Interface Category:

API.

Purpose:

Creates an interactor for interacting on the control. Classes deriving from TMomentaryControl can override this function to return different interactors.

Calling Context:

Called when a mouse-down event is received.

Parameters:

const TGPoint & pt -The location where the mouse-down event occurred.

Return Value:

Returns a TInteractor object or an object that inherits from TInteractor. TMomentaryControl's implementation of this function returns a TMomentaryControlInteractor, which should be adequate for most momentary controls.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides the inherited MControl function.

Member Function: TMomentaryControl::MouseDown

virtual bool MouseDown (TMouseDownEvent & mouseEvent)

Interface Category:

API.

Purpose:

Receives mouse-down events that occur inside the control and starts an interactor on the control (using CreateInteractor). Classes deriving from TMomentaryControl can override this function to implement specific mouse-down handling.

Calling Context:

Called by the Input System framework.

Parameters:

TMouseDownEvent & mouseEvent -The event that caused this function to be called.

Return Value:

Returns true if this control handled the mouse-down event, false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides the inherited MMouseEventHandler function.

Member Function: TMomentaryControl::DrawSelf

virtual void DrawSelf () const

Interface Category:

API.

Purpose:

Redraws this control immediately.

Calling Context:

Called by HandleStateChanged. You can also 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:

None.

Member Function: TMomentaryControl::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 resolves the ambiguity by returning true only if both MDelegatingMomentaryControl::IsEnabled and MControl::IsEnabled return true.

Calling Context:

Called by MouseDown to see if an interaction can take place. You can also call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if this control's state object is enabled, false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides the inherited MDelegatingMomentaryControl and MControl functions.

Member Function: TMomentaryControl::Layout

virtual void Layout () const

Interface Category:

API.

Purpose:

Lays out the inside of this control.

Calling Context:

Called when parameters that affect the layout of the control are changed.

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: TMomentaryControl::IsLayoutValid

virtual bool IsLayoutValid () const

Interface Category:

API.

Purpose:

Determines whether the layout is currently valid.

Calling Context:

Called by functions, such as HandleStateChanged in derived classes, to determine whether the layout is still valid. If not, such functions call Layout to relayout the control.

Parameters:

Takes no parameters.

Return Value:

Returns true if the layout is currently valid, false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is protected.

Member Function: TMomentaryControl::SetLayoutValid

virtual void SetLayoutValid (bool valid =true)

Interface Category:

API.

Purpose:

Specifies whether the current layout is valid.

Calling Context:

Called by Layout functions of derived classes with value true after completing the layout. Called by functions with value false when parameters that affect the layout of the control are changed.

Parameters:

bool valid =true -Set to true to set the current layout as valid, false to set it as invalid.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is protected.

Member Function: TMomentaryControl::HandleBeforeDisconnectionFromViewRoot

virtual void HandleBeforeDisconnectionFromViewRoot ()

Interface Category:

API.

Purpose:

Performs actions required before disconnecting from the view root. Breaks the notification connection with the state, and delegates to TSimpleView.

Calling Context:

Called before disconnecting 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: TMomentaryControl::HandleAfterConnectionToViewRoot

virtual void HandleAfterConnectionToViewRoot ()

Interface Category:

API.

Purpose:

Performs setup actions required after connection to the view root. Delegates to TSimpleView, and establishes a notification connection to the state.

Calling Context:

Called by the View system after the view is connected (directly or indirectly) 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: TMomentaryControl::Animate

virtual void Animate ()

Interface Category:

API.

Purpose:

Simulates a mouse click over the control; calls SetPressed(true), Select, and SetPressed(false).

Calling Context:

Called to invoke the momentary control action programmatically and allow the end user to see the same display changes as occur when the control is invoked interactively. Typical clients include tutorial packages, or dialog windows that invoke the OK button when you press the Enter key.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMomentaryControl::SetControlLayout

virtual void SetControlLayout (MControl :: ELayout layout)

Interface Category:

API.

Purpose:

Sets the layout orientation of this control. It calls Layout to relayout the control, and redraws the control according to the new layout.

Calling Context:

Called directly by clients or derived classes.

Parameters:

ELayout layout -The orientation to set.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides the inherited MControl function.

Member Function: TMomentaryControl::SetVisibility

virtual void SetVisibility (bool visible)

Interface Category:

API.

Purpose:

Sets this control to be visible or invisible. Delegates to TView to draw the control (if it has become visible) or to refresh the previously visible area (if the control has been set to invisible) to make the newly exposed areas appear on the display.

Calling Context:

Called directly by clients or derived classes.

Parameters:

bool visible -The flag indicating whether this control should become visible or invisible--true makes the control visible; false makes it invisible.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides the inherited MControl function.

Member Function: TMomentaryControl::GetBounds

virtual void GetBounds (TGArea & area) const

Interface Category:

API.

Purpose:

Returns an area of the preferred size for the control. The preferred size of a control is the smallest rectangle that contains all of the control's components laid out according to the control's layout orientation.

Calling Context:

Called externally and internally by the View system. Clients or derived classes can call this function directly.

Parameters:

TGArea & area -Receives the area of the preferred size.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides the inherited TView function.

Member Function: TMomentaryControl::GetVisibility

virtual bool GetVisibility () const

Interface Category:

API.

Purpose:

Delegates to TView to determine whether this control is visible.

Calling Context:

Called directly by clients or derived classes.

Parameters:

Takes no parameters.

Return Value:

Returns true if this control is visible, false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides the inherited MControl function.

Member Function: TMomentaryControl::SetPressed

virtual void SetPressed (bool)

Interface Category:

API.

Purpose:

Sets this control as either pressed or unpressed according to the specified Boolean flag, and calls DrawSelf to update the display of this control. Normally, a control becomes pressed when the user clicks over it with the mouse. By default, controls are unpressed.

Calling Context:

Called directly by clients or derived classes.

Parameters:

bool -The flag indicating whether this control should become pressed or unpressed--true presses the control; false unpresses it.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides the inherited MControl function.

Member Function: TMomentaryControl::SetEnabled

virtual void SetEnabled (bool)

Interface Category:

API.

Purpose:

Enables or disables this control according to the specified Boolean flag, and redraws the control to provide visual feedback regarding its new enabled or disabled state. A disabled control is not interactive, while an enabled control functions normally. All controls can be enabled or disabled; by default, controls are enabled.

Calling Context:

Called directly by clients or derived classes.

Parameters:

bool -The flag indicating whether to enable or disable this control--true enables the control; false disables it.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides the inherited MControl function.

Member Function: TMomentaryControl::DistributePositionalEvent

virtual bool DistributePositionalEvent (TEvent & theEvent, const TGPoint & where)

Interface Category:

API.

Purpose:

Same as the TView method.

Calling Context:

Called by the View system to direct positional events to the correct view.

Parameters:

TEvent & theEvent -The event that's being distributed.
const TGPoint & where -The position of the positional event, in coordinates relative to this view.

Return Value:

Returns true if the event was handled by this view or one of its children.

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.