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.
- TSpinField ()
- TSpinField (MSpinFieldState * tobeAdoptedState)
- TSpinField (TSequenceOf < TText > * beAdoptedLabelList, unsigned long startSpinPos =0)
- TSpinField (const TSpinField & copy)
Interface Category:
API.
Purpose:
- Default constructor.
- Creates a TSpinField object using the referenced MSpinFieldState object.
- Creates a TSpinField object using the list of text and using the startSpinPos to set the initial text value in this field.
- Copy constructor.
Calling Context:
- Called by the stream-in operators and derived classes.
- Called to create the object for a single MSpinFieldState.
- Called to create the object from a list of text items.
- Called to copy an object.
Parameters:
- Takes no parameters.
- MSpinFieldState * tobeAdoptedState -A pointer to the MSpinFieldState object.
- TSequenceOf < TText > * beAdoptedLabelList -A pointer to the list of text items that are to become spin fields.
- unsigned long startSpinPos =0 -The starting spin list position of the first item in the label list; this defaults to zero unless otherwise specified.
- const TSpinField & copy -The object that is to be copied.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Multithread safe.
Other Considerations:
None.
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:
- const TSpinField & -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: TSpinField::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: TSpinField::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: 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:
- bool isReadOny -A Boolean value that determines if the field is to be read-only. If set to true, then the field is made read-only.
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:
- TText & text -A reference to the text value that is at the current position; 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: 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:
- const TText & textToSet -The text value that is to be set within the text object.
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:
- GCoordinate maximumMainDimension =kInfinity -A global view coordinate that specifies the maximum dimensions; this defaults to the value of kInfinity if not set.
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:
- MSpinFieldState * tobeAdoptedState -A pointer to the spin field state that is to be added.
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:
- TSequenceOf < TText > * listToAdopt -A pointer to the list of text items that is to be adopted.
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:
- const TAllocationHeap & -A reference to the memory location where the list is located.
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:
- bool focus -The Boolean value that indicates whether focus is set for this field.
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:
- bool enabled -A Boolean value that indicates whether the spin field is enabled or disabled. When true, the spin field is set to enabled; when false, it is set to disabled.
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:
- TGArea & area -A reference to the TGArea object that is filled & returned with the current display bounds.
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:
- 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: 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:
- 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.
Click the icon to mail questions or corrections about this material to Taligent personnel.
Copyright©1995 Taligent,Inc. All rights reserved.