47     \brief HbDataFormViewItem represents an item view in HbDataForm corresponding to model item.

    48     

    48     Each HbDataFormModelItem added inside model is represented using HbDataFormViewItem instance.

    49     \brief The HbDataFormViewItem class is for representing the visual appearence of the data in a data form model item.

    50     HbDataFormViewItem have different visualization based upon the 

    51     An HbDataForm object contains HbDataFormViewItem objects. To add a custom widget to a form create a subclass of HbDataFormViewItem class.

    51     HbDataFormModelItem::DataItemType:

    52 

    53     - FormPageItem: This type does not have any visualization. Whatever QString is passed while

    54         creating HbDataFormModelItem, is added in a combo box at the top level view. User can 

    55         switch between different form page using this combo.

    56     - GroupItem: A visualization is created for this type. Visualization includes +/- icon and 

    57         group heading. User can expand and collapse the group by clicking any where in 

    58         HbDataFormViewItem of this type. Whatever QString is passed while creating

    59         HbDataFormModelItem for this type is set as a group heading.

    60     - GroupPageItem: This type does not have any visualization. Whatever QString is passed while

    61         creating HbDataFormModelItem, is added in a group combo box. User can switch between 

    62         different group page using this combo.

    63     - DataItems: Any type other then FormPageItem, GroupItem and GroupPageItem is treated as

    64         a data item. Data item can contain label, description, icon and content widget. Data items

    65         can not have any children. They are always placed at the leaf. Data item content widget 

    66         can be set using HbDataFormModelItem::ItemTypeRole, label of data items can be set using 

    67         HbDataFormModelItem::LabelRole, description of data item can be set using 

    68         HbDataFormModelItem::DescriptionRole.

    70     If HbDataFormViewItem represents a GroupItem then it can be expanded and collapsed. 

    53     HbDataFormViewItem object's appearance and functionality depends on the value of HbDataFormModelItem::DataItemType as follows:

    71     If group is expanded then all the child items are shown.

    54     - FormPageItem

    72 

    55       - When creating the HbDataFormModelItem object, the text of constructor's QString parameter will be the item's visible text in the combo box which lists available form pages.

    73     If user wants to create a custom data item then he has to derive from this class and set that

    56       - The user can select a form page from the combo box which lists available form pages.

    74     as a prototype for HbDataForm using HbAbstractItemView::setItemPrototype API. While creating

    57       - The combo box is the only visible element of FormPageItem.

    75     data for custom data items user should pass value greater than or equal to 

    58     - GroupItem

    76     DataItemType::CustomItemBase. When visualization is created and if data item type is

    59       - Visible element has a group title and an icon which is

    77     custom item then createCustomWidget() is called. User has to override this API and pass the

    60           - a plus sign (+) when the user can expand the group, i.e. all the child items are shown.

    78     custom widget which he wants to show in data item. Below is the code snippet:

    61           - a minus sign (-) when the user can collapse the group, i.e. all the child items are hidden.

    62       - User can expand and collapse the group by clicking anywhere in the group title bar.

    63       - When creating the HbDataFormModelItem object, the text of constructor's QString parameter will be the group title.

    64     - GroupPageItem

    65       - When creating the HbDataFormModelItem object, the text of constructor's QString parameter will be the item's visible text in the combo box which lists available group pages.

    66       - The user can select a group page from the group page combo box.

    67       - The combo box is the only visible element of GroupPageItem.

    68       - The HbAbstractItemView::activated() signal is emitted when a group page item is clicked.

    69     - DataItem

    70       - If the HbDataFormModelItem::DataItemType parameter's value is not FormPageItem, GroupItem or GroupPageItem, it is treated as a data item.

    71       - Contains

    72         - a label which you can set with HbDataFormModelItem::LabelRole.

    73         - a content widget which you can set with HbDataFormModelItem::ItemTypeRole.

    74         - a description which you can set with HbDataFormModelItem::DescriptionRole.

    75         - an icon which you can set with HbDataFormModelItem::setIcon().

    76 

    77       - %Data item cannot have a child, i.e. it is always the leaf of the structure.  

    78     

    79     \section _usecases_hbdataformviewitem Using the HbDataFormViewItem class

    80     

    81     \subsection _uc_hbdataformviewitem_001 Creating a custom data item.

    82 

    83     The code snippet below shows how you can create a custom data item. To create a custom data item object of (in this example) the DataFormCustomItem class, derive it from the HbDataFormViewItem class and set the prototype for HbDataForm with HbAbstractItemView::setItemPrototype() method. When creating data for custom data items pass a value greater than or equal to DataItemType::CustomItemBase. When visual appearance is created and if data item type is custom data item then createCustomWidget() is called. You must override this method and pass the custom widget which you want to show in the data item.

   136     The signals emitted by this class are:

   141     The signal emitted by this class is:

   137     \li itemShown(const QModelIndex&) This signal is emitted when ever this item becomes visible.

   142     \li itemShown(const QModelIndex&) signal is emitted whenever this item becomes visible.

   138     

   143 

   139     Refer HbDataForm documentation for sample code.

   144     See HbDataForm for sample code.

   144 /*!

   149 

   145     Constructs HbDataFormViewItem with given \a parent.

   150 /*!

   146     \param parent parent .

   151     Constructs a data form view item with the given \a parent.

   156     Destructs the HbDataFormViewItem.

   161     Destructor.

   163     \reimp

   168     Creates a data form view item. This method is called to form an HbAbstractItemContainer object when the model is parsed for creating items.

   164     Creates HbDataFormViewItem. This function is called from HbAbstractItemContainer 

   165     when model is getting parsed for creating items. 

   172 /*!

   175 

   173     \reimp

   176 /*!

   174     Returns true if \a model index is supported by HbDataFormViewItem prototype, otherwise returns false.

   177     Returns \c true if the given model \a index is supported by the data form view item, otherwise returns \c false. This method is called for every item on the prototype list until an item which can create a list view item for \a index, is found. The method goes through the prototype list from the end to the beginning. 

   175     This function is called for every item on the prototype list (if several prototypes exist)

   178     

   176     until item is found, which can create view item for \a index.

   179     \sa HbAbstractItemView::setItemPrototype(HbAbstractViewItem *prototype) and HbAbstractItemView::setItemPrototypes(const QList<HbAbstractViewItem *> &prototypes)

   177 

   178     \sa HbAbstractItemView::setItemPrototype(HbAbstractViewItem *prototype)

   179     \sa HbAbstractItemView::setItemPrototype(const QList<HbAbstractViewItem *> &prototypes)

   197     \reimp

   197     Updates child graphics items to represent current state and content. In case HbDataFormViewItem represents data item and DataItemType is set to custom item, createCustomWidget is called. You can override createCustomWidget and can pass your own custom widget.

   198     Updates child graphics items to represent current state and content stored in model. In case when 

   199     HbDataFormViewItem represents data item and DataItemType is set to custom item, then 

   200     createCustomWidget is called. User can override createCustomWidget and can pass his own

   201     custom widget.

   248         style()->updatePrimitive(

   244         HbStylePrivate::updatePrimitive(

   249             d->mBackgroundItem, HbStyle::P_DataItem_background, &options );

   245             d->mBackgroundItem, HbStylePrivate::P_DataItem_background, &options );

   250     }

   246     }

   251 

   247 

   252 }

   248 }

   253 

   249 

   254 /*!

   250 /*!

   255     \protected constructor

   251     \protected Constructs a data form view item with the given protected class object \a dd and \a parent.

   266     \protected constructor

   262     \protected Constructs a data form view item with the given protected class object \a source.

   291     The content widget property for restoring and saving the data need to be initialized when the 

   286     The property for restoring and saving the data need to be initialized when the data item is created. If the model item type is custom, then you must override this method to get a notification when the data is changed in the model.

   292     data item is created. If model item type is custom, then application developer has to override

   293     this API in order to get notification when data is changed in model.

   345 

   338     Saves the current data of the content widget in data item to the model .

   346     Saves the current data of the content widget in data item to the model.

   339     The property for restoring and saving the data need to be initialized when the data item is created. If the model item type is custom, then you must override this API in order to save the content widget value into the model.

   347     The property for restoring and saving the data need to be initialized when the 

   348     data item is created. If model item type is custom, then application developer has to override

   349     this API in order to save the content widget value in model.

   374     This is a virtual function which by default returns NULL. This function must be overridden

   364     This is a virtual method which returns NULL by default. To create a data item of the custom widget type override this method. Pass the widget which you want to be shown in the data item. If the content widget has requested to receive pan gesture events using QGraphicsObject::grabGesture(), then any scrolling is recognized as a pan gesture and is always sent to the content widget, even when the content widget is disabled. If you want the data form to be scrollable even when the content widget is disabled, you need to call QGraphicsObject::ungrabGesture() while the content widget is disabled, and grab pan gestures again when the content widget is later enabled.

   375     in case user wants to create a data item of type custom item. The user is supposed to pass

   376     the widget which he wants to display in data item.

   377     If content widget grabs pan gesture and user wants data form to be scrollable even panning

   378     is done on disabled content widget then user is supposed to ungrab pan gesture when content 

   379     widget is disabled. And again grab pan gesture when state of content widget is changed to 

   380     enabled.

   388     \reimp 

   372     Sets the item to either collapse or expanded, depending on the value of \a expanded.

   389     Sets the item to either collapse or expanded state, depending on the value of \a expanded.

   373     The function calls setModelIndexes which in turn will make the child items visible or invisible accordingly. This method is valid only if HbDataFormViewItem represents FormPageItem, GroupItem or GroupPageItem.

   390     The function calls setModelIndexes which inturn will make the child items visible/invisible 

   391     accordingly. This API is valid only if HbDataFormViewItem represents a FormPageItem, GroupItem

   392     or GroupPageItem.

   435 /*!

   415 

   436     @beta

   416 /*!

   437 

   417     This method is valid only if the data form view item represents a data item. The method returns the content widget of data item. For example, if the type of data item is SliderItem then this method will return the HbSlider content widget object. 

   438     Returns the content widget of data item. For example if data item is of type SliderItem 

   418     

   439     then this API will return the instance of HbSlider. If user wants to connect to some 

   419     You can use this method to retrieve the widget object of a data item for connecting its signals to appropriate slot. It returns the object only if the data item is visible. You can query the content widget with this method when the item is visible and connect the HbDataForm::activated() signal to an appropriate slot.

   440     signals of content widget in data item then this API can be used to fetch the instance

   441     of the widget. It will return the instance only if data item is visible. User can connect

   442     to HbDataForm::itemShown() signal and when this item is visible then he can query the 

   443     content widget using this API.

   520                 style()->updatePrimitive(

   496                 HbStylePrivate::updatePrimitive(

   521                 d->mBackgroundItem, HbStyle::P_DataItem_background, &options );

   497                 d->mBackgroundItem, HbStylePrivate::P_DataItem_background, &options );