Class: MFloatControlState

Declaration: FloatControls.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MCollectible

Inherited By:

TFloatActionState

Purpose:

MFloatControlState is an abstract base class that has floating-point state and is acted upon by a floating-point control object such as a slider. Float control state objects potentially act on another object known as its client object or its target object. In other words, float control states are functors that translate float control protocol into the protocol of some target object. The float control state's value can be constrained to a specific range of values and can be further constrained to discrete intervals within the specified range. Unlike other controls such as TBooleanControl, MFloatControlState has no TFloatControl companion class. This is because floating-point controls can have different feels in addition to a different look; for example, either a slider or a pair of arrows can control a floating-point value. The slider has its own TSliderControl and TSliderControlInteractor, and the arrows have their own control and interactor classes. With the support for adopted control states, the slider and the arrows that comprise a typical scroll bar can share the same state information.

Instantiation:

Abstract base class; do not allocate.

Deriving Classes:

This class must be derived from to be used in a float control. Classes deriving from MFloatControlState must override GetFloatValue, SetFloatValue, and GetFloatConstraints. Derived classes should also override IsEnabled and AddInterests.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: MFloatControlState::MFloatControlState

MFloatControlState ()
MFloatControlState (const MFloatControlState & state)

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 MFloatControlState & state -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: MFloatControlState::~MFloatControlState

virtual ~ MFloatControlState ()

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

MFloatControlState & operator =(const MFloatControlState & state)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

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

Parameters:

const MFloatControlState & state -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: MFloatControlState::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: MFloatControlState::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: MFloatControlState::StartInteraction

virtual void StartInteraction ()

Interface Category:

API.

Purpose:

Called when the user begins an interaction with the floating-point control associated with this float control state--usually by clicking the mouse down on the control. MFloatControlState's implementation of this function does nothing.

Calling Context:

Called by the event handling functions in the interactors associated with floating-point control objects.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MFloatControlState::EndInteraction

virtual void EndInteraction (bool cancelled)

Interface Category:

API.

Purpose:

Called when the interaction started with StartInteraction ends--usually by releasing the mouse button over the control associated with this float control state. The Boolean flag indicates whether the interaction was cancelled by the user. MFloatControlState's implementation of this function does nothing.

Calling Context:

Called by the event handling functions in the interactors associated with floating-point control objects.

Parameters:

bool cancelled -The flag indicating whether the interaction was canceled by the user.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MFloatControlState::GetLabel

virtual const TLabel* GetLabel() const

Interface Category:

API.

Purpose:

Determines if a label is available for use by the control. The default behavior is to return NIL.

Calling Context:

Called by float 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 returned from this member function overrides any label that has been adopted into the control directly.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MFloatControlState::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 float 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: MFloatControlState::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.

Member Function: MFloatControlState::AddInterests

virtual void AddInterests (TSetOf < TInterest > & set)

Interface Category:

API.

Purpose:

Returns one or more TInterests in the given set so that the owning control can establish a notification connection for notification of changes in the state. When the control receives such a notification, it calls IsEnabled and GetFloatValue and updates the presentation accordingly. MFloatControlState's implementation of this function provides an empty set of TInterests, indicating that no notifications are generated by this state.

Calling Context:

Called by the float 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 float 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: MFloatControlState::IsEnabled

virtual bool IsEnabled () const

Interface Category:

API.

Purpose:

Determines whether the owning control is allowed to make changes to the state as a result of user input. A return value of true indicates that state changes are allowed (the float control owning this state object can call SetFloatValue). A return value of false indicates that the target object is disabled and can not accept state changes (the control owning this state object can not call SetFloatValue). Typically, controls present a different look to the user when disabled. MFloatControlState's implementation of this function returns true. Classes deriving from MFloatControlState can implement this function if it is not always valid to call SetFloatValue.

Calling Context:

Called by float controls during initialization or when a notification is received from this state object.

Parameters:

Takes no parameters.

Return Value:

Returns true if the target object is enabled and SetFloatValue can be called, false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MFloatControlState::ConstrainValue

virtual double ConstrainValue (double value)

Interface Category:

API.

Purpose:

Applies this float control state's current constraining rules to the specified value. First, this function calls GetFloatConstraints to determine the current constraints. Then, this function calls PinValueToBounds to constrain the specified value to the minimum and maximum values. Finally, this function applies the interval constraint to the result of PinValueToBounds.

Calling Context:

Called directly by friend classes or classes deriving from MFloatControlState.

Parameters:

double value -The value to be constrained.

Return Value:

Returns the constrained number.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MFloatControlState::PinValueToBounds

static double PinValueToBounds (double value, double lowerBound, double uppperBound)

Interface Category:

API.

Purpose:

Returns the specified value if it falls within the specified lower and upper bounds. Otherwise this function returns the bound that is closest to the value.

Calling Context:

Called from ConstrainValue. You can also call this function directly.

Parameters:

double value -The value to pin to the specified bounds.
double lowerBound -The lower bound to which to pin the specified value.
double uppperBound -The upper bound to which to pin the specified value.

Return Value:

Returns the specified value if the value falls within the specified lower and upper bounds. Otherwise this function returns the bound that is closest to the value.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function must be declared inline before it is called.

Member Function: MFloatControlState::GetFloatConstraints

virtual void GetFloatConstraints (double & minimum, double & maximum, double & intervalSize) const

Interface Category:

API.

Purpose:

Gets the constraints currently applied to this float control state's value. The first two parameters indicate the range within which this float control state's value must fall. The third parameter indicates the discrete interval by which to constrain this float control state's value. For example, if the interval is 1.0, then the float control state's value is constrained to whole numbers. An interval of 0.0 indicates that there is no interval constraint.

Calling Context:

Called from ConstrainValue. You can also call this function directly.

Parameters:

double & minimum -The minimum value of this float control state.
double & maximum -The maximum value of this float control state.
double & intervalSize -The interval by which to constrain the value of this float control state.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

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

Member Function: MFloatControlState::SetFloatValue

virtual void SetFloatValue (double newValue)

Interface Category:

API.

Purpose:

Sets the value, which is the primary state of this class. Classes deriving from MFloatControlState can override this function to make the appropriate changes to the data represented by the state.

Calling Context:

Call this function directly.

Parameters:

double newValue -The new value for this control state.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

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

Member Function: MFloatControlState::GetFloatValue

virtual double GetFloatValue () const

Interface Category:

API.

Purpose:

Returns the value, which is the primary state of this class.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns this float control state's current value.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

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

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