Class: TLineSlider

Declaration: FloatControls.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TSliderControl

Inherited By:

TScrollbarLineSlider

Purpose:

TLineSlider derives from TSliderControl and provides a concrete float control. A TLineSlider consists of a thin rectangular track and an overlapping rectangular thumb. The width of the track, and the dimensions of the thumb can be changed. To specify a horizontal line slider, use the inherited function SetControlLayout to specify kLeftToRight or kRightToLeft. For a vertical line slider, specify kTopToBottom or kBottomToTop.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

None.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TLineSlider::TLineSlider

TLineSlider ()
TLineSlider (MFloatControlState * state)
TLineSlider (const TLineSlider & that)

Interface Category:

API.

Purpose:

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

Calling Context:

Called by the stream-in operators.
Call this function directly.
Called to copy an object.

Parameters:

Takes no parameters.
MFloatControlState * state -The float control state object to be adopted by the newly created line slider.
const TLineSlider & that -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: TLineSlider::~TLineSlider

virtual ~ TLineSlider ()

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

TLineSlider & operator =(const TLineSlider &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

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

Parameters:

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

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

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

TStream & writeTo -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: TLineSlider::operator<<=

virtual TStream & operator <<= (TStream & readFrom)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

TStream & readFrom -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: TLineSlider::GetLabelMargin

virtual GCoordinate GetLabelMargin () const

Interface Category:

API.

Purpose:

Returns the amount of space between the track and the label, also known as the label margin. Clients are guaranteed at least this much space between the track and the control label. However, a larger margin is used to prevent overlapping the display of the ruler and the control label when necessary.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the label margin.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLineSlider::SetLabelMargin

virtual void SetLabelMargin (GCoordinate labelMargin)

Interface Category:

API.

Purpose:

Sets the amount of space between the track and the label, also known as the label margin. Clients are guaranteed at least this much space between the track and the control label. However, a larger margin is used to prevent overlapping the display of the ruler and the control label when necessary.

Calling Context:

Call this function directly.

Parameters:

GCoordinate labelMargin -The new label margin.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLineSlider::GetThumbSize

virtual void GetThumbSize (GCoordinate & thickness, GCoordinate & length) const

Interface Category:

API.

Purpose:

Returns the size of the thumb. Because the thumb can be in a vertical or horizontal track, thickness and length are used instead of width and height. For a vertical track, the thumb thickness is its width and the thumb length is its height. For a horizontal track, the thumb thickness is its height and the thumb length is its width.

Calling Context:

Call this function directly.

Parameters:

GCoordinate & thickness -The thickness of the line slider's thumb as returned by this function.
GCoordinate & length -The length of the line slider's thumb as returned by this function.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLineSlider::GetTrackSize

virtual void GetTrackSize (GCoordinate & thickness, GCoordinate & endSpace) const

Interface Category:

API.

Purpose:

Returns the thickness and end space of the line slider's track. Only the track thickness is configurable, because the track length is determined by the bounds of the control. Track end space is the space that the thumb is not allowed to move into at either end of the track. When the thumb is wider than the track, the default end space usually suffices. When the thumb is the same width as the track (for example, a scroller for a scroll bar control), less end space will most likely be desired.

Calling Context:

Call this function directly.

Parameters:

GCoordinate & thickness -The track thickness as returned by this function.
GCoordinate & endSpace -The end space for the track as returned by this function.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLineSlider::GetTrackTolerance

void GetTrackTolerance (GCoordinate & endPointTolerance, GCoordinate & traversalTolerance) const

Interface Category:

API.

Purpose:

Returns the track tolerance of the line slider. The track tolerances determine how far the user can move the mouse outside the visible bounds of the track before the slider assumes the user is canceling the interaction. The slider's thumb actually jumps back to its initial position once the user moves the mouse beyond the tolerances outside the track. The endpoint tolerance defines how far beyond the endpoints the user can move the mouse before the slider's thumb jumps back to its original position. The traversal tolerance defines how far beyond the sides the user can move the mouse before the slider's thumb jumps back to its original position.

Calling Context:

Call this function directly.

Parameters:

GCoordinate & endPointTolerance -The endpoint tolerance for this line slider's track as returned by this function.
GCoordinate & traversalTolerance -The traversal tolerance for this line slider's track as returned by this function.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLineSlider::SetTrackTolerance

void SetTrackTolerance (GCoordinate endPointTolerance, GCoordinate traversalTolerance)

Interface Category:

API.

Purpose:

Sets the track tolerance of the line slider. The track tolerances determine how far the user can move the mouse outside the visible bounds of the track before the control assumes the user is canceling the interaction. The slider's thumb actually jumps back to initial position once the user moves the mouse beyond the tolerances outside the track. The endpoint tolerance defines how far beyond the endpoints the user can move the mouse before the slider's thumb jumps back to its original position. The traversal tolerance defines how far beyond the sides the user can move the mouse before the slider's thumb jumps back to its original position.

Calling Context:

Call this function directly.

Parameters:

GCoordinate endPointTolerance -The new endpoint tolerance for this line slider's track.
GCoordinate traversalTolerance -The new traversal tolerance for this line slider's track.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLineSlider::GetVisibleTrackBounds

virtual TGRect GetVisibleTrackBounds () const

Interface Category:

API.

Purpose:

Computes and returns the visible bounds of the line slider's track. The normal bounds include margin space for the overlapping thumb and possibly for ruler labels that extend beyond the edge of the track.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the visible track bounds.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLineSlider::Layout

virtual void Layout();
virtual void Layout (const TGRect & actualBounds, TGRect & labelBounds, TGRect & trackBounds, TGRect & rulerBounds)

Interface Category:

API.

Purpose:

Lays out the slider's components according to the slider's current layout direction, label, and other settings. This function also calls SetLayoutValid to validate the layout.

Calling Context:

Called directly by friend classes or classes deriving from TLineSlider.

Parameters:

Takes no parameters.
const TGRect & actualBounds -The bounds for the entire control.
TGRect & labelBounds -The bounds for the slider's label.
TGRect & trackBounds -The bounds for the slider's track.
TGRect & rulerBounds -The bounds for the slider's ruler.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This is a protected member function. The first Layout function (without parameters) overrides the inherited TSliderControl function.

Member Function: TLineSlider::SetThumbBounds

virtual void SetThumbBounds ()

Interface Category:

API.

Purpose:

Adjusts the thumb position based upon the current thumb location and the orientation of the slider track.

Calling Context:

Called directly by friend classes or classes deriving from TSliderControl.

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 TSliderControl function.

Member Function: TLineSlider::HandleStateChanged

virtual void HandleStateChanged ()

Interface Category:

API.

Purpose:

Handles notification that the float control's state has changed. This can be the float value, or the float constraints. This function is also called if other aspects of the slider control are changed and the slider needs to relayout.

Calling Context:

Called directly by friend classes or classes deriving from TSliderControl. Also called from AdoptState, SetState, OrphanState, and StateChanged.

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 TSliderControl function.

Member Function: TLineSlider::DrawContents

virtual void DrawContents (TGrafPort &) const

Interface Category:

API.

Purpose:

Draws the slider to the specified port by drawing each of the slider's components.

Calling Context:

Called directly by friend classes or classes deriving from TLineSlider.

Parameters:

TGrafPort & -The port into which to render the slider.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This is a protected member function.

Member Function: TLineSlider::MoveThumbToFloatValue

virtual void MoveThumbToFloatValue (double)

Interface Category:

API.

Purpose:

Moves the slider's thumb to the specified value.

Calling Context:

Called during mouse interaction on the slider.

Parameters:

double value -The value at which the thumb should be placed.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides the inherited TSliderControl function.

Member Function: TLineSlider::MoveThumbToTrackValue

virtual void MoveThumbToTrackValue (GCoordinate)

Interface Category:

API.

Purpose:

Moves the slider's thumb to the specified location on the track.

Calling Context:

Called during mouse interaction on the slider.

Parameters:

GCoordinate value -The track location to which to move the thumb.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides the inherited TSliderControl function.

Member Function: TLineSlider::MoveThumbToGlobalPoint

virtual GCoordinate MoveThumbToGlobalPoint (const TGPoint &)

Interface Category:

API.

Purpose:

Moves the slider's thumb to the specified global position.

Calling Context:

Called during mouse interaction on the slider.

Parameters:

const TGPoint & point -The global position to which to move the thumb.

Return Value:

Returns the track value where the thumb was actually moved.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides the inherited TSliderControl function.

Member Function: TLineSlider::SetPressed

virtual void SetPressed (bool)

Purpose:

Sets this slider as either pressed or unpressed according to the specified Boolean flag. Normally, a slider becomes pressed when the user clicks over it with the mouse. By default, sliders are unpressed.

Calling Context:

Call this function directly.

Parameters:

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

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides the inherited TSliderControl function.

Member Function: TLineSlider::SetEnabled

virtual void SetEnabled (bool)

Interface Category:

API.

Purpose:

Enables or disables this slider according to the specified Boolean flag. A disabled slider is not interactive, while an enabled control functions normally.

Calling Context:

Call this function directly.

Parameters:

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

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides the inherited TSliderControl function.

Member Function: TLineSlider::HandleBeforeDisconnectionFromViewRoot

virtual void HandleBeforeDisconnectionFromViewRoot ()

Interface Category:

API.

Purpose:

Performs actions required before disconnecting from the view root, including breaking the notification connection with the state.

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 TSliderControl function.

Member Function: TLineSlider::HandleAfterConnectionToViewRoot

virtual void HandleAfterConnectionToViewRoot ()

Interface Category:

API.

Purpose:

Performs setup actions required after connection to the view root, including establishing 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 TSliderControl function.

Member Function: TLineSlider::GetThumbBounds

virtual void GetThumbBounds (TGArea & bounds) const

Interface Category:

API.

Purpose:

Gets the thumb bounds.

Calling Context:

Call this function directly.

Parameters:

TGArea & bounds -Receives the thumb bounds.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is protected.

Member Function: TLineSlider::DrawThumb

virtual void DrawThumb (TGrafPort &) const

Interface Category:

API.

Purpose:

Draws the line slider's thumb to the specified port.

Calling Context:

Called directly by friend classes or classes deriving from TLineSlider.

Parameters:

TGrafPort & -The port into which to draw the slider's thumb.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is protected.

Member Function: TLineSlider::DrawTrack

virtual void DrawTrack (TGrafPort &) const

Interface Category:

API.

Purpose:

Draws the line slider's track to the specified port.

Calling Context:

Called directly by friend classes or classes deriving from TLineSlider.

Parameters:

TGrafPort & port -The port into which to draw the slider's track.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is protected.

Member Function: TLineSlider::DrawLabel

virtual void DrawLabel (TGrafPort &) const

Interface Category:

API.

Purpose:

Draws the line slider's label to the specified port.

Calling Context:

Called directly by friend classes or classes deriving from TLineSlider.

Parameters:

TGrafPort & -The port into which to draw the slider's label.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is protected.

Member Function: TLineSlider::NeedsClipping

virtual bool NeedsClipping ()

Interface Category:

API.

Purpose:

Tells whether this line slider control needs to have its drawing port clipped for the DrawContents to fit within the allocated area.

Calling Context:

Called by the framework during a View system refresh to determine whether a TLinkedClipPort needs to be created before calling the TLineSlider's DrawContents to ensure that all drawing that happens in the TLineSlider's DrawContents is clipped to the TLineSlider's current allocated area.

Parameters:

Takes no parameters.

Return Value:

True if it needs clipping, false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides the inherited TView function.

Member Function: TLineSlider::OrphanRuler

virtual TSliderRuler * OrphanRuler ()

Interface Category:

API.

Purpose:

Removes this control's reference to the currently adopted ruler object so that it's no longer owned by the TLineSlider. This function does not delete the orphaned ruler object.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

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

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLineSlider::GetRuler

virtual const TSliderRuler * GetRuler () const

Interface Category:

API.

Purpose:

Gets the ruler that was adopted by this control.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

A pointer to the ruler.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLineSlider::AdoptRuler

virtual void AdoptRuler (TSliderRuler * ruler)

Interface Category:

API.

Purpose:

Adopts the specified ruler object. This class can only contain a single ruler object at a time, so the new ruler object replaces any ruler object previously adopted in AdoptRuler, and this function deletes the previously adopted ruler.

Calling Context:

Call this function directly.

Parameters:

TSliderRuler * ruler -The ruler to be adopted.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLineSlider::SetTrackSize

virtual void SetTrackSize (GCoordinate thickness, GCoordinate endSpace)

Interface Category:

API.

Purpose:

Sets the thickness and end space of the line slider's track. Only the track thickness is configurable, because the track length is determined by the bounds of the control. Track end space is the space that the thumb is not allowed to move into at either end of the track.

Calling Context:

Call this function directly.

Parameters:

GCoordinate thickness -The new thickness for this line slider's track.
GCoordinate endSpace -The new end space for this line slider's track.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLineSlider::SetThumbSize

virtual void SetThumbSize (GCoordinate thickness, GCoordinate length)

Interface Category:

API.

Purpose:

Sets the size of the thumb. Because the thumb can be in a vertical or horizontal track, thickness and length are used instead of width and height. For a vertical track, the thumb thickness is its width and the thumb length is its height. For a horizontal track, the thumb thickness is its height and the thumb length is its width.

Calling Context:

Call this function directly.

Parameters:

GCoordinate thickness -The new thickness for the line slider's thumb.
GCoordinate length -The new length for the line slider's thumb.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLineSlider::SetControlLayout

virtual void SetControlLayout (ELayout layout)

Interface Category:

API.

Purpose:

Sets the layout orientation of this line slider control. The control layout determines the horizontal or vertical orientation of the slider, and how the components of the slider are laid out with respect to each other. A kLeftToRight or kRightToLeft layout indicates that the track is horizontal and the ruler (if any) is also horizontal. (The ruler layout determines the layout of the ruler relative to the slider track.) The difference is that in a kLeftToRight layout, the label appears to the left of the track, while the order is reversed in a kRightToLeft layout. A kTopToBottom or kBottomToTop layout indicates that the track is vertical and the ruler (if any) is also vertical. (The ruler layout determines the layout of the ruler relative to the slider track.) The difference is that in a kTopToBottom layout, the label appears above the track, while the order is reversed in a kBottomToTop layout.

Calling Context:

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:

Overrides the inherited TSliderControl function.

Member Function: TLineSlider::CreateInteractor

virtual TInteractor * CreateInteractor (const TGPoint &)

Interface Category:

API.

Purpose:

Creates an interactor for the slider.

Calling Context:

Called from MouseDown.

Parameters:

const TGPoint & -The point at which the mouse button was clicked.

Return Value:

Returns the newly created TSliderControlInteractor.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides the inherited MControl function.

Member Function: TLineSlider::MouseDown

virtual bool MouseDown (TMouseDownEvent &)

Interface Category:

API.

Purpose:

Receives the mouse-down events that occur inside the slider and starts an interactor on the slider (using CreateInteractor).

Calling Context:

Called by the Input System framework.

Parameters:

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

Return Value:

Returns true if this slider 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: TLineSlider::GetFloatValue

virtual double GetFloatValue () const

Interface Category:

API.

Purpose:

Returns the current value of this slider.

Calling Context:

Called by the interactor. You can also call this directly.

Parameters:

Takes no parameters.

Return Value:

The current value of this slider.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides the inherited MDelegatingFloatControl function.

Member Function: TLineSlider::GetPreferredSize

virtual TGPoint GetPreferredSize (GCoordinate maximumMainDimension =kInfinity) const

Interface Category:

API.

Purpose:

Returns the preferred size of this 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. 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:

Call this function directly.

Parameters:

GCoordinate maximumMainDimension =kInfinity -The layout constraint.

Return Value:

Returns a TGPoint that 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:

Overrides the inherited MControl function.

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