Class: TSpinListControl

Declaration: SpinListControl.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TSpinControllerView, MMouseEventHandler, MControl

Inherited By:

None.

Purpose:

The TSpinListControl class is a concrete class derived from an internal class named TSpinControllerView. Its purpose is to adopt any number of editable text-based spinnable fields (for example, TSpinFields) for spinning. Thus, it spins on editable text fields.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

This is a concrete class. No one should derive from this class.

Concurrency:

Multithread safe.

Resource Use:

No special requirements.

Other Considerations:

None.

Member Function: TSpinListControl::TSpinListControl

TSpinListControl ()
TSpinListControl (const TSpinListControl &)

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 TSpinListControl & -A reference to the object to be copied.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinListControl::~TSpinListControl

virtual ~ TSpinListControl ()

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:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinListControl::operator=

TSpinListControl & operator =(const TSpinListControl &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TSpinListControl & -The object to be assigned to this object.

Return Value:

A non-const reference to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinListControl::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:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinListControl::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:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinListControl::GetValueAtField

virtual void GetValueAtField (TText & retText, unsigned long index) const

Interface Category:

API.

Purpose:

Gets the text value of the spin field at the position referenced by the current index.

Calling Context:

Call this function directly.

Parameters:

TText & retText -The value of the text field that is referenced by the index; this is filled in by the function.
unsigned long index -The index value that references the position of the text field to be retrieved.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinListControl::GetFieldCount

virtual unsigned long GetFieldCount () const

Interface Category:

API.

Purpose:

Gets the number of text fields or items in the spin control list.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a value that indicates the number of entries in the spin control list.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinListControl::Next

virtual void Next ()

Interface Category:

API.

Purpose:

Gets the next spin control list item when the bottom button of the rocker button is pressed.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinListControl::Previous

virtual void Previous ()

Interface Category:

API.

Purpose:

Gets the previous spin control list item when the top button of the rocker button is pressed.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinListControl::AdoptField

virtual void AdoptField (TSpinField *)

Interface Category:

API.

Purpose:

Adds the referenced TSpinField text field to the spin control so that this field shows up on the display. Spin fields are indexed within the spin control state by the order in which they are added or adopted, starting from position zero through position n minus one.

Calling Context:

Call this function directly.

Parameters:

TSpinField * -A pointer to the TSpinField text field to be adopted.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

After adoption, the TSpinListControl has total control of this adopted field.

Member Function: TSpinListControl::OrphanFieldAt

virtual TSpinField * OrphanFieldAt (const unsigned long & index)

Interface Category:

API.

Purpose:

Removes from the spin control the text field that is at the specified index position.

Calling Context:

Call this function directly.

Parameters:

const unsigned long & index -A reference to the index position of the text field that is to be removed.

Return Value:

Returns a pointer to the TSpinField text field that has been removed.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

After being orphaned, the caller has the control of this spin field.

Member Function: TSpinListControl::InsertFieldAt

virtual void InsertFieldAt (const unsigned long & posTobeInserted, TSpinField * fieldTobeAdopted)

Interface Category:

API.

Purpose:

Adds the referenced TSpinField text field to the spin control at the specified index position so that this field shows up on the display at the specified posTobeInserted index position.

Calling Context:

Call this function directly.

Parameters:

const unsigned long & posTobeInserted -The index position within the spin control at which the text field is to be inserted.
TSpinField * fieldTobeAdopted -The TSpinField text field that is to be added to the spin control.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

However, if the posTobeInserted index is greater than the range of the current number of fields, the new fieldTobeAdopted is added at the end of these fields. The TSpinListControl has total control of this fieldTobeAdopted after insertion.

Member Function: TSpinListControl::GetFieldAt

virtual TSpinField * GetFieldAt (const unsigned long &) const

Interface Category:

API.

Purpose:

Gets the text field that is at the specified index position within the spin control.

Calling Context:

Call this function directly.

Parameters:

const unsigned long & -A reference to the index position of the text field within the spin control list.

Return Value:

Returns a pointer to the TSpinField text field.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinListControl::SetControlLayout

virtual void SetControlLayout (MControl :: ELayout layout)

Interface Category:

API.

Purpose:

Sets the spin control layout orientation. The layout orientation default is LeftToRight. This function overrides the MControl layout.

Calling Context:

Call this function directly.

Parameters:

MControl :: ELayout layout -The ELayout enum value that specifies the layout orientation.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinListControl::GetControlLayout

virtual MControl :: ELayout GetControlLayout () const

Interface Category:

API.

Purpose:

Gets the currently set layout orientation for the spin control.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the ELayout enum value that specifies the current layout orientation for the spin control.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinListControl::AdoptBorder

virtual void AdoptBorder (TBorder * border)

Interface Category:

API.

Purpose:

Sets up a box border object for the field group of the spin control display. Providing a border is optional; the display is drawn with a default TRecessedBackground boarder if none is specified.

Calling Context:

Call this function directly.

Parameters:

TBorder * border -A pointer to the border object that describes the thickness of the border to draw around the spin box.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinListControl::OrphanBorder

virtual TBorder * OrphanBorder ()

Interface Category:

API.

Purpose:

Removes or releases a previously set border for the spin box. Once the TBorder border object is released, the spin box is drawn without a border.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a pointer to the newly removed TBorder border object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinListControl::GetBorder

virtual TBorder * GetBorder () const

Interface Category:

API.

Purpose:

Returns the current border object that has been set up for this spin control box.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a pointer to the current TBorder border object, or NIL if no border object is set for this spin control box.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinListControl::SetEnabled

virtual void SetEnabled (bool isEnabled)

Interface Category:

API.

Purpose:

Sets up all the fields in the spin list control to be either enabled or disabled, depending on the value of the Boolean isEnabled. When isEnabled is set to true, all fields in the control are enabled. By default, all fields are enabled in the TSpinListControl.

Calling Context:

Call this function directly.

Parameters:

bool isEnabled -A Boolean value that indicates whether all the fields in the spin control are enabled or disabled. When true, all fields are set to enabled; when false, all fields are set to disabled.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinListControl::IsEnabled

virtual bool IsEnabled () const

Interface Category:

API.

Purpose:

Returns the current value of the IsEnabled Boolean. This Boolean controls whether all the fields in the spin control are enabled or disabled.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if all the fields in the spin control are enabled; otherwise, returns false.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinListControl::GetPreferredSize

virtual TGPoint GetPreferredSize (GCoordinate maximumMainDimension =kInfinity) const

Interface Category:

API.

Purpose:

Returns the preferred size of this TSpinView spin control view. The preferred size is based on the best fit bounds of the adopted spin fields and the bounds of the spin button.

Calling Context:

Call this function directly.

Parameters:

GCoordinate maximumMainDimension =kInfinity -A global view coordinate that specifies the maximum width; this defaults to the value of kInfinity if not set. If the caller has a restricted width for this control to be in, then the caller can set this maximumMainDimension to a preferred width. This member function will then only calculate the best fit height for this control. Otherwise, the caller can leave this field unset and let this member function decide what is the best fit size for this field for both width and height.

Return Value:

Returns the TGPoint object that describes the preferred size of the spin control view.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

It is recommended to call this member function if the caller wants to get the best fit TSpinListControl in order for all its fields to show up visibly.

Member Function: TSpinListControl::GetBounds

virtual void GetBounds (TGArea & area) const

Interface Category:

API.

Purpose:

Gets the area bounds for the spin control view. This area should be the same size as that returned from GetPreferredSize.

Calling Context:

Call this function directly.

Parameters:

TGArea & area -A reference to the TGArea object that contains the area bounds for the spin control view; this is filled in by the function.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinListControl::SetFieldGap

void SetFieldGap (GCoordinate fieldGap)

Interface Category:

API.

Purpose:

Sets the display gap between the fields in the spin control view. By default, the gap is zero.

Calling Context:

Call this function directly.

Parameters:

GCoordinate fieldGap -A global coordinate value that specifies the gap between the spin control fields for the display.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinListControl::GetFieldGap

GCoordinate GetFieldGap () const

Interface Category:

API.

Purpose:

Gets the currently set display gap between the spin control fields.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the GCoordinate object that specifies the gap between the spin control fields.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinListControl::GetFocusField

unsigned long GetFocusField ()

Interface Category:

API.

Purpose:

Gets the currently set focus field. This is the text field that is focused on when the spin control starts to spin.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the index position of the focus field.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinListControl::SetFocusField

void SetFocusField (unsigned long fieldPos)

Interface Category:

API.

Purpose:

Sets the display focus of the spin control to the specified field, according to the index position.

Calling Context:

Call this function directly.

Parameters:

unsigned long fieldPos -The index position of the text field to focus on in the spin control display.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinListControl::HandleAllocatedAreaChanged

virtual void HandleAllocatedAreaChanged (const TGArea & newArea)

Interface Category:

API.

Purpose:

Handles notification of a change to the spin control view�s allocated area, so that appropriate changes can be made to its layout.

Calling Context:

This function is called internally.

Parameters:

const TGArea & newArea -A reference to the TGArea object that describes the new allocated area.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinListControl::HandleAfterConnectionToViewRoot

virtual void HandleAfterConnectionToViewRoot ()

Interface Category:

API.

Purpose:

Overrides the associated TView function. It is used for notification of when the spin control view is connected to the view root hierarchy, so that display of the spin control view occurs.

Calling Context:

This function is called internally.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinListControl::HandleBeforeDisconnectionFromViewRoot

virtual void HandleBeforeDisconnectionFromViewRoot ()

Interface Category:

API.

Purpose:

Overrides the associated TView function. It is used for notification of when the spin control view is disconnected to the view root hierarchy.

Calling Context:

This function is called internally.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinListControl::NeedsClipping

virtual bool NeedsClipping ()

Interface Category:

API.

Purpose:

Returns a Boolean value that indicates whether the spin list control screen needs clipping.

Calling Context:

This function is called internally to check if the spin list control will need clipping.

Parameters:

Takes no parameters.

Return Value:

Returns a Boolean value that is set to true if clipping is needed.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinListControl::DrawContents

virtual void DrawContents (TGrafPort & port) const

Interface Category:

API.

Purpose:

Draws the contents of the spin control view to the specified TGrafPort.

Calling Context:

This function is called internally when the spin control view is to be redrawn.

Parameters:

TGrafPort & port -A reference to the graf port for drawing the display.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinListControl::Layout

virtual void Layout ()

Interface Category:

API.

Purpose:

Handles any changes made to the spin control view layout. These are changes to the border, the text fields, and the rocker button.

Calling Context:

This function is called internally.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

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