ThemeListModel Class Reference
[QtBaseModule]

Detailed Description

The ThemeListModel class provides a list model that is used for list functionality in Qt Extended theming.

List functionality in theming is implemented using Qt's model-view architecture and theme templates.

To use a ThemeListModel you pass in the associated ThemeListItem and ThemedView objects during construction, and then populate it with ThemeListModelEntry items using the addEntry() and removeEntry() functions. The ThemeListModel installs itself as the model for the ThemeListItem's QListView object during construction. From that point on communication between the QListView and the ThemeListModel occurs through Qt's model-view architecture.

Theme templates are used to describe the visual look of items in the ThemeListModel. As a list's items are added dynamically at runtime, they cannot be specified in the themed view XML. However, using theme templates, the visual appearance of a list item is defined instead, which is used to draw items as appropriate. Instances of these theme templates can be created at anytime using ThemeTemplateItem::createInstance().

An internal implementation of QItemDelegate called ThemeListDelegate exists to handle communication between the QListView of a ThemeListItem, and associated ThemeListModel/ThemeListModelEntry objects. It works completely under the hood, and so this information is given only to help the developer understand how the system works.

The ThemeListDelegate is installed using QListView::setItemDelegate() on the ThemeListItem's QListView. Qt's model-view architecture then asks the delegate to paint items in the QListView as required. When requested to repaint a particular QModelIndex in the QListView, the ThemeItemDelegate performs the following functions:

• The index is used to look up the associated ThemeListModelEntry through the associated ThemeListModel. The ThemeItemDelegate asserts that the return value of QListView::model() is an object that inherits from ThemeListModel.
• If no template instance has been created for the ThemeListModelEntry object, a new one is created using by calling ThemeListModelEntry::templateInstance() which calls ThemeTemplateItem::createInstance().
• If a template instance exists but the value returned by its itemName() function is not equal to the value returned by the ThemeListModelEntry's type() function, then the delegate deletes the existing template instance and calls ThemeTemplateItem::templateInstance() to get a new one.
• A pointer to the template instance is stored in the ThemeListModelEntry object.
• The template instance for the ThemeListModelEntry object is painted to the QListView at the index.

See the ThemeTemplateItem and ThemeListModelEntry documentation for more information.

The valuespace is used to communicate data from the system to items in the themed list. Normally a valuespace path can be assigned in the themed view XML to items using the vspath attribute of ThemeItem. However, as template definitions representing a theme list items' visual appearance are not actual instances, their vspath is dynamically determined and set at runtime when they are created using ThemeTemplateItem::createInstance(). ThemeTemplateItem::createInstance() takes a uid which is actually set to the vspath of the returned ThemeTemplateInstance. For template instances created by ThemeListModelEntry::templateInstance() the uid passed is the return value of ThemeListModelEntry::uid(). This acts as a unique association between a theme template instance and the ThemeListModelEntry, as well as a unique valuespace path for both to communicate under. A call to ThemeListModelEntry::setValue() set keys under this unique vspath. For example, given the following themed view XML definition:

    <list vspath="/UserInterface/MyList/">
        <template name="myListItem">
            <text name="titleMessage">@TitleMessage</text>
        </template>
    </list>

you could set the text of the element 'titleMessage' with the following:

    ThemeListModelEntry* myEntry; // assuming that myEntry->type() returns "myListItem"
    ..
    myEntry->setValue("TitleMessage", "Hello, World"); // expands to /UserInterface/MyList/<myEntry->uid()>/TitleMessage

See also Themed View Elements, ThemeTemplateItem, ThemeTemplateInstanceItem, and ThemeListModelEntry.

Member Function Documentation

ThemeListModel::ThemeListModel ( QObject * parent, ThemeListItem * listItem, ThemedView * view )

Constructs a ThemeListModel. parent is passed to QAbstractListModel, listItem is the ThemeListItem associated with this model and view is the ThemedView associated with this model. The model is installed on the ThemeListItem listItem using the ThemeListItem::setModel() function.

ThemeListModel::~ThemeListModel ()   [virtual]

Destroys the model. All items in the model are deleted.

void ThemeListModel::addEntry ( ThemeListModelEntry * item )

Adds item to the end of this model. ThemeListModel takes ownership of item and will delete it when it is removed.

void ThemeListModel::clear ()

Clears all items from the model. The items are deleted.

QModelIndex ThemeListModel::entryIndex ( const ThemeListModelEntry * entry ) const

Returns the index of the item entry in the model.

QList<ThemeListModelEntry *> ThemeListModel::items () const   [protected]

Returns a QList of all items in the model.

ThemeListItem * ThemeListModel::listItem () const

Returns the ThemeListItem instance associated with this model.

void ThemeListModel::removeEntry ( const QModelIndex & index )

Removes the item at index from the mdoel. The item is deleted.

ThemeListModelEntry * ThemeListModel::themeListModelEntry ( const QModelIndex & index ) const

Returns a pointer to the ThemeListModelEntry at index.

ThemedView * ThemeListModel::themedView () const

Returns the ThemedView instance associated with this model.

void ThemeListModel::triggerUpdate ()

Triggers an update in the view for all items in the model.