Class: MControl

Declaration: Controls.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

None.

Inherited By:

TSpinField TDropDownTextControl TSpinListControl TWindow MMenuItem TBooleanControl TBooleanControlGroup TMenu TMomentaryControl TScrollbar TSliderControl TTableView TTextControl

Purpose:

MControl is an abstract base class that defines the protocol required for all controls. A control is an on-screen object that, when manipulated, sends messages to other objects. Specifically, a control's responsibility is to recognize and translate user gestures into the semantics of its clients. MControl provides the protocol for setting and getting three states which are common to all controls: (1) enabled/disabled--a disabled control is not interactive, while an enabled control functions normally; (2) pressed/unpressed--this state is typically used to give visual indications that the user has clicked on the control; and (3) visible/invisible--used to quickly place (remove) a control into (from) view. MControl also defines some primitive layout protocols for supporting the four basic layouts: left to right, right to left, top to bottom and bottom to top. This ensures that all controls can work well in different languages. MControl also defines a method for creating an interactor since all controls by definition are interactive. This class is a mixin so that you can add control features to existing view classes without having to restructure the inheritance hierarchy.

Instantiation:

Abstract base class; do not allocate.

Deriving Classes:

Classes deriving from MControl implement the above protocol as appropriate for specific controls.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: MControl::MControl

MControl ()
MControl (const MControl & copy)

Interface Category:

API.

Purpose:

Default constructor.
Copy constructor. All controls can be copied.

Calling Context:

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

Parameters:

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

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

MControl is an abstract base class--all the constructors are protected. Do not instantiate this class. For controls that derive from TView, the copy constructor is a little tricky to implement since TView does not copy the child views in its copy constructor. In fact, TView cannot blindly copy all the child views because some of those children may have pointers to other children or to the parent control view and aliases cannot be copied. Most controls implement their copy constructors by manually constructing the child views with the appropriate state and manually fixing up any aliased pointers.

Member Function: MControl::~MControl

virtual ~ MControl ()

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

MControl & operator =(const MControl & copy)

Interface Category:

API.

Purpose:

Assignment operator. All controls can be assigned.

Calling Context:

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

Parameters:

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

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

Interface Category:

API.

Purpose:

Stream-out operator. All controls can be streamed out.

Calling Context:

Called to stream out data.

Parameters:

TStream & towhere -The stream to which the object streams itself out.

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

virtual TStream & operator <<= (TStream &)

Interface Category:

API.

Purpose:

Stream-in operator. All controls can be streamed in.

Calling Context:

Called to stream in data.

Parameters:

TStream & fromwhere -The stream from which the object streams itself in.

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: MControl::SetEnabled

virtual void SetEnabled (bool enabled)

Interface Category:

API.

Purpose:

SetEnabled enables or disables this control according to the specified Boolean flag. A disabled control is not interactive, while an enabled control functions normally. All controls can be enabled or disabled; by default, controls are enabled. Typically, classes deriving from MControl will override this function to provide visual feedback when the control becomes enabled or disabled. The standard CommonPoint controls use a pseudo 3-D look for enabled controls and a dimmed 2-D look for disabled controls. They mostly use the TRaisedBackground, TRecessedBackground classes to do this.

Calling Context:

Clients or derived classes can call this function directly.

Parameters:

bool enabled -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:

None.

Member Function: MControl::IsEnabled

virtual bool IsEnabled () const

Interface Category:

API.

Purpose:

Determines whether or not this control is enabled.

Calling Context:

Clients or derived classes can call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if this control is enabled, false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MControl::SetPressed

virtual void SetPressed (bool pressed)

Interface Category:

API.

Purpose:

SetPressed sets this control as either pressed or unpressed according to the specified Boolean flag. Normally, a control becomes pressed when the user clicks over it with the mouse. By default, controls are unpressed. Typically, classes deriving from MControl will override this function to provide visual feedback when the control is pressed or unpressed. For example, a push button may toggle from a raised look to a recessed look.

Calling Context:

Clients or derived classes can call this function directly.

Parameters:

bool pressed -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:

None.

Member Function: MControl::IsPressed

virtual bool IsPressed () const

Interface Category:

API.

Purpose:

Determines whether or not this control is pressed.

Calling Context:

Clients or derived classes can call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if this control is pressed, false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MControl::SetControlLayout

virtual void SetControlLayout (ELayout layout)

Interface Category:

API.

Purpose:

SetControlLayout sets the layout orientation of this control. The control layout determines how the components of this control are laid out with respect to each other. For example, a kRightToLeft check box control draws the check box graphic on the right hand side of its label. By default, controls are laid out kLeftToRight. Classes deriving from MControl should override this function to re-layout and redraw the control according to its new layout.

Calling Context:

Clients or derived classes can call this function directly.

Parameters:

ELayout layout -The orientation to set.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MControl::GetControlLayout

virtual ELayout GetControlLayout () const

Interface Category:

API.

Purpose:

GetControlLayout determines the layout orientation of the control.

Calling Context:

Clients or derived classes can call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the current layout of this control.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MControl::GetPreferredSize

virtual TGPoint GetPreferredSize (GCoordinate maximumMainDimension =kInfinity) const

Interface Category:

API.

Purpose:

GetPreferredSize returns the preferred size of this control. The preferred size of a control is the smallest rectangle which contains all of the control's components laid out according to the control's layout orientation. An optional maximumMainDimension can be provided to constrain the width or height of the control. In a kLeftToRight or kRightToLeft layout the main dimension is the X-dimension, otherwise it is the Y-dimension.

Calling Context:

Clients or derived classes can call this function directly.

Parameters:

GCoordinate maximumMainDimension =kInfinity -The layout constraint.

Return Value:

Returns a TGPoint which contains the preferred size of this control; the X component of the point represents the preferred width, and the Y component of the point represents the preferred height.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Controls that derive from TView, or a TView derived class, should also override the TView::GetBounds member function to return this same preferred size. This will then ensure that your control behaved correctly when used inside the layout views (TLayoutView, TBoxView, etc) since the layout views interpret the TView::GetBounds member function to mean "get preferred minimum bounds."

Member Function: MControl::CreateInteractor

virtual TInteractor * CreateInteractor (const TGPoint & pt)

Interface Category:

API.

Purpose:

CreateInteractor creates an interactor for the control. This is supposed to be an interactor for handling mouse input. The position of the mouse is provided (in local coordinates) so that complex controls can actually return different interactors depending on where the user pressed the mouse. MControl's implementation of this function returns NIL. Classes deriving from MControl should override this function to create the appropriate interactor. Most controls also mixin the MMouseEventHandler class and override MouseDown to call this member function and then call mouseEvent.StartInteraction to start the returned interactor.

Calling Context:

Clients or derived classes can call this function directly.

Parameters:

const TGPoint & pt -The location of a positional event that started the interaction.

Return Value:

Returns the newly created interactor. The caller owns the new interactor and is responsible for destroying it.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Since this member function is public, controls can be combined in more complex interactions where multiple interactors are involved. For example, the rocker button in a scrollbar contains two push buttons. Normally, if a user clicks on a button the button starts the interactor and doesn't allow interaction on another button until the mouse up event arrives. But the rocker buttons wants to allow the user to interact with both buttons in one interaction. To do this the rocker button creates its own interactor that delegates to the interactor for either push button depending on which button the mouse is over. To allow this kind of compound interaction, your interactors should not depend on receiving mouse down.

Member Function: MControl::GetVisibility

virtual bool GetVisibility () const

Interface Category:

API.

Purpose:

Determines whether or not this control is visible.

Calling Context:

Clients or derived classes can call this function directly.

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:

Controls that also derive from a TView class will have to override this member function to delegate to the TView GetVisibility member function in order to resolve the ambiguity.

Member Function: MControl::SetVisibility

virtual void SetVisibility (bool visible)

Interface Category:

API.

Purpose:

Sets this control to be visible or invisible. Typically, classes deriving from MControl will override this function to redraw the control when its visible state changes. By default, controls are visible.

Calling Context:

Clients or derived classes can call this function directly.

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:

Controls that also derive from a TView class will have to override this member function to delegate to the TView SetVisibility member function in order to resolve the ambiguity.

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