Wt  4.10.4
Public Member Functions | Static Public Member Functions | List of all members
Wt::WModelIndex Class Reference

A value class that describes an index to an item in a data model. More...

#include <Wt/WModelIndex.h>

Public Member Functions

 WModelIndex ()
 Create an invalid WModelIndex. More...
 
int column () const
 Returns the column for this model index. More...
 
int row () const
 Returns the row for this model index. More...
 
void * internalPointer () const
 Returns the internal pointer. More...
 
::uint64_t internalId () const
 Returns the internal id. More...
 
WModelIndex child (int row, int column) const
 Returns a model index for a child item. More...
 
WModelIndex parent () const
 Returns an index to the parent. More...
 
cpp17::any data (ItemDataRole role=ItemDataRole::Display) const
 Returns data in the model at this index. More...
 
WFlags< ItemFlagflags () const
 Returns the flags for this item. More...
 
bool isValid () const
 Returns whether the index is a real valid index. More...
 
const WAbstractItemModelmodel () const
 Returns the model to which this (valid) index is bound. More...
 
bool operator== (const WModelIndex &other) const
 Comparison operator. More...
 
bool operator!= (const WModelIndex &other) const
 Comparison operator. More...
 
bool operator< (const WModelIndex &other) const
 Comparison operator. More...
 
void encodeAsRawIndex ()
 Encode to raw index (before a layout change). More...
 
WModelIndex decodeFromRawIndex () const
 Decodes a raw index (after a layout change). More...
 
int depth () const
 Returns the depth (in a hierarchical model). More...
 

Static Public Member Functions

static void encodeAsRawIndexes (WModelIndexSet &indexes)
 Utility method for converting an entire set of indexes to raw. More...
 
static void encodeAsRawIndexes (std::unordered_set< WModelIndex > &indexes)
 Utility method for converting an entire set of indexes to raw. More...
 
static WModelIndexSet decodeFromRawIndexes (const WModelIndexSet &encodedIndexes)
 Utility method to decode an entire set of raw indexes. More...
 
static std::unordered_set< WModelIndexdecodeFromRawIndexes (const std::unordered_set< WModelIndex > &encodedIndexes)
 Utility method to decode an entire set of raw indexes. More...
 
static bool isAncestor (const Wt::WModelIndex &i1, const Wt::WModelIndex &i2)
 Returns whether i2 is an ancestor of i1.
 

Detailed Description

A value class that describes an index to an item in a data model.

Indexes are used to indicate a particular item in a WAbstractItemModel. An index points to the item by identifying its row and column location within a parent model index.

An index is immutable.

The default constructor creates an invalid index, which by convention indicates the parent of top level indexes. Thus, a model that specifies only a list or table of data (but no hierarchical data) would have as valid indexes only indexes that specify the invalid model index as parent.

Upon the model's choice, model indexes for hierarchical models may have an internal Id represented by a int64_t (internalId()), a pointer (internalPointer()).

Indexes are created by the model, within the protected WAbstractItemModel::createIndex() methods. In this way, models can define an internal pointer or id suitable for identifying parent items in the model.

When a model's geometry changes due to row or column insertions or removals, you may need to update your indexes, as otherwise they may no longer point to the same item (but instead still to the same row/column). Thus, if you store indexes and want to support model changes such as row or columns insertions/removals, then you need to react to the corresponding signals such as WAbstractItemModel::rowsInserted() to update these indexes (i.e. shift them), or even remove them when the corresponding row/column has been removed.

When a model's layout changes (it is rearranging its contents for example in response to a sort operation), a similar problem arises. Some models support tracking of indexes over layout changes, using raw indexes. In reaction to WAbstractItemModel::layoutAboutToBeChanged(), you should encode any index which you wish to recover after the layout change using encodeAsRawIndex(), and in WAbstractItemModel::layoutChanged() you can obtain an index that points to the same item using decodeFromRawIndex().

See also
WAbstractItemModel

Constructor & Destructor Documentation

◆ WModelIndex()

Wt::WModelIndex::WModelIndex ( )

Create an invalid WModelIndex.

Returns a model index for which isValid() return false.

Member Function Documentation

◆ child()

WModelIndex Wt::WModelIndex::child ( int  row,
int  column 
) const

Returns a model index for a child item.

This is a convenience method, and is only defined for indexes that are valid().

It has the same function as WAbstractItemModel::index() but is less general because the latter expression may also be used to retrieve top level children, i.e. when index is invalid.

See also
WAbstractItemModel::index(), isValid()

◆ column()

int Wt::WModelIndex::column ( ) const

Returns the column for this model index.

See also
row()

◆ data()

cpp17::any Wt::WModelIndex::data ( ItemDataRole  role = ItemDataRole::Display) const

Returns data in the model at this index.

This is a convenience method for WAbstractItemModel::data().

See also
WAbstractItemModel::data()
ItemDataRole

◆ decodeFromRawIndex()

WModelIndex Wt::WModelIndex::decodeFromRawIndex ( ) const

Decodes a raw index (after a layout change).

A raw index can be decoded, within the context of a model that has been re-layed out.

This method returns a new index that points to the same item, or, WModelIndex() if the underlying model did not support encoding to raw indexes, or, if the item to which the index previously pointed, is no longer part of the model.

See also
WAbstractItemModel::fromRawIndex(), WAbstractItemModel::layoutChanged()
encodeAsRawIndex()

◆ decodeFromRawIndexes() [1/2]

std::unordered_set< WModelIndex > Wt::WModelIndex::decodeFromRawIndexes ( const std::unordered_set< WModelIndex > &  encodedIndexes)
static

Utility method to decode an entire set of raw indexes.

See also
decodeFromRawIndex()

◆ decodeFromRawIndexes() [2/2]

WModelIndexSet Wt::WModelIndex::decodeFromRawIndexes ( const WModelIndexSet encodedIndexes)
static

Utility method to decode an entire set of raw indexes.

See also
decodeFromRawIndex()

◆ depth()

int Wt::WModelIndex::depth ( ) const

Returns the depth (in a hierarchical model).

A top level index has depth 0.

◆ encodeAsRawIndex()

void Wt::WModelIndex::encodeAsRawIndex ( )

Encode to raw index (before a layout change).

Use this method to encode an index for which you want to recover an index after the layout change to the same item (which may still be in the model, but at a different location).

An index that has been encoded as a raw index cannot be used for anything but decodeFromRawIndex() at a later point.

See also
WAbstractItemModel::toRawIndex(), WAbstractItemModel::layoutAboutToBeChanged()
decodeFromRawIndex()

◆ encodeAsRawIndexes() [1/2]

void Wt::WModelIndex::encodeAsRawIndexes ( std::unordered_set< WModelIndex > &  indexes)
static

Utility method for converting an entire set of indexes to raw.

See also
encodeAsRawIndex()

◆ encodeAsRawIndexes() [2/2]

void Wt::WModelIndex::encodeAsRawIndexes ( WModelIndexSet indexes)
static

Utility method for converting an entire set of indexes to raw.

See also
encodeAsRawIndex()

◆ flags()

WFlags< ItemFlag > Wt::WModelIndex::flags ( ) const

Returns the flags for this item.

This is a convenience method for WAbstractItemModel::flags().

See also
WAbstractItemModel::flags()
ItemFlag

◆ internalId()

::uint64_t Wt::WModelIndex::internalId ( ) const

Returns the internal id.

The internal id is used by the model to retrieve the corresponding data.

This is only defined when the model created the index using WAbstractItemModel::createIndex(int, int, uint64_t) const.

See also
internalPointer()
WAbstractItemModel::createIndex(int, int, uint64_t) const

◆ internalPointer()

void* Wt::WModelIndex::internalPointer ( ) const

Returns the internal pointer.

The internal pointer is used by the model to retrieve the corresponding data.

This is only defined when the model created the index using WAbstractItemModel::createIndex(int, int, void *) const.

See also
internalId(),
WAbstractItemModel::createIndex(int, int, void *) const

◆ isValid()

bool Wt::WModelIndex::isValid ( ) const

Returns whether the index is a real valid index.

Returns true when the index points to a valid data item, i.e. at a valid row() and column().

An index may be invalid for two reasons:

  • an operation requested an index that was out of model bounds,
  • or, the index corresponds to the model's top level root item, and is thus the parent index for top level items.

◆ model()

const WAbstractItemModel* Wt::WModelIndex::model ( ) const

Returns the model to which this (valid) index is bound.

This returns the model that created the model index.

◆ operator!=()

bool Wt::WModelIndex::operator!= ( const WModelIndex other) const

Comparison operator.

See also
operator==()

◆ operator<()

bool Wt::WModelIndex::operator< ( const WModelIndex other) const

Comparison operator.

Returns true if the index comes topologically before other.

Topological order follows the order in which the indexes would be displayed in a tree table view, from top to bottom followed by left to right.

An invalid index comes before all other indexes. Indexes encoded as raw index come after the invalid index and before all other indexes, and are ordered according to their internalId().

◆ operator==()

bool Wt::WModelIndex::operator== ( const WModelIndex other) const

Comparison operator.

Returns true only if the indexes point at the same data, in the same model.

◆ parent()

WModelIndex Wt::WModelIndex::parent ( ) const

Returns an index to the parent.

This is a convenience method for WAbstractItemModel::parent().

For a top level data item, the parent() is an invalid index (see WModelIndex()).

See also
WAbstractItemModel::parent()

◆ row()

int Wt::WModelIndex::row ( ) const

Returns the row for this model index.

See also
column()