46     \brief HbListWidget represents a list

    46     \brief The HbListWidget class is for simple lists consisting of single row items of an icon and some text, and together with HbListWidgetItem consisting of icon and at most two-row text items.

    47 

    47 

    48     This class has been provided with the class HbListWidgetItem as a convenience

    48     

    49     API. It provides an item-based interface for adding and removing items. 

    49     HbListWidget provides a convenience API for adding, modifying, and removing single row items in simple lists. Single row items consist of some text and an icon in one line. If you want list items with two texts or two icons, that is, with multirow items, then you can create HbListWidgetItem objects and add them to an HbListWidget. See HbListWidgetItem for the detailed description of the multirow item. 

    50 

    50 

    51     SetModel() function of the base class HbListView cannot be used. If the user wants to start 

    51      HbListWidget model supports arranging items with drag and drop.

    52     using a list view with e.g. a directory model (QDirModel) this convenience API cannot be used.

    52      

    53     

    53      \link HbAbstractItemView::setModel(QAbstractItemModel *model, HbAbstractViewItem *prototype=0) SetModel()\endlink method of the base class HbAbstractItemView cannot be used. HbListWidget cannot be used for list views with a directory model (QDirModel), for example.

    54     HbListWidget can be used without HbListWidgetItem to populate 

    54     

    55     simple list with single row items consisting of a text and an icon. 

    55     \section _usecases_hblistwidget Using the HbListWidget class

    56 

    56     

    57     If multirow items are needed the HbListWidgetItem must be used.

    57     \subsection _uc_hblistwidget_001 Creating a list and adding one single row item into it.

    58 

    58     

    59     The following code snippet first creates a list and then adds one item which contains some text and an icon to the list.

    60    

    61     See HbListWidgetItem for more usage examples.

    63     \sa HbListWidgetItem, HbListView for more use cases.

    62 

    63     \sa HbListWidgetItem, HbListView 

    69     This signal is emitted when a list item is pressed.

    69     This signal is emitted when the user presses an item in the list. \a item indicates the pressed item.

    70     The pressed item is specified by \a item.

    70 

    71 

    71     \sa released(), longPressed(), activated()

    72     See also released(), longPressed() and activated().

    78     This signal is emitted when a list item is no more pressed.

    77     This signal is emitted when when release event occurs for \a item.

    79     The released item is specified by \a item.

    78 

    80 

    79     \sa pressed(), longPressed(), activated()

    81     See also pressed(), longPressed() and activated().

    80     \sa HbAbstractViewItem::released(const QPointF &position)

    86 

    85     

    87     This signal is emitted when the item specified by \a item is activated by the user.

    86     This signal is emitted when the user activates an item in the list. \a item indicates the activated item. The activation of the item depends on the input method. An item can be activated in the following ways:

    88     How to activate items depends on the input method; e.g., with mouse by clicking the item,

    87     - by clicking the item with a mouse

    89     or with touch input by tapping the item, or with hardware keys by pressing the Return

    88     - by tapping the item on a touch screen

    90     or Enter key when the item is current, or with soft keys by pressing choosing "Select"

    89     - by pressing Return or Enter hardware keys when the item has focus

    91     when the item is current.

    90     - by pressing Select soft key when the item has focus

    92 

    91     

    93     See also pressed(), released() and longPressed().

    92     \sa pressed(), released(), longPressed()

    99     This signal is emitted when a list item is long pressed.

    98     This signal is emitted when the user presses an item in the list for a long time. \a item indicates the activated item and \a coords the screen position where the long press happened.

   100     The pressed item is specified by \a item and \a coords.

    99 

   101     See also pressed(), released() and activated().

   100     \sa pressed(), released(), activated()

   106  */

   105 */

   122     Destructs the list view.

   121     Destructor.

   123  */ 

   122 */ 

   129     Returns the total number of rows.

   128     Returns the total number of rows in the list.

   137     Returns the current row number

   136     Returns the current row number in the list. A current row is a row having focus.

   138  */

   137 */

   145    Sets current \a row. This function sets current index into selection model. 

   144     Sets the current row to \a row. A current row is a row having focus.

   146    Selection is never changed.

   145     

   147  */

   146     \sa currentRow()

   147 */

   155     Returns a pointer to the current HbListWidgetItem. 

   155     Returns a pointer to the current list item.  A current list item is a list item having focus.

   156     Ownership not transferred to the caller.

   156     Ownership is not transferred so the item should not be deleted by the caller.

   157     Should not be deleted by the caller.

   157     

   158  */

   158     \sa currentRow()

   159 */

   166     Sets the current item to item.

   167     Sets the current item to \a item. A current item is an item having focus.

   167  */

   168 */

   174     Returns a pointer to an item specified by \a row.

   175     Returns a pointer to the list item specified by \a row.

   175     Ownership not transferred to the caller.

   176     Ownership is not transferred to the caller so the item should not be deleted by the caller.

   176     Should not be deleted by the caller.

   177 */

   177  */

   185     Creates new one row item based on a string and an icon and append it to the end of the list.

   185     Creates a single row item specified by \a icon and \a text and appends it to the end of the list.

   186  */

   186 */

   198     Creates new one row item based on a string and append it to the end of the list.

   198     Creates a new single row item spcified by \a text and appends it to the end of the list.

   199  */ 

   199 */ 

   210    Appends an item created by the user to the end of the list.

   210    Appends \a item to the end of the list.

   211  */

   211 */

   222     Creates a new item based on the string and an icon into a specified location in the list            

   222     Creates a list widget item with \a icon and \a text and inserts it into the list at the \a row location. Regarding \a row the following rules apply:

   223  */

   223     - if \a row is negative the item is inserted into the first row

   224     - if \a row is greater than the number of list's items the item is added at the last item

   225 */

   236     Creates a new item based on the string into a specified location in the list.

   238     Creates a list widget item with \a text and inserts it into the list at the \a row location. Regarding \a row the following rules apply:

   237  */

   239     - if \a row is negative the item is inserted into the first row

   240     - if \a row is greater than the number of list's items the item is added at the last item

   241 */

   249    Inserts an item created by the user to the specified place on the list.

   253     Creates a list widget item with \a item and inserts it into the list at the \a row location. Regarding \a row the following rules apply:

   250  */

   254     - if \a row is negative the item is inserted into the first row

   255     - if \a row is greater than the number of list's items the item is added at the last item

   256 */

   261     Deletes every item in the list     

   267     Deletes all the items in the list.     

   262  */

   268 */

   273     Returns the row containing the given item.

   279     Returns the row number of given \a item.

   274  */

   280 */

   283     \reimp

   289     This method cannot be used. If you call it in debug builds you will get an ASSERT failure i.e. Q_ASSERT_X(). In release builds nothing will happen.

   284 

   285     Setting own model to HbListWidget is not allowed.

   296     Set the text for a simple one row item or the first text row for a 

   300     Replaces the text on the given \a row with the given \a text. Only the text is replaced, the icon stays unchanged. In case of a multi-row only the first text row is replaced. Use HbListWidgetItem to modify multirow items.

   297     multi row item. Only the text is replaced, no icon removed. 

   301     

   298     Use HbListWidgetItem to modify multirow items.

   302     \param text - Text to be shown in the list widget item.

   303     \param row - Row of the list widget item.

   304     

   309     Set the icon for a simple one row item or the first icon for a 

   315     Replaces the icon on the given \a row with the given \a icon. Only the icon is replaced, the text stays unchanged. The item can be a single row or a multirow item. Use HbListWidgetItem to modify multirow items.

   310     multi row item. Only the icon is replaced, no text removed.

   316     

   311     Use HbListWidgetItem to modify multirow items.

   317     \param icon - Icon to be shown in the list widget item.

   318     \param row - Row of the list widget item.

   322     Removes and returns the item from the given row in the list widget; otherwise returns 0.

   329     Returns the list widget item of given row and then removes the item from the list. Items removed from a list must be deleted manually.

   323     Items removed from a list widget will not be managed, and will need to be deleted manually.   

   330     

   324     Use this function to remove items form the list.    

   331     \param row - Row to be removed. 

   332 

   333     \return

   334     - The list widget item of \a row if it exists in the list.

   335     - 0, if \a row doesn't exist in the list.

   336     HbListWidget model supports arranging items with drag and drop, so 

   347     HbListWidget supports arranging items with drag and drop. If \a arrangeMode is \c true and the list is not in the selection mode, the list is put into the arrange list mode which allows the user to rearrange the list by dragging and dropping items. If \a arrangeMode is \c false, then the arrange list mode is cancelled. 

   337     this method returns true unless the widget is in some selection mode. 

   348     

   349     The list can be in either arrange or selection mode but not in both modes at any given time.

   350     

   351     \return

   352     - \c True if the arrange list mode is successfully set according to \a arrangeMode. This includes the case where the requested \a arrangeMode is the same as what was already set for the list.

   353     - \c False if the requested \a arrangeMode cannot be set.   

   344         if (arrangeMode == true) {

   360         if (d->mSelectionMode != HbAbstractItemView::NoSelection) {

   345             if (d->mSelectionMode != HbAbstractItemView::NoSelection) {

   361             return false;

   346                 return false;

   347             }

   348             verticalScrollBar()->setInteractive(true);

   349         } else {

   350             verticalScrollBar()->setInteractive(false);

   352 

   363         d->arrangeModeSetup(arrangeMode);

   353         d->mArrangeMode = arrangeMode;

   354         d->mAnimateItems = !d->mArrangeMode;

   355 

   356         if (d->mArrangeMode == true) {

   357             d->mOriginalFriction = d->mFrictionEnabled;

   358             setFrictionEnabled(false);

   359         } else {

   360             setFrictionEnabled(d->mOriginalFriction);

   361         }

   387  */

   395 */