MList implements a list view. More...

Inheritance diagram for MList:

Collaboration diagram for MList:

Public Types
enum	SelectionMode { NoSelection, SingleSelection, MultiSelection }
enum	ScrollHint { EnsureVisibleHint, PositionAtTopHint, PositionAtBottomHint, PositionAtCenterHint }
enum	DisplayMode { Hide = 0, Show, Auto, Floating }
enum	ListOptimizationFlag { DontCallCreateCellDuringUpdate = 0x1 }
Public Slots
void	selectItem (const QModelIndex &index)
void	longTapItem (const QModelIndex &index)
void	longTapItem (const QModelIndex &index, const QPointF &position)
void	scrollTo (const QModelIndex &index)
void	scrollTo (const QModelIndex &index, ScrollHint hint)
void	setIndexVisible (bool visible)
void	setIndexDisplayMode (DisplayMode displayMode)
DisplayMode	indexDisplayMode () const
Signals
void	scrollToIndex (const QModelIndex &index)
void	selectionModelChanged (QItemSelectionModel *selectionModel)
void	itemClicked (const QModelIndex &index)
void	itemLongTapped (const QModelIndex &index)
void	itemLongTapped (const QModelIndex &index, const QPointF &position)
void	panningStarted ()
void	panningStopped ()
Public Member Functions
	MList (QGraphicsItem *parent=0)
virtual	~MList ()
void	setItemModel (QAbstractItemModel *itemModel)
QAbstractItemModel *	itemModel () const
void	setCellCreator (MCellCreator *cellCreator)
const MCellCreator *	cellCreator () const
void	setHeaderCreator (MCellCreator *cellCreator)
const MCellCreator *	headerCreator () const
void	setColumns (int columns)
int	columns () const
QItemSelectionModel *	selectionModel () const
void	setSelectionModel (QItemSelectionModel *selectionModel)
void	setSelectionMode (MList::SelectionMode mode)
MList::SelectionMode	selectionMode () const
const QModelIndex	firstVisibleItem () const
const QModelIndex	lastVisibleItem () const
bool	showGroups () const
void	setShowGroups (bool showGroups)
bool	indexVisible ()
MListFilter *	filtering () const
ListOptimizationFlags	optimizationFlags () const
void	setOptimizationFlag (ListOptimizationFlag optimizationFlag, bool enabled=true)
void	setOptimizationFlags (ListOptimizationFlags optimizationFlags)
Protected Member Functions
	MList (MListPrivate dd, MListModel model, QGraphicsItem *parent)
virtual void	updateData (const QList< const char * > &modifications)
virtual void	contextMenuEvent (QGraphicsSceneContextMenuEvent *event)
virtual void	keyPressEvent (QKeyEvent *event)
virtual void	connectNotify (const char *signal)
virtual void	disconnectNotify (const char *signal)
Properties
bool	showGroups
int	columns
SelectionMode	selectionMode

Detailed Description

MList implements a list view.

MList provides support for data that inherits QAbstractItemModel and can be set by setItemModel().

Unlike, Qt model/view widgets, MList only shows one "view" column. To show multiple model columns in a MList, you should create a custom widget in your MCellCreator::createCell() implementation and use your MCellCreator::updateCell() implementation to show the various items of data from each column in one widget.

See http://doc.trolltech.com/4.5/model-view-creating-models.html#a-read-only-example-model for how to build a custom item model that can be used with MList.

A very minimal basic item model example is shown below. The example model has 1 items and that item is MContentItem.

Important thing to remember is model defines protocol between model and list. Model defines the way data will be passed to MCellCreator which will create widgets.

Model will look like this:

  class TestModel : public QAbstractListModel
  {
     Q_OBJECT

   public:
     TestModel(QObject *parent = 0)
        : QAbstractListModel(parent) {}

     int rowCount(const QModelIndex &parent = QModelIndex()) const;
     QVariant data(const QModelIndex &index, int role) const;

  };


  int TestModel::rowCount(const QModelIndex &parent) const
  {
     Q_UNUSED(parent);
     return 1;
  }

  QVariant TestModel::data(const QModelIndex &index, int role) const
  {
    if (role == Qt::DisplayRole) {
        QStringList rowData;
        rowData << "Angelina"; // first name
        rowData << "Joli"; // last name
        return QVariant(rowData);
    }

    return QVariant();
  }

Model doesn't tell MList how to create actual widgets, we need MCellCreator for that. MAbstractCellCreator is the best candidate for simple case (keep in mind that you can change style of MContentItem only in it's constructor, so if other style is needed, MAbstractCellCreator will not work, MCellCreator should be used instead):

  class MContentItemCreator : public MAbstractCellCreator<MContentItem>
  {
  public:
      void updateCell(const QModelIndex& index, MWidget * cell) const
      {
          MContentItem * contentItem = qobject_cast<MContentItem *>(cell);
          QVariant data = index.data(Qt::DisplayRole);
          QStringList rowData = data.value<QStringList>();
          contentItem->setTitle(rowData[0]);
          contentItem->setSubtitle(rowData[1]);
      }
  };

And finally it can be combined in a list:

    MList * list = new MList(panel);
    MContentItemCreator * cellCreator = new MContentItemCreator;
    list->setCellCreator(cellCreator);
    TestModel * model = new TestModel;
    list->setItemModel(model);

Member Enumeration Documentation

enum MList::DisplayMode

Enumerator:

Hide	The list index is always hidden.
Show	The list index is always visible.
Auto	The list index appears on panning, and disappears when panning is stopped.
Floating	The list index appears on tapping right area of the list.

Definition at line 188 of file corelib/widgets/mlist.h.

                     {
        Hide = 0,
        Show,
        Auto,
        Floating
    };

enum MList::ListOptimizationFlag

Enumerator:

DontCallCreateCellDuringUpdate

MAbstractCellCreator::createCell() will be called only on new items. If items receives update only MAbstractCellCreate::updateCell() will be called. Enabled by default.

Definition at line 209 of file corelib/widgets/mlist.h.

                              {
        DontCallCreateCellDuringUpdate = 0x1
    };

enum MList::ScrollHint

Enumerator:

EnsureVisibleHint	Scroll to ensure that the item is visible.
PositionAtTopHint	Scroll to position the item at the top of the viewport.
PositionAtBottomHint	Scroll to position the item at the bottom of the viewport.
PositionAtCenterHint	Scroll to position the item at the center of the viewport.

Definition at line 169 of file corelib/widgets/mlist.h.

                    {
        EnsureVisibleHint,
        PositionAtTopHint,
        PositionAtBottomHint,
        PositionAtCenterHint
    };

enum MList::SelectionMode

This enumerated type is used by MList to indicate how it reacts to selection by the user.

Enumerator:

NoSelection	Items cannot be selected.
SingleSelection	When the user selects an item, any already-selected item becomes unselected.
MultiSelection	When the user selects an item in the usual way, the selection status of that item is toggled and the other items are left alone.

Definition at line 154 of file corelib/widgets/mlist.h.

                       {
        NoSelection,
        SingleSelection,
        MultiSelection
    };

Constructor & Destructor Documentation

MList::MList ( QGraphicsItem * parent = 0 )

Constructor for creating an empty object.

Parameters:

parent

Parent object.

Definition at line 74 of file mlist.cpp.

    : MWidgetController(new MListPrivate, new MListModel, parent)

{
    Q_D(MList);
    d->init();
}

MList::~MList ( ) [virtual]

Destructor.

Definition at line 82 of file mlist.cpp.

{
    delete model()->cellCreator();
}

Here is the call graph for this function:

MList::MList	(	MListPrivate *	dd,
		MListModel *	model,
		QGraphicsItem *	parent
	)			`[protected]`

Definition at line 67 of file mlist.cpp.

    : MWidgetController(dd, model, parent)
{
    Q_D(MList);
    d->init();
}

Member Function Documentation

const MCellCreator * MList::cellCreator ( ) const

Returns cell creator associated with MList

Definition at line 197 of file mlist.cpp.

{
    return model()->cellCreator();
}

Here is the call graph for this function:

int MList::columns ( ) const

void MList::connectNotify ( const char * signal ) [protected, virtual]

Handler of notifications of new receivers connected to MList signals.

Definition at line 307 of file mlist.cpp.

{
    Q_D(MList);
    if (QLatin1String(signal) == SIGNAL(itemLongTapped(QModelIndex)) ||
        QLatin1String(signal) == SIGNAL(itemLongTapped(QModelIndex,QPointF))) {
        d->updateLongTapConnections();
    }
}

Here is the call graph for this function:

void MList::contextMenuEvent ( QGraphicsSceneContextMenuEvent * event ) [protected, virtual]

Notification of context menu event.

Reimplemented from MWidget.

Definition at line 98 of file mlist.cpp.

{
    MWidgetController::contextMenuEvent(event);
}

void MList::disconnectNotify ( const char * signal ) [protected, virtual]

Handler of notifications of receivers disconnecting from MList signals.

Definition at line 316 of file mlist.cpp.

{
    Q_D(MList);
    if (QLatin1String(signal) == SIGNAL(itemLongTapped(QModelIndex)) ||
        QLatin1String(signal) == SIGNAL(itemLongTapped(QModelIndex,QPointF))) {
        d->updateLongTapConnections();
    }
}

Here is the call graph for this function:

MListFilter * MList::filtering ( ) const

Returns:: filter which implements live filtering of list contents.

Definition at line 287 of file mlist.cpp.

{
    MListPrivate* d = static_cast<MListPrivate*>(d_ptr);
    if (d->listFilter == 0) {
        // Postpone the creation of the list filter until it is requested
        // to speedup the startup performance
        d->listFilter = new MListFilter(const_cast<MList*>(this));
        d->listFilter->setEnabled(false);
    }
    return d->listFilter;
}

const QModelIndex MList::firstVisibleItem ( ) const

Returns:: index of first visible item

Definition at line 212 of file mlist.cpp.

{
    return model()->firstVisibleItem();
}

Here is the call graph for this function:

const MCellCreator * MList::headerCreator ( ) const

Returns header creator associated with MList

Definition at line 207 of file mlist.cpp.

{
    return model()->headerCreator();
}

Here is the call graph for this function:

MList::DisplayMode MList::indexDisplayMode ( ) const [slot]

Returns visibility mode of list index.

See also:: MList::DisplayMode

Definition at line 250 of file mlist.cpp.

{
    return static_cast<MList::DisplayMode>(model()->listIndexDisplayMode());
}

Here is the call graph for this function:

bool MList::indexVisible ( )

Returns:: Returns the status of the list index availability.

Deprecated:: Please use indexDisplayMode()

Definition at line 255 of file mlist.cpp.

{
    return model()->listIndexVisible();
}

Here is the call graph for this function:

void MList::itemClicked ( const QModelIndex & index ) [signal]

Emitted when an item is clicked.

void MList::itemLongTapped ( const QModelIndex & index ) [signal]

Emitted when an item is long tapped.

Deprecated:: The MList::itemLongTapped(QModelIndex, QPointF) extends the signal.

void MList::itemLongTapped	(	const QModelIndex &	index,
		const QPointF &	position
	)			`[signal]`

Emitted when an item is long tapped. Also provides tap location.

QAbstractItemModel * MList::itemModel ( ) const

Returns model, associated with the MList.

Definition at line 118 of file mlist.cpp.

{
    return model()->itemModel();
}

Here is the call graph for this function:

void MList::keyPressEvent ( QKeyEvent * event ) [protected, virtual]

Handling of key events

Definition at line 299 of file mlist.cpp.

{
    Q_D(MList);

    if (d->listFilter && d->listFilter->enabled())
        d->listFilter->keyPressEvent(event);
}

const QModelIndex MList::lastVisibleItem ( ) const

Returns:: index of last visible item

Definition at line 217 of file mlist.cpp.

{
    return model()->lastVisibleItem();
}

Here is the call graph for this function:

void MList::longTapItem ( const QModelIndex & index ) [slot]

Convenience function - Emits a long tap event for an item.

Deprecated:: Use MList::longTapItem(QModelIndex, QPointF) instead.

Definition at line 179 of file mlist.cpp.

{
    longTapItem(index, QPointF());
}

void MList::longTapItem	(	const QModelIndex &	index,
		const QPointF &	position
	)			`[slot]`

Convenience function - Emits a long tap event for an item. Also provides tap location.

Definition at line 184 of file mlist.cpp.

{
    emit itemLongTapped(index);
    emit itemLongTapped(index, position);
}

Here is the call graph for this function:

MList::ListOptimizationFlags MList::optimizationFlags ( ) const

Returns:: list's optimization flags.

Definition at line 325 of file mlist.cpp.

{
    Q_D(const MList);
    return ListOptimizationFlags(d->optimizationFlags);
}

void MList::panningStarted ( ) [signal]

Emitted when list is moving, e.g. pannable by user.

void MList::panningStopped ( ) [signal]

Emitted when list stopped moving.

void MList::scrollTo ( const QModelIndex & index ) [slot]

Scrolls list to a specific index. Call to function will ensure that item with specified index becomes visible.

Definition at line 123 of file mlist.cpp.

{
    scrollTo(index, MList::EnsureVisibleHint);
}

void MList::scrollTo	(	const QModelIndex &	index,
		ScrollHint	hint
	)			`[slot]`

Scrolls list to a specific index with specified hint.

Definition at line 128 of file mlist.cpp.

{
    emit scrollToIndex(index);

    model()->beginTransaction();
    model()->setScrollHint(hint);
    model()->setScrollToIndex(index);
    model()->commitTransaction();
}

Here is the call graph for this function:

void MList::scrollToIndex ( const QModelIndex & index ) [signal]

Emitted when scrollTo(index) is called to tell the view to scroll to the given item index.

MList::SelectionMode MList::selectionMode ( ) const

Returns:: selection mode of a list

QItemSelectionModel * MList::selectionModel ( ) const

Returns the current selection model.

Definition at line 138 of file mlist.cpp.

{
    return model()->selectionModel();
}

Here is the call graph for this function:

void MList::selectionModelChanged ( QItemSelectionModel * selectionModel ) [signal]

Emitted when the selection model has changed.

void MList::selectItem ( const QModelIndex & index ) [slot]

Convenience function - Select the given item. If index is not valid, the current selection is not changed.

Definition at line 153 of file mlist.cpp.

{
    QItemSelectionModel *sModel = selectionModel();

    if (index.isValid() && sModel->model() != index.model()) {
        qWarning("MList::selectItem() failed: "
                 "Trying to select an item that is for"
                 " a different model than the view ");
        return;
    }

    if (sModel != NULL) {
        if (selectionMode() == MList::MultiSelection) {
            if (sModel->isSelected(index)) {
                sModel->select(index, QItemSelectionModel::Deselect);
            } else {
                sModel->select(index, QItemSelectionModel::Select);
            }
        } else if (selectionMode() == MList::SingleSelection) {
            sModel->select(index, QItemSelectionModel::ClearAndSelect);
        }
    }

    emit itemClicked(index);
}

Here is the call graph for this function:

void MList::setCellCreator ( MCellCreator * cellCreator )

Set's cell creator which will map data from model to widgets which will be displayed by MList. Ownership is transferred to MList.

See also:: MCellCreator

Definition at line 190 of file mlist.cpp.

{
    delete model()->cellCreator();

    model()->setCellCreator(itemCreator);
}

Here is the call graph for this function:

void MList::setColumns ( int columns )

Sets the amount of columns to be used for presenting list items. Set to 1 by default.

When columns is > 1, the rows will be split vertically, making the cell widget narrower, with rows flowing from top-to-bottom into the next column. For instance, this could be used to create a "grid" list.

Definition at line 265 of file mlist.cpp.

{
    model()->setColumns(columns);
}

Here is the call graph for this function:

void MList::setHeaderCreator ( MCellCreator * cellCreator )

Set's header creator which will map data from model to widgets which will be displayed by MList in the header. Ownership is transferred to MList.

See also:: MCellCreator

Definition at line 202 of file mlist.cpp.

{
    model()->setHeaderCreator(headerCreator);
}

Here is the call graph for this function:

void MList::setIndexDisplayMode ( MList::DisplayMode displayMode ) [slot]

Specifies fi the list index bar for a grouped model should be visible or not, or automatically to appear on list panning.

See also:: MList::DisplayMode

Definition at line 240 of file mlist.cpp.

{
    model()->setListIndexDisplayMode(displayMode);

    if(displayMode == MList::Hide)
        model()->setListIndexVisible(false);
    else
        model()->setListIndexVisible(true);
}

Here is the call graph for this function:

void MList::setIndexVisible ( bool visible ) [slot]

Specifies whether the list index for a grouped model should be visible or not.

Deprecated:: Please use setIndexDisplayMode(MList::DisplayMode);

Definition at line 232 of file mlist.cpp.

{
    if (visible)
        setIndexDisplayMode(MList::Show);
    else
        setIndexDisplayMode(MList::Hide);
}

Here is the call graph for this function:

void MList::setItemModel ( QAbstractItemModel * itemModel )

Sets object to fetch displayed items from. Similar to 'setModel' method in QListView.

Sets the model for the view to present. This function will create and set a new selection model, replacing any model that was previously set with setSelectionModel(). However, the old selection model will not be deleted as it may be shared between several views. We recommend that you delete the old selection model if it is no longer required. This is done with the following code:

        QItemSelectionModel *m = view->selectionModel();
        view->setModel(new model);
        delete m;

If both the old model and the old selection model do not have parents, or if their parents are long-lived objects, it may be preferable to call their deleteLater() functions to explicitly delete them.

MList does not take ownership of the model unless it is the model's parent object because the view may be shared between many different MList(s).

Definition at line 103 of file mlist.cpp.

{
    Q_D(MList);
    if (d->listFilter && d->listFilter->enabled())
        itemModel = d->listFilter->updateItemModel(itemModel);

    setSelectionModel(NULL);

    if (itemModel)
        setSelectionModel(new QItemSelectionModel(itemModel));

    model()->setItemModel(itemModel);
}

Here is the call graph for this function:

void MList::setOptimizationFlag	(	ListOptimizationFlag	optimizationFlag,
		bool	enabled = `true`
	)

Sets one optimization flag to enabled if enabled is true, otherwise to disabled.

Definition at line 331 of file mlist.cpp.

{
    Q_D(MList);
    if (enabled)
        setOptimizationFlags(ListOptimizationFlags(d->optimizationFlags) | optimizationFlag);
    else
        setOptimizationFlags(ListOptimizationFlags(d->optimizationFlags) & ~optimizationFlag);
}

Here is the call graph for this function:

void MList::setOptimizationFlags ( ListOptimizationFlags optimizationFlags )

Sets the list optimization flags to flags. All flags in flags are enabled and the others are disabled.

Definition at line 340 of file mlist.cpp.

{
    Q_D(MList);
    d->optimizationFlags = optimizationFlags;
}

void MList::setSelectionMode ( MList::SelectionMode mode )

Sets selection mode. By default NoSelection is set. Check SelectionMode enumeration for details.

Definition at line 270 of file mlist.cpp.

{
    Q_D(MList);
    d->selectionMode = mode;

    QItemSelectionModel *sModel = selectionModel();

    if (sModel)
        sModel->clearSelection();
}

Here is the call graph for this function:

void MList::setSelectionModel ( QItemSelectionModel * selectionModel )

Sets selection model.

Definition at line 143 of file mlist.cpp.

{
    if (selectionModel == this->selectionModel()) {
        return;
    }

    model()->setSelectionModel(selectionModel);
    emit selectionModelChanged(selectionModel);
}

Here is the call graph for this function:

void MList::setShowGroups ( bool showGroups )

Specifies whether list should show groups or not.

MList will handle item model as a 2 level tree. First level will be headers and second level items for that header.

Customization of the group header's appearance in the list is done through group-header-object-name. Group header is a label, so all styles of label applies to group header. Example: Application.css

      MList#customList
      {
        group-header-object-name : "redLabelOnWhiteBackground";
      }

      #redLabelOnWhiteBackground
      {
        color : #FF0000;
        background-color : #FFFFFF;
      }

Application.cpp

      MList * list = ....;
      ...
      list->setObjectName("customList");
      ...

Definition at line 227 of file mlist.cpp.

{
    model()->setShowGroups(showGroups);
}

Here is the call graph for this function:

bool MList::showGroups ( ) const

Returns:: true if MList shows groups, otherwise false

void MList::updateData ( const QList< const char * > & modifications ) [protected, virtual]

Notification of model data modifications.

Reimplemented from MWidgetController.

Definition at line 87 of file mlist.cpp.

{
    const char *member;
    for (int i = 0; i < modifications.count(); i++) {
        member = modifications[i];
        if (member == MListModel::ListIsMoving) {
            model()->listIsMoving() ? emit panningStarted() : emit panningStopped();
        }
    }
}

Here is the call graph for this function:

Property Documentation

int MList::columns [read, write]

Definition at line 140 of file corelib/widgets/mlist.h.

MList::SelectionMode MList::selectionMode [read, write]

Definition at line 145 of file corelib/widgets/mlist.h.

bool MList::showGroups [read, write]

Definition at line 135 of file corelib/widgets/mlist.h.

MList Class Reference

Public Types

Public Slots

Signals

Public Member Functions

Protected Member Functions

Properties

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Property Documentation