Class: MSpinFieldState

Declaration: SpinListControl.h

Taxonomy Categories:

Member Functions:

MSpinFieldState
~MSpinFieldState
operator=
operator>>=
operator<<=
SetReadOnly
IsReadOnly
IsEnabled
IsBoundedSpin
CanChangeList
GetCount
AdoptList
OrphanList
CreateIterator
GetItemFromIndex
GetIndexFromItem
Previous
Next
GetSpinIndex
CreateInterests
HandleReturnKeyEvent

Interface Category:

API.

Inherits From:

MSpinnable, MReferenceCounted, MCollectible

Inherited By:

TStandardSpinFieldState

Purpose:

The MSpinFieldState is the base class for all spin field states. It provides pure virtual functions, or protocols, for the derived classes. These protocols set up the basic spin field state control template.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

Currently, class TStandardSpinFieldState is derived from this class. Derive from this class if one wants to customize the behavior on a TSpinField which is not supported via TStandardSpinFieldState.

Concurrency:

Multithread safe.

Resource Use:

No special requirements.

Other Considerations:

None.

Member Function: MSpinFieldState::MSpinFieldState

MSpinFieldState ()
MSpinFieldState (const MSpinFieldState & copy)

Interface Category:

API.

Purpose:

Default constructor.
Copy constructor.

Calling Context:

Called by the stream-in operators and derived classes.
Called to copy an object.

Parameters:

Takes no parameters.
const MSpinFieldState & copy -The object that is be to copied.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: MSpinFieldState::~MSpinFieldState

virtual ~ MSpinFieldState ()

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

MSpinFieldState & operator =(const MSpinFieldState & state)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

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

virtual void SetReadOnly (bool isReadOnly)

Interface Category:

API.

Purpose:

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

Calling Context:

This virtual function serves as a template for the corresponding function defined in the derived class.

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: MSpinFieldState::IsReadOnly

virtual bool IsReadOnly () const

Interface Category:

API.

Purpose:

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

Calling Context:

This virtual function serves as a template for the corresponding function defined in the derived class.

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: MSpinFieldState::IsEnabled

virtual bool IsEnabled () const

Interface Category:

API.

Purpose:

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

Calling Context:

This virtual function serves as a template for the corresponding function defined in the derived class.

Parameters:

Takes no parameters.

Return Value:

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

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: MSpinFieldState::IsBoundedSpin

virtual bool IsBoundedSpin () const

Interface Category:

API.

Purpose:

Returns a Boolean value that indicates whether the spin operation is occurring on a bounded list value. The spin operation, when not on a bounded list, can be spinning on a value that has an indefinite bound. This means that the spin value is calculated on the fly. By default, the spin is operating on a bounded list that was adopted into the field.

Calling Context:

This virtual function serves as a template for the corresponding function defined in the derived class.

Parameters:

Takes no parameters.

Return Value:

Returns true when the spin operation is occurring on a bounded list value, which is the default condition. Returns false if the spin is occurring on a value that has an indefinite bound.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

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

This virtual function serves as a template for the corresponding function defined in the derived class. Call the derived function directly before calling the AdoptList and OrphanList functions to verify that this function allows those operations.

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: MSpinFieldState::GetCount

virtual 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:

This virtual function serves as a template for the corresponding function defined in the derived class.

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: MSpinFieldState::AdoptList

virtual void AdoptList (TSequenceOf < TText > * listToAdopt)

Interface Category:

API.

Purpose:

Uses the referenced list as the list to spin in the spin field. This is a pure virtual protocol and expects the derived class to specify its specific needs.

Calling Context:

Call the derived class version of this function after calling CanChangeList to verify that the adopt operation is allowed.

Parameters:

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

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: MSpinFieldState::OrphanList

virtual TSequenceOf < TText > * OrphanList ()

Interface Category:

API.

Purpose:

Releases a previously adopted list of text items. This is a pure virtual protocol and expects the derived class to provide its specific needs.

Calling Context:

Call the derived class version of this function after calling CanChangeList to verify that the orphan operation is allowed.

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: MSpinFieldState::CreateIterator

virtual TSpinListIterator * CreateIterator (const TAllocationHeap &) const

Interface Category:

API.

Purpose:

Creates an iterator for accessing the text entries in the spin field. You can use this iterator to iterate through the list.

Calling Context:

This is the virtual function definition and should not be called 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:

None.

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

This virtual function serves as a template for the corresponding function defined in the derived class.

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: MSpinFieldState::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:

This virtual function serves as a template for the corresponding function defined in the derived class.

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 matching found, it returns TSpinField::kInvalidIndex.

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

This virtual function serves as a template for the corresponding function defined in the derived class.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

It's up to the caller to decide what the previous value should be when this call was called.

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

This virtual function serves as a template for the corresponding function defined in the derived class.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

It's up to the caller to decide what the previous value should be when this call was called.

Member Function: MSpinFieldState::GetSpinIndex

virtual unsigned long GetSpinIndex () const

Interface Category:

API.

Purpose:

Gets the text that is to be displayed on the text control.

Calling Context:

This virtual function serves as a template for the corresponding function defined in the derived class.

Parameters:

Takes no parameters.

Return Value:

Returns the index position of the text value that is to be displayed on the text control.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

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

This virtual function serves as a template for the corresponding function defined in the derived class.

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

virtual void HandleReturnKeyEvent ()

Interface Category:

API.

Purpose:

Processes the user's input of the Enter and Return keys.

Calling Context:

This virtual function serves as a template for the corresponding function defined in the derived class.

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.