Class: MTableControlState

Declaration: ScrollingListControl.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MCollectible

Inherited By:

TLinearListControlState

Purpose:

MTableControlState is a mixin class used to represent the contents of a one or two dimensional array of TTableItem objects. MTableControlState defines the protocol for accessing the items and maintains a list of currently selected items.

Instantiation:

MTableControlState is an abstract class and cannot be instantiated.

Deriving Classes:

Use MTableControlState to derive classes to control your own array of TTableItems.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Other Considerations:

None.

Member Function: MTableControlState::MTableControlState

MTableControlState ()
MTableControlState (const MTableControlState &)

Interface Category:

API.

Purpose:

Default constructor.
Copy constructor.

Calling Context:

Called to create a MTableControlState suitable for streaming into.
Called to copy an object.

Parameters:

Takes no parameters.
const MTableControlState & -The object to be copied.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MTableControlState::~MTableControlState

virtual ~ MTableControlState ()

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:

Not multithread safe.

Other Considerations:

None.

Member Function: MTableControlState::operator=

MTableControlState & operator =(const MTableControlState &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const MTableControlState & -The object to be copied.

Return Value:

A non-const reference to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MTableControlState::operator>>=

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

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

TStream & -The destination stream.

Return Value:

Returns a reference to the stream the object streams itself out to.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MTableControlState::operator<<=

virtual TStream & operator <<= (TStream &)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

TStream & -The source stream.

Return Value:

Returns a reference to the stream the object streams itself in from.

Exceptions:

Throws TInvalidVersionError if the version of the flattened object is not supported.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MTableControlState::SetSelectionType

virtual void SetSelectionType (EListSelectionType type)

Interface Category:

API.

Purpose:

Sets the selection policy for table items. If multiple items are currently selected and the selection policy is being changed to kOneOnly, only the first of the selected items will remain selected.

Calling Context:

Call this function directly to set the manner in which table items may be selected.

Parameters:

EListSelectionType type -The selection type to be allowed.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MTableControlState::GetSelectionType

virtual EListSelectionType GetSelectionType () const

Interface Category:

API.

Purpose:

Returns the current selection policy for table items.

Calling Context:

Call this function directly to obtain the current selection policy for table items.

Parameters:

Takes no parameters.

Return Value:

Returns the currently allowed manner of selecting table items.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MTableControlState::SetAutoUpdate

virtual void SetAutoUpdate (bool flag)

Interface Category:

API.

Purpose:

Enables or disables batch updates to the list's view when multiple changes are made. When Enabled, updates happen automatically.

Calling Context:

Call this function directly to enable or disable automatic updating.

Parameters:

bool flag -If set to true, automatic updating is enabled. If set to false, automatic updating is disabled.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Only when enabled, the list view is updated automatically for each display changes.

Member Function: MTableControlState::IsAutoUpdate

virtual bool IsAutoUpdate () const

Interface Category:

API.

Purpose:

Returns true if automatic updating is enabled, otherwise false is returned.

Calling Context:

Call this function directly to determine if automatic updating is enabled or disabled.

Parameters:

Takes no parameters.

Return Value:

Returns true if automatic updating is enabled, otherwise false is returned.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MTableControlState::IsEnabled

virtual bool IsEnabled () const

Interface Category:

API.

Purpose:

Returns true if this control state is enabled, otherwise false is returned. The default implementation always returns true.

Calling Context:

Call this function directly to determine if this control state is enabled or disabled.

Parameters:

Takes no parameters.

Return Value:

Returns true if this control state is enabled, otherwise false is returned.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Deriving classes should override this member function.

Member Function: MTableControlState::GetCount

virtual unsigned long GetCount () const

Interface Category:

API.

Purpose:

Returns the number of items in this control.

Calling Context:

Call this function directly to determine the number of items in this control.

Parameters:

Takes no parameters.

Return Value:

Returns the number of items in this control.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Deriving classes must implement this member function.

Member Function: MTableControlState::GetSelectedItems

virtual void GetSelectedItems (TArrayOf < TTableItem > & set) const

Interface Category:

API.

Purpose:

Returns an array containing the items currently selected.

Calling Context:

Call this function directly to obtain the currently selected items.

Parameters:

TArrayOf < TTableItem > & set -The array to be filled in.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MTableControlState::IsCellSelected

virtual bool IsCellSelected (const TTableCell & aCell) const

Interface Category:

API.

Purpose:

Returns true if the specified cell is selected, otherwise false is returned.

Calling Context:

Call this function directly to determine if a cell is currently selected.

Parameters:

const TTableCell & aCell -The cell to check.

Return Value:

Returns true if the specified cell is selected, otherwise false is returned.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MTableControlState::GetFixedCell

virtual void GetFixedCell (TTableCell & cell) const

Interface Category:

API.

Purpose:

Returns the fixed cell from the selection list. In other words, it returns the item at the MinimumCell position of the selection list. occurred.

Calling Context:

Call this function directly by MTableControlState::HandleExtendDragSelection.

Parameters:

TTableCell & cell -The parameter to be filled in.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MTableControlState::GetMaximumCell

virtual void GetMaximumCell (TTableCell & cell) const

Interface Category:

API.

Purpose:

Fills in the supplied parameter with the last cell in the current selection list.

Calling Context:

Call this function directly to obtain the last cell in the current selection list.

Parameters:

TTableCell & cell -The parameter to be filled in.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MTableControlState::GetMinimumCell

virtual void GetMinimumCell (TTableCell & cell) const

Interface Category:

API.

Purpose:

Fills in the supplied parameter with the first cell in the current selection.

Calling Context:

Call this function directly to obtain the first cell in the current selection.

Parameters:

TTableCell & cell -The parameter to be filled in.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MTableControlState::SetEnabledItem

virtual void SetEnabledItem (const TTableItem & item, bool enabled)

Interface Category:

API.

Purpose:

Enables or disables the specified item.

Calling Context:

Call this function directly to enable or disable the specified item.

Parameters:

const TTableItem & item -The item to be enabled or disabled.
bool enabled -If set to true, the item will be enabled. If set to false, the item will be disabled.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MTableControlState::SetEnabled

virtual void SetEnabled (bool enabled)

Interface Category:

API.

Purpose:

Enables or disables this control. The default implementation does nothing.

Calling Context:

Call this function directly to enable or disable the control.

Parameters:

bool enabled -If set to true, this control will be enabled. If set to false, this control will be disabled.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Deriving classes should override this member function.

Member Function: MTableControlState::SetSelectedItem

virtual void SetSelectedItem (TTableItem & item, bool selected)

Interface Category:

API.

Purpose:

Enables or disables the selection state for the specified item.

Calling Context:

Call this function directly to enable or disable an item's selection state.

Parameters:

TTableItem & item -The item whose selection state is enabled or disabled.
bool selected -If set to true, the item will be selected. If set to false the item will be unselected.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MTableControlState::SetSelectedItems

virtual void SetSelectedItems (TDequeOf < TTableItem > & set, bool selected)

Interface Category:

API.

Purpose:

Enables or disables the selection state for the specified set of items.

Calling Context:

Call this function directly to enable or disable the selection state for a list of items.

Parameters:

TDequeOf < TTableItem > & set -The list of items whose selection state is to be enabled or disabled.
bool selected -If set to true, the item will be selected. If set to false the item will be unselected.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MTableControlState::ClearSelectedItems

virtual void ClearSelectedItems ()

Interface Category:

API.

Purpose:

Disables the selection state for all items in the list.

Calling Context:

Call this function directly to deselect all items in the list.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MTableControlState::Select

virtual void Select (TArrayOf < TTableItem > & items)

Interface Category:

API.

Purpose:

Override this method to implement an immediate response to list item selection. The default implementation does nothing.

Calling Context:

Called from the list's interactor when the interaction has finished.

Parameters:

TArrayOf < TTableItem > & items -The items to be selected.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Deriving classes should override this member function.

Member Function: MTableControlState::HandleDoubleClick

virtual void HandleDoubleClick (const TTableItem & item)

Interface Category:

API.

Purpose:

Handle the processing required for a double-clicked item. The default implementation does nothing.

Calling Context:

Called when the user double-clicks on an item.

Parameters:

const TTableItem & item -The item on which the user double-clicked.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Deriving classes should override this member function.

Member Function: MTableControlState::HandleSimpleSelection

virtual void HandleSimpleSelection (const TTableCell & cell)

Interface Category:

API.

Purpose:

kOneOnly or kOneOrNone: Clear all the other selections, and Select the specified item. kMultipleAny: When the specified cell item is outside the current selection list, then clear all the current selection, and make the specified cell item the current selection. When the specified cell item is within the current selection list, then do nothing. kMultipleContiguous: Perform the same as in HandleExtendSelection.

Calling Context:

Called from the list interactor when an item is selected.

Parameters:

const TTableCell & cell -The item to be selected.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MTableControlState::HandleExtendSelection

virtual void HandleExtendSelection (const TTableCell & cell)

Interface Category:

API.

Purpose:

kOneOnly or kNoneOrOne: Set the specified cell as the only selected cell. kMultipleAny or kMultipleContiguous: If no previous selection, then Set the specified cell as the current selection. If with previous selection, extend the selection from the maximum row to this specified cell (now the new minimum), and include everything in between too.

Calling Context:

Called to extent the set of selected cells.

Parameters:

const TTableCell & cell -The cell to add the set of selected cells.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MTableControlState::HandleToggleSelection

virtual void HandleToggleSelection (const TTableCell & cell)

Interface Category:

API.

Purpose:

For kOneOnly: Clear all the other selection, and select the specified cell. For kNoneOrOne: Clear all the other selection, and toggle the selection state of the specified cell. If the cell is currently not selected, then select it. If the cell is currently selected, then deselect it. For kMultipleAny: Everything else remain the same. Toggle the selection state of the specified cell. If the cell is currently not selected, then select it. If the cell is currently selected, then deselect it. For kMultipleContiguous: Perform the same way as in HandleExtendSelection.

Calling Context:

Called to toggle the selection state of the specified cell.

Parameters:

const TTableCell & cell -The cell to be toggled.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MTableControlState::HandleExtendDragSelection

virtual void HandleExtendDragSelection (const TTableCell & beginCell, const TTableCell & endCell)

Interface Category:

API.

Purpose:

kOneOnly or kNoneOrOne: Make the endCell the current selected cell. kMultipleAny or kMultipleContiguous: Selects the cells in the range specified by beginCell and endCell. Always make these selection contiguous during drag.

Calling Context:

Called to select a range of cells.

Parameters:

const TTableCell & beginCell -The first cell in the range.
const TTableCell & endCell -The last cell in the range.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MTableControlState::HandleToggleDragSelection

virtual void HandleToggleDragSelection (const TTableCell & beginCell, const TTableCell & endCell)

Interface Category:

API.

Purpose:

kOneOnly: Make the endCell current selection. kNoneOrOne: The same as HandleSimpleSelection. kMultipleAny: Allow discontiguously selected items to be added to the selection list. Or, allow discontiguously deselected items to be removed from the selection list. kMultipleContiguous: Acts the same as HandleExtendDragSelection.

Calling Context:

Called to de-select as range of cells.

Parameters:

const TTableCell & beginCell -The first cell in the range.
const TTableCell & endCell -The last cell in the range.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MTableControlState::HandleDragSelection

virtual void HandleDragSelection (const TTableCell & beginCell, const TTableCell & endCell)

Interface Category:

API.

Purpose:

kOneOnly: Makes the endCell as the current selection. kNoneOrOne: Makes the endCell as the current selection if the endCell is not currently selected. Otherwise, deselect the endCell. kMultipleAny: If no item is currently selected, always select the endCell. If one item is selected, and the mouse position starts to drag from that selected item, then, make the endCell (ie new mouse position) the current selection. If there is a range of selected items, and mouse start to drag within this selected range, then deselect the beginCell and select the endCell. kMultipleContiguous: Acts the same as HandleExtendDragSelection.

Calling Context:

Called to select a range of cells.

Parameters:

const TTableCell & beginCell -The first cell in the range.
const TTableCell & endCell -The last cell in the range.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MTableControlState::AddInterests

virtual void AddInterests (TSetOf < TInterest > & set)

Interface Category:

API.

Purpose:

Adds in the state changed interest that the control is interested in. This then provides the connection to receive state changed notification.

Calling Context:

Call this function directly to add state changed notification.

Parameters:

TSetOf < TInterest > & set -The interest set.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MTableControlState::GetItemFromCell

virtual TTableItem * GetItemFromCell (const TTableCell & cell) const

Interface Category:

API.

Purpose:

Returns the item from the specified cell.

Calling Context:

Call this function directly to obtain the item from the specified cell.

Parameters:

const TTableCell & cell -The cell whose item is to be returned.

Return Value:

Returns the item from the specified cell.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Deriving classes must provide an implementation for this member function.

Member Function: MTableControlState::GetCellFromItem

virtual void GetCellFromItem (TTableCell & cell, const TTableItem & item) const

Interface Category:

API.

Purpose:

Fills in the cell parameter with the cell representing the item.

Calling Context:

Call this function directly to obtain the cell representing the specified item.

Parameters:

TTableCell & cell -The parameter to be filled.
const TTableItem & item -The item whose location is the cell to be obtained.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Deriving classes must provide an implementation for this member function.

Member Function: MTableControlState::NotifyControlOfChange

virtual void NotifyControlOfChange ()

Interface Category:

API.

Purpose:

Notify control to update the view for the interest that the control has requested through AddInterests.

Calling Context:

Called to notify the control with this control state change.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MTableControlState::CreateInterest

virtual TInterest * CreateInterest ()

Interface Category:

API.

Purpose:

Creates an interest object for this control state.

Calling Context:

Called to obtain an interest object for this control state.

Parameters:

Takes no parameters.

Return Value:

Returns a pointer to an interest object for this control state.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MTableControlState::AddSelectedCell

virtual void AddSelectedCell (const TTableCell & cell)

Interface Category:

API.

Purpose:

Adds the specified cell to the selection list.

Calling Context:

Call this function directly to add a cell to the selection list.

Parameters:

const TTableCell & cell -The cell to add to the selection list.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MTableControlState::RemoveSelectedCell

virtual void RemoveSelectedCell (const TTableCell & cell)

Interface Category:

API.

Purpose:

Removes the specified cell from the selection list.

Calling Context:

Call this function directly to remove a cell from the selection list.

Parameters:

const TTableCell & cell -The cell to remove from the selection list.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MTableControlState::GetSelectedCells

virtual const TDequeOf < TTableCell > * GetSelectedCells ()

Interface Category:

API.

Purpose:

Returns the cells currently selected.

Calling Context:

Call this function directly to obtain the cells currently selected.

Parameters:

Takes no parameters.

Return Value:

A pointer to a deque containing the cells currently selected.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MTableControlState::SynchronizeSelections

virtual void SynchronizeSelections ()

Interface Category:

API.

Purpose:

Clears the list containing the selected cell positions so that the selected items may register their new cell positions.

Calling Context:

Call this function directly to clear the list containing the selected cell positions.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MTableControlState::GetSingleDefaultSelectableItem

virtual TTableItem * GetSingleDefaultSelectableItem () const

Interface Category:

API.

Purpose:

Returns the first enabled and selected item.

Calling Context:

Call this function directly to obtain the first enabled and selected item.

Parameters:

Takes no parameters.

Return Value:

Returns the first enabled and selected item.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The derived class MUST override this method.

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