Home · All Classes · Main Classes · Deprecated
Public Types | Public Slots | Signals | Public Member Functions | Protected Member Functions | Properties

MList Class Reference

MList implements a list view. More...

Inherits MWidgetController.

List of all members.

Public Types

enum  SelectionMode { NoSelection, SingleSelection, MultiSelection }
enum  ScrollHint { EnsureVisibleHint, PositionAtTopHint, PositionAtBottomHint, PositionAtCenterHint }
enum  DisplayMode { Hide = 0, Show, Auto, Floating }
enum  AnimationMode { NonAnimated = 0, Animated = 1 }
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, AnimationMode mode)
void scrollTo (const QModelIndex &index, ScrollHint hint)
void scrollTo (const QModelIndex &index, ScrollHint hint, AnimationMode mode)
void setIndexVisible (bool visible)
void setIndexDisplayMode (DisplayMode displayMode)
void setIndexMagnifierDataRole (int role)
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 ()
void indexScrollStarted ()
void indexScrollEnded ()

Public Member Functions

 MList (QGraphicsItem *parent=0)
virtual ~MList ()
void setItemModel (QAbstractItemModel *itemModel)
QAbstractItemModelitemModel () const
void setCellCreator (MCellCreator *cellCreator)
const MCellCreatorcellCreator () const
void setHeaderCreator (MCellCreator *cellCreator)
const MCellCreatorheaderCreator () const
void setColumns (int columns)
int columns () const
QItemSelectionModelselectionModel () 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 ()
MListFilterfiltering () const
ListOptimizationFlags optimizationFlags () const
void setOptimizationFlag (ListOptimizationFlag optimizationFlag, bool enabled=true)
void setOptimizationFlags (ListOptimizationFlags optimizationFlags)
int indexMagnifierDataRole () const

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 its 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);

See also MListView, MWidgetFactory.


Member Enumeration Documentation

Enumerator:
NonAnimated 

The method shall be not animated.

Animated 

The method shall be animated.

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. Group titles are displayed on the list index rail, when user performs the panning gesture on it's reactive area.

Floating 

Same as Auto, but group titles are not displayed on list index rail in this case.

Enumerator:
DontCallCreateCellDuringUpdate 

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

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.

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.


Constructor & Destructor Documentation

MList::MList ( QGraphicsItem parent = 0  ) 

Constructor for creating an empty object.

Parameters:
parent Parent object.
MList::~MList (  )  [virtual]

Destructor.

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

Member Function Documentation

const MCellCreator * MList::cellCreator (  )  const

Returns cell creator associated with MList

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

Handler of notifications of new receivers connected to MList signals.

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

Notification of context menu event.

Reimplemented from MWidget.

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

Handler of notifications of receivers disconnecting from MList signals.

MListFilter * MList::filtering (  )  const
Returns:
filter which implements live filtering of list contents.
const QModelIndex MList::firstVisibleItem (  )  const
Returns:
index of first visible item
const MCellCreator * MList::headerCreator (  )  const

Returns header creator associated with MList

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

Returns visibility mode of list index.

See also:
MList::DisplayMode
int MList::indexMagnifierDataRole (  )  const
Returns:
Data role of the title in the list index magnifier.
void MList::indexScrollEnded (  )  [signal]

Emitted when index scrolling ends.

void MList::indexScrollStarted (  )  [signal]

Emitted when index scrolling is started.

bool MList::indexVisible (  ) 
Returns:
Returns the status of the list index availability.
Deprecated:
Please use indexDisplayMode()
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.

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

Handling of key events

const QModelIndex MList::lastVisibleItem (  )  const
Returns:
index of last visible item
void MList::longTapItem ( const QModelIndex index  )  [slot]

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

Deprecated:
Use MList::longTapItem(QModelIndex, QPointF) instead.
void MList::longTapItem ( const QModelIndex index,
const QPointF position 
) [slot]

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

MList::ListOptimizationFlags MList::optimizationFlags (  )  const
Returns:
list's optimization flags.
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.

Deprecated:
Please use the MList::scrollTo(QModelIndex, AnimationMode).
void MList::scrollTo ( const QModelIndex index,
AnimationMode  mode 
) [slot]

Scrolls list to a specific index. Call to function will ensure that item with specified index becomes visible. The scroll to might be executed animated or non-animated.

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

Scrolls list to a specific index with specified hint.

Deprecated:
Please use the MList::scrollTo(QModelIndex, ScrollHint, AnimationMode).
void MList::scrollTo ( const QModelIndex index,
ScrollHint  hint,
AnimationMode  mode 
) [slot]

Scrolls list to a specific index with specified hint. The method is executed either animated or non-animated.

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.

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.

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

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
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
void MList::setIndexMagnifierDataRole ( int  role  )  [slot]

Specifies the data role for the title in the list index magnifier.

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);
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).

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

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

void MList::setOptimizationFlags ( ListOptimizationFlags  optimizationFlags  ) 

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

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

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

void MList::setSelectionModel ( QItemSelectionModel selectionModel  ) 

Sets selection model.

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");
      ...
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.


Property Documentation

int MList::columns [read, write]
MList::SelectionMode MList::selectionMode [read, write]
bool MList::showGroups [read, write]

Copyright © 2010 Nokia Corporation
MeeGo Touch