Class: TSpinField

Declaration: SpinListControl.h

Taxonomy Categories:

Member Functions:


Interface Category:

API.

Inherits From:

TView, MControl

Inherited By:

None.

Purpose:

The TSpinField is the control for spin fields. This class takes an MSpinFieldState. It provides the protocols for handling updating the spin field to the previous or next value. This is the editable text-based spin field that is adopted into the TSpinListControl list of spin fields.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

This is a concrete class. Deriving classes may override any of the virtual member functions in this class to alter the behavior of this control only if absolutely necessary.

Concurrency:

Multithread safe.

Resource Use:

No special requirements.

Other Considerations:

None.

Member Function: TSpinField::TSpinField

  1. TSpinField ()
  2. TSpinField (MSpinFieldState * tobeAdoptedState)
  3. TSpinField (TSequenceOf < TText > * beAdoptedLabelList, unsigned long startSpinPos =0)
  4. TSpinField (const TSpinField & copy)

Interface Category:

API.

Purpose:

  1. Default constructor.
  2. Creates a TSpinField object using the referenced MSpinFieldState object.
  3. Creates a TSpinField object using the list of text and using the startSpinPos to set the initial text value in this field.
  4. Copy constructor.

Calling Context:

  1. Called by the stream-in operators and derived classes.
  2. Called to create the object for a single MSpinFieldState.
  3. Called to create the object from a list of text items.
  4. Called to copy an object.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinField::~TSpinField

virtual ~ TSpinField ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinField::operator=

TSpinField & operator =(const TSpinField &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

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

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

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

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

virtual TStream & operator <<= (TStream &)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

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: TSpinField::SetReadOnly

virtual void SetReadOnly (bool isReadOny)

Interface Category:

API.

Purpose:

Sets the current TSpinField field to be a read-only field. When set as a read-only field, the field cannot have its value changed or focused, nor is spin allowed to happen to this field. By default, the field is created with this value set to false.

Calling Context:

Call this function directly.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinField::IsReadOnly

virtual bool IsReadOnly () const

Interface Category:

API.

Purpose:

Gets the current value of the Boolean that determines if the field is read-only.

Calling Context:

Call this function directly. Called by class TSpinListControl.

Parameters:

Return Value:

Returns true if the field is read-only; otherwise, returns false.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinField::Previous

virtual void Previous ()

Interface Category:

API.

Purpose:

Goes to the previous spin field value in the spin list, as a result of an up-arrow operation.

Calling Context:

Call this function directly. Called by class TSpinListControl.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinField::Next

virtual void Next ()

Interface Category:

API.

Purpose:

Goes to the next spin field value in the spin list, as a result of a down-arrow operation.

Calling Context:

Call this function directly.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinField::GetValue

void GetValue (TText & text) const

Interface Category:

API.

Purpose:

Returns the text value at the current position within the TText object.

Calling Context:

Call this function directly.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinField::SetValue

void SetValue (const TText & textToSet)

Interface Category:

API.

Purpose:

Sets the TText object to the specified text value, thus changing whatever text value might have been in the field.

Calling Context:

Call this function directly.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinField::GetPreferredSize

virtual TGPoint GetPreferredSize (GCoordinate maximumMainDimension =kInfinity) const

Interface Category:

API.

Purpose:

Returns the preferred size of this TSpinField spin field view. The preferred size is based on the bounds of the adopted label of the text field and its bounds. This calculates the optimum size to hold the longest text in the list of text objects to spin. If the maximumMainDimension is set to a certain value, that value is then used to constrain the width of a field. Only the height of the field is calculated in this member function. If the maximumMainDimension is not set, then, this member function determines a best fit size for this field for both width and height.

Calling Context:

Call this function directly.

Parameters:

Return Value:

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

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinField::AdoptSpinState

virtual void AdoptSpinState (MSpinFieldState * tobeAdoptedState)

Interface Category:

API.

Purpose:

Adds the specified spin field state to the spin field object. This sets up the data and protocol for spinning.

Calling Context:

Call this function directly.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinField::GetSpinState

virtual MSpinFieldState * GetSpinState () const

Interface Category:

API.

Purpose:

Gets the current spin state for the spin field. This is the data and protocol for spinning.

Calling Context:

Call this function directly.

Parameters:

Return Value:

Returns a pointer to the current spin field state object for the spin field.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinField::OrphanSpinState

virtual MSpinFieldState * OrphanSpinState ()

Interface Category:

API.

Purpose:

Releases the spin field state data and protocol for the spin field.

Calling Context:

Call this function directly.

Parameters:

Return Value:

Returns a pointer to the spin field state object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinField::AdoptTextState

virtual void AdoptTextState (MTextControlState * stateToAdopt)

Interface Category:

API.

Purpose:

A convenience function for changing the state of the TTextControl object. This function calls the respective TTextControl function to adopt the new text state.

Calling Context:

Call this function directly.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinField::OrphanTextState

virtual MTextControlState * OrphanTextState ()

Interface Category:

API.

Purpose:

A convenience function for changing the state of the TTextControl object. This function calls the respective TTextControl function to release the current text state.

Calling Context:

Call this function directly.

Parameters:

Return Value:

Returns a pointer to the just released text control state.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinField::GetTextState

virtual const MTextControlState * GetTextState () const

Interface Category:

API.

Purpose:

A convenience function for getting the current text control state. This function calls the respective TTextControl function to get the current text state.

Calling Context:

Call this function directly.

Parameters:

Return Value:

Returns a pointer to the current text control state.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

After obtaining the TextState, the caller can query all the information there is about the TText and its current value.

Member Function: TSpinField::AdoptList

virtual void AdoptList (TSequenceOf < TText > * listToAdopt)

Interface Category:

API.

Purpose:

A convenience function for adopting a list of text items into a spin field. This function calls MSpinFieldState::AdoptList to adopt the list. A state is always automatically created if none is adopted.

Calling Context:

Call this function directly.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

This member function will automatically update the preferred size for this field but will not update size for the control visually. One can query this preferred size and try to set the proper size for this control accordingly.

Member Function: TSpinField::OrphanList

virtual TSequenceOf < TText > * OrphanList ()

Interface Category:

API.

Purpose:

A convenience function for releasing a list of text items from a spin field. This function calls MSpinFieldState::OrphanList to release the list.

Calling Context:

Call this function directly.

Parameters:

Return Value:

Returns a pointer to the list of text items that was just orphaned.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinField::CanChangeList

virtual bool CanChangeList ()

Interface Category:

API.

Purpose:

Returns a Boolean value that indicates whether a list can be adopted or orphaned.

Calling Context:

Call this function directly. This should be called prior to calling AdoptList or OrphanList to verify that the operation can be performed.

Parameters:

Return Value:

Returns true if the list can be adopted or orphaned; otherwise, returns false.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinField::CreateIterator

virtual TSpinListIterator * CreateIterator (const TAllocationHeap &) const

Interface Category:

API.

Purpose:

Creates an iterator for accessing the text entries in the spin field. If there is a list contained in the spin field, then you can use this iterator to iterate through the list.

Calling Context:

Call this function directly.

Parameters:

Return Value:

Returns a pointer to the list iterator, if one is created; otherwise, it returns NIL.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

If there is no list in the field, a default empty list is created.

Member Function: TSpinField::SetFocus

virtual void SetFocus (bool focus)

Interface Category:

API.

Purpose:

Sets the current spin field to be the focus in the TSpinListControl.

Calling Context:

Call this function directly. Called by class TSpinListControl.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinField::IsFocus

virtual bool IsFocus () const

Interface Category:

API.

Purpose:

Returns the focus status of the current spin field.

Calling Context:

Call this function directly.

Parameters:

Return Value:

Returns true if the focus status is set for the spin field; otherwise, returns false.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinField::SetEnabled

virtual void SetEnabled (bool enabled)

Interface Category:

API.

Purpose:

Sets up all the current spin fields to be either enabled or disabled, depending on the value of the Boolean enabled. When enabled is set to true, the spin field is enabled. By default, the field is enabled.

Calling Context:

Call this function directly. Called by class TSpinListControl.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinField::IsEnabled

virtual bool IsEnabled () const

Interface Category:

API.

Purpose:

Returns the current value of the IsEnabled Boolean. This Boolean indicates whether the spin field is enabled or disabled.

Calling Context:

Call this function directly. Called by class TSpinListControl.

Parameters:

Return Value:

Returns true if the spin field is enabled; otherwise, returns false.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinField::HandleStateChanged

virtual void HandleStateChanged (const TNotification &)

Interface Category:

API.

Purpose:

Provides notification when the spin field either adopts or orphans a new state.

Calling Context:

Call this function directly. Called by class TSpinListControl.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinField::GetBounds

virtual void GetBounds (TGArea & area) const

Interface Category:

API.

Purpose:

Gets the current allocated area of the spin field display area.

Calling Context:

Call this function directly.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinField::HandleReturnKeyEvent

virtual void HandleReturnKeyEvent ()

Interface Category:

API.

Purpose:

Processes the user keyboard input of the Return key. By default, this function highlights the spin text field when Return key is entered.

Calling Context:

Call this function directly. Currently, it is called by class TSpinFieldKeyFilter.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinField::HandleAllocatedAreaChanged

virtual void HandleAllocatedAreaChanged (const TGArea & newArea)

Interface Category:

API.

Purpose:

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

Calling Context:

This function is called internally.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinField::GetBestFitSize

virtual TGPoint GetBestFitSize () const

Interface Category:

API.

Purpose:

Returns the calculated best size for the spin field to perfectly fit every text item to spin in the field.

Calling Context:

This function is called internally.

Parameters:

Return Value:

Returns the TGPoint object that describes the size of the spin field for the display.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinField::HandleAfterConnectionToViewRoot

virtual void HandleAfterConnectionToViewRoot ()

Interface Category:

API.

Purpose:

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

Calling Context:

This function is called internally.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinField::HandleBeforeDisconnectionFromViewRoot

virtual void HandleBeforeDisconnectionFromViewRoot ()

Interface Category:

API.

Purpose:

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

Calling Context:

This function is called internally.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinField::NeedsClipping

virtual bool NeedsClipping ()

Interface Category:

API.

Purpose:

Returns a Boolean value that indicates whether the spin field display needs clipping.

Calling Context:

This function is called internally to check if the display needs clipping.

Parameters:

Return Value:

Returns true if the spin field needs clipping; otherwise, returns false.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSpinField::DrawContents

virtual void DrawContents (TGrafPort & port) const

Interface Category:

API.

Purpose:

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

Calling Context:

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

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.
Copyright©1995 Taligent,Inc. All rights reserved.