Class: MDropDownListControlState

Declaration: DropDownTextControl.h

Taxonomy Categories:

Member Functions:

MDropDownListControlState
~MDropDownListControlState
operator=
operator>>=
operator<<=
GetItemFromIndex
GetIndexFromItem
GetSelectedIndex
GetItemCount
GetItemsMaximumSize
CanChangeList
AdoptList
OrphanList
CreateIterator
IsEnabled
CreateInterests
HandleReturnKeyEvent

Interface Category:

API.

Inherits From:

MCollectible

Inherited By:

TStandardDropDownListControlState

Purpose:

The MDropDownListControlState is an abstract class for classes such as TStandardDropDownTextControlState classes. MDropDownListControlState derives from MCollectible, and provides virtual functions for handling internal lists for the classes that are derived from it. As virtual functions, they must be filled in by the derived classes.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

Derive to create TStandardDropDownListControlState for using a TSequenceOf<TText> as internal list.

Concurrency:

Multithread safe.

Resource Use:

No special requirements.

Other Considerations:

None.

Member Function: MDropDownListControlState::MDropDownListControlState

MDropDownListControlState ()
MDropDownListControlState (const MDropDownListControlState &)

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 MDropDownListControlState & -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: MDropDownListControlState::~MDropDownListControlState

virtual ~ MDropDownListControlState ()

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

MDropDownListControlState & operator =(const MDropDownListControlState &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const MDropDownListControlState & -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: MDropDownListControlState::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 is streamed 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: MDropDownListControlState::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 is streamed 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: MDropDownListControlState::GetItemFromIndex

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

Interface Category:

API.

Purpose:

Gets an item by its index value.

Calling Context:

Called by derived classes.

Parameters:

unsigned long index -The index value to the item.
TText & textToFill -The text of the item, filled in by the function.

Return Value:

Returns true if the item was found successfully; otherwise, returns false.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

As this is a pure virtual function, it must be defined by the derived classes.

Member Function: MDropDownListControlState::GetIndexFromItem

virtual unsigned long GetIndexFromItem (const TText & item) const

Interface Category:

API.

Purpose:

Gets the index value for a given item.

Calling Context:

Called by derived classes.

Parameters:

const TText & item -The text of the item for which the index value is desired.

Return Value:

Returns the index value.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

As this is a pure virtual function, it must be defined by the derived classes.

Member Function: MDropDownListControlState::GetSelectedIndex

virtual unsigned long GetSelectedIndex () const

Interface Category:

API.

Purpose:

Gets the selected list item's index value.

Calling Context:

Called by derived classes.

Parameters:

Takes no parameters.

Return Value:

Returns the index value of the selected list item.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

As this is a pure virtual function, it must be defined by the derived classes.

Member Function: MDropDownListControlState::GetItemCount

virtual unsigned long GetItemCount () const

Interface Category:

API.

Purpose:

Gets the count of the number of items in the list.

Calling Context:

Called by derived classes.

Parameters:

Takes no parameters.

Return Value:

Returns the number of items in the list.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

As this is a pure virtual function, it must be defined by the derived classes.

Member Function: MDropDownListControlState::GetItemsMaximumSize

virtual TGPoint GetItemsMaximumSize () const

Interface Category:

API.

Purpose:

Gets the maximum size--the maximum width and height--of the item in the list.

Calling Context:

Called by derived classes.

Parameters:

Takes no parameters.

Return Value:

Returns the TGPoint object that describes the width and height dimensions for the item.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

As this is a pure virtual function, it must be defined by the derived classes.

Member Function: MDropDownListControlState::CanChangeList

virtual bool CanChangeList () const

Interface Category:

API.

Purpose:

Returns the Boolean value that indicates whether the control state can adopt or orphan a list.

Calling Context:

Called by derived classes.

Parameters:

Takes no parameters.

Return Value:

Returns true if the control state has the ability to adopt and orphan a list; otherwise, returns false.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

Default is true to allow control state the ability to adopt and orphan a list. Derived classes should override this method when different behavior is needed.

Member Function: MDropDownListControlState::AdoptList

virtual void AdoptList (TSequenceOf < TText > * listToAdopt)

Interface Category:

API.

Purpose:

Adopts the referenced list control state and incorporates its items into the drop-down list display. This enables customizing of the object.

Calling Context:

Called by derived classes.

Parameters:

TSequenceOf < TText > * listToAdopt -A reference to the list sequence to adopt.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

As this is a pure virtual function, it must be defined by the derived classes.

Member Function: MDropDownListControlState::OrphanList

virtual TSequenceOf < TText > * OrphanList ()

Interface Category:

API.

Purpose:

Orphans, or frees, the current adopted list sequence.

Calling Context:

Called by derived classes.

Parameters:

Takes no parameters.

Return Value:

Returns a pointer to the just orphaned list sequence.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

As this is a pure virtual function, it must be defined by the derived classes.

Member Function: MDropDownListControlState::CreateIterator

virtual TDropDownTextControlIterator * CreateIterator (const TAllocationHeap & whichHeap) const

Interface Category:

API.

Purpose:

Creates an iterator, which gives the creator the ability to iterate through a list of items.

Calling Context:

Called by derived classes.

Parameters:

const TAllocationHeap & whichHeap -A reference to the heap on which the list has been allocated.

Return Value:

Returns a pointer to the TDropDownTextControlIterator iterator.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

As this is a pure virtual function, it must be defined by the derived classes.

Member Function: MDropDownListControlState::IsEnabled

virtual bool IsEnabled () const

Interface Category:

API.

Purpose:

Returns a Boolean value that indicates whether the control is enabled. Note that the control can present a different look when it is enabled from when it is not enabled.

Calling Context:

Called by derived classes.

Parameters:

Takes no parameters.

Return Value:

Returns true if the control is enabled, which is the default; otherwise, returns false.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: MDropDownListControlState::CreateInterests

virtual void CreateInterests (TCollectionOf < TInterest > & collection) const

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 StateChanged function.

Calling Context:

Called by derived classes.

Parameters:

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

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

Derived classes should define this function to provide notification connection.

Member Function: MDropDownListControlState::HandleReturnKeyEvent

virtual bool HandleReturnKeyEvent ()

Interface Category:

API.

Purpose:

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

Calling Context:

Called by derived classes.

Parameters:

Takes no parameters.

Return Value:

Returns true if the Enter or Return key was pressed by the user and the action was handled.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

Derived classes should define this function to handle return key input if necessary.

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