Class: TStandardSpinFieldState

Declaration: SpinListControl.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MSpinFieldState

Inherited By:

None.

Purpose:

The TStandardSpinFieldState is a concrete class derived from MSpinFieldState. It provides a storage placeholder for a list of TText data. It also provides the means to spin this list in the spin field. In addition, it provides protocols for sending notification for state change and for creating interests.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

None.

Concurrency:

Multithread safe.

Resource Use:

No special requirements.

Other Considerations:

None.

Member Function: TStandardSpinFieldState::TStandardSpinFieldState

TStandardSpinFieldState ()
TStandardSpinFieldState (TSequenceOf < TText > * beAdoptedLabelList, unsigned long startSpinPos =0)
TStandardSpinFieldState (const TStandardSpinFieldState & copy)

Interface Category:

API.

Purpose:

Default constructor.
Constructor that creates a TStandardSpinFieldState object using the text item list, and uses the text at the startSpinPos of the list to be the initial text value in the spin field.
Copy constructor.

Calling Context:

Called by the stream-in operators.
Called to create a custom TStandardSpinFieldState object.
Called to copy an object.

Parameters:

Takes no parameters.
TSequenceOf < TText > * beAdoptedLabelList -A pointer to the text label list object to use.
unsigned long startSpinPos =0 -The index value of the starting spin position of the text list; this defaults to zero.
const TStandardSpinFieldState & 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.

Member Function: TStandardSpinFieldState::~TStandardSpinFieldState

virtual ~ TStandardSpinFieldState ()

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

TStandardSpinFieldState & operator =(const TStandardSpinFieldState & state)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TStandardSpinFieldState & state -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: TStandardSpinFieldState::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: TStandardSpinFieldState::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: TStandardSpinFieldState::SetReadOnly

virtual void SetReadOnly (bool isReadOnly)

Interface Category:

API.

Purpose:

Sets the spin field to be a read-only field.

Calling Context:

Call this function directly. Called by class TSpinField.

Parameters:

bool isReadOnly -A Boolean value that indicates whether the field is to be read-only. If set to true, the spin field is made to be read-only.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TStandardSpinFieldState::IsReadOnly

virtual bool IsReadOnly () const

Interface Category:

API.

Purpose:

Returns the Boolean value that indicates whether the spin field is read-only.

Calling Context:

Call this function directly. Called by class TSpinField.

Parameters:

Takes no parameters.

Return Value:

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

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TStandardSpinFieldState::CanChangeList

virtual bool CanChangeList () const

Interface Category:

API.

Purpose:

Returns a Boolean value that indicates whether the function allows adopting and orphaning of a new list. A value of true indicates that the function does allow adopting/orphaning; a value of false indicates that it does not.

Calling Context:

Call this function directly. Called by class TSpinField before adopting or orphaning list from the spin field.

Parameters:

Takes no parameters.

Return Value:

Returns true if the function allows the adopting and orphaning of a new list; otherwise, returns false.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TStandardSpinFieldState::AdoptList

virtual void AdoptList (TSequenceOf < TText > * listToAdopt)

Interface Category:

API.

Purpose:

Uses the referenced list as the list to spin in the spin field. The field now has total control of the list and the items in the list.

Calling Context:

Call this function directly. Called by class TSpinField.

Parameters:

TSequenceOf < TText > * listToAdopt -A pointer to the list of text items that is to be added to the spin field.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

The old list in the field will then be destroyed in this member function. If the caller wishes to keep the old list, the caller has to keep a copy of the list prior to when this member function was called.
This member function will only adopt a new list to the state. The control, which has this state already, will not change its preferred size. These items may be wrapped to fit in the current size of the field if the size of an item is larger than the field.
If a developer wants wants the field to be big enough to accommodate the new list items. It is suggested to call _TSpinField::AdoptList()_ member function to cause the change in the preferred size of the field to take place.

Member Function: TStandardSpinFieldState::OrphanList

TSequenceOf

TText

Interface Category:

API.

Purpose:

Releases a previously adopted list of text items.

Calling Context:

Call this function directly. Called by class TSpinField.

Parameters:

Takes no parameters.

Return Value:

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

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TStandardSpinFieldState::GetCount

unsigned long GetCount () const

Interface Category:

API.

Purpose:

Returns the number of items in the list, if there is a list. If there is no list, then it returns zero.

Calling Context:

Call this function directly. Called by class TSpinField.

Parameters:

Takes no parameters.

Return Value:

Returns the number of items in the list, or zero if there is no list.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TStandardSpinFieldState::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 the developer can use this iterator to iterate through the list.

Calling Context:

Call this function directly. Called by class TSpinField.

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:

None.

Member Function: TStandardSpinFieldState::Previous

virtual void Previous ()

Interface Category:

API.

Purpose:

Positions the list pointer to the previous position in the list. This corresponds to the up arrow.

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: TStandardSpinFieldState::Next

virtual void Next ()

Interface Category:

API.

Purpose:

Positions the list pointer to the next item in the list. This corresponds to the down arrow.

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: TStandardSpinFieldState::HandleReturnKeyEvent

virtual void HandleReturnKeyEvent ()

Interface Category:

API.

Purpose:

Processes the user's input of the Return key. Currently, this member function does nothing.

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: TStandardSpinFieldState::CreateInterests

virtual void CreateInterests (TCollectionOf < TInterest > & collection)

Interface Category:

API.

Purpose:

Establishes a notification connection for changes to the control state. This function is called by the control so that it receives notification of changes. If this function returns one or more interests, then a member function connection is made with the control�s HandleStateChanged function.

Calling Context:

Call this function directly. Called by class TSpinField.

Parameters:

TCollectionOf < TInterest > & collection -The set of interests.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TStandardSpinFieldState::SetValueByLabel

virtual void SetValueByLabel (TText * label)

Interface Category:

API.

Purpose:

Sets the value of the spin text field to the specified text in the list entry. The default is the first text entry in the adopted list. This starts the spin operation and spins to the position where the text value is in the list.

Calling Context:

Call this function directly.

Parameters:

TText * label -A pointer to the text item to set in the spin field.

Return Value:

None.

Exceptions:

Throws an exception when no matching text value is found in the list.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TStandardSpinFieldState::SetValueByPos

virtual void SetValueByPos (unsigned long index)

Interface Category:

API.

Purpose:

Spins the spin field to the index position.

Calling Context:

Call this function directly.

Parameters:

unsigned long index -The index position of the text item in the list.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

When the index value is greater than the number of text entries in the list, this continues to spin forward until the index value resides in the range of these text entries.

Member Function: TStandardSpinFieldState::GetItemFromIndex

virtual bool GetItemFromIndex (const unsigned long index, TText & textToFill) const

Interface Category:

API.

Purpose:

Retrieves the text value from an item in the list, according to the index position of that item.

Calling Context:

Call this function directly.

Parameters:

const unsigned long index -The index position of the item in the list that is to be retrieved.
TText & textToFill -The TText object that is filled with the text value of the selected item.

Return Value:

Returns true if the item was successfully found and its text retrieved; otherwise, returns false.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TStandardSpinFieldState::GetIndexFromItem

virtual unsigned long GetIndexFromItem (const TText & item) const

Interface Category:

API.

Purpose:

Returns the index position of the specified item in the list .

Calling Context:

Call this function directly.

Parameters:

const TText & item -A reference to the TText object that contains the list item.

Return Value:

Returns the index value that indicates the position of the item in the list.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

When no item is matched, this returns TSpinField::kInvalidIndex.

Member Function: TStandardSpinFieldState::GetSpinIndex

virtual unsigned long GetSpinIndex () const

Interface Category:

API.

Purpose:

Gets the start spin index position (for example, the position that the initial spin value is at).

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the start spin index position.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TStandardSpinFieldState::NotifyControlOfChange

virtual void NotifyControlOfChange ()

Interface Category:

API.

Purpose:

Notifies the control of the changes that are acquired by the control.

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.

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