47     \brief HbDataForm represents hierarchical dataitems in form of form pages, groups, group pages

    47 

    48     and data items.

    48     \brief The HbDataForm class is for showing and entering data in 

    49     HbDataForm implements a hierarchical representation of view items for each model items from 

    49     hierarchically organized pages and groups of a form.

    50     HbDataFormModel.

    50 

    51 

    51     A data form contains data items for showing and entering data in an 

    52     HbDataForm implements the interfaces defined by the HbAbstractItemView class to allow 

    52     application. Each data item shown in a data form can contain an input widget 

    53     it to display data provided by models which are derived from QAbstractItemModel class.

    53     and an optional text label. Text fields, sliders and check boxes are typical 

    54 

    54     widgets used to show and collect data in an application. If a complex data 

    55     It is simple to construct a dataform displaying data from a model. The user has to create

    55     form contains many data items a user may be required to scroll the data form 

    56     HbDataFormModel and create the hierarchy of HbDataFormModelItems.The hierarchy is 

    56     content. To reduce the need to scroll, the data items can be organised into 

    57     similar to the following.

    57     elements whose hierarchy is the following:

    58     

    58     -  %Data form

    59     - HbDataForm

    59       - Form pages

    60        - HbDataFormPage1

    60         - Groups

    61          - HbDataGroup1

    61           - Group pages

    62            - HbDataGroupPage1

    62 

    63              - HbDataItem

    63     The data form uses a model-view architecture. HbDataFormModel represents the 

    64              - HbDataItem

    64     data model for the form. You add HbDataFormModelItem objects (i.e. form 

    65              - HbDataItem

    65     pages, groups, group pages and data items) to a data form model by creating 

    66              - HbDataItem

    66     a HbDataFormModel object and adding HbDataFormModelItem objects to it. You 

    67        - HbDataFormPage2

    67     can then create a data form widget to show the data by creating an 

    68          - HbDataGroup2

    68     HbDataForm object and setting its data form model. The model-view 

    69            - HbDataGroupPage2

    69     architecture ensures that the content of the data form view is updated as 

    70              - HbDataItem

    70     the data form model changes.

    71              - HbDataItem

    71 

    72              - HbDataItem

    72     The important thing to note is that you do not create data form widgets 

    73              - HbDataItem

    73     directly in your data form. The HbDataForm object creates the appropriate UI 

    74        - HbDataGroup3

    74     widget type for each data item in your data form model. You must specify the 

    75           - HbDataItem

    75     type of widget that is shown in the data form when you create your data form 

    76           - HbDataItem

    76     model.

    77           - HbDataItem

    77 

    78        - HbDataItem

    78     HbDataForm implements the interface defined by the HbAbstractItemView class 

    79        - HbDataItem

    79     to display the data provided by the data form model. This model is derived 

    80  

    80     from the QAbstractItemModel class. To construct a data form for displaying 

    81     HbDataItem can be the child of HbDataForm, HbDataFormPage, HbDataGroup and 

    81     the data from a data form model, create HbDataFormModel and the hierarchy of 

    82     HbDataGroupPage. An instance of HbDataForm has to be created and model should be set 

    82     HbDataFormModelItem objects. The following rules apply in the hierarchy:

    83     to the form using setModel( ) API.

    83     - A form page can be a child of the data form only.

    84     The properties of each data item node can be set using HbDataFormModelItem convenient

    84     - A group can be a child of the data form or a form page.

    85     API's like setContentWidgetData( ). These model data are parsed and set while the visualization 

    85     - A group page can be a child of a group only.

    86     instance of each item is created.

    86     - A data item can be the child of data form, form page, group, and group page.

    87 

    87 

    88     The model/view architecture ensures that the view contents are updated as and when the data in

    88     The hierarchy can be for example the following:

    89     model changes.

    89     

    90 

    90     - %Data form

    91     Only model items that can have children can be in expanded (childrens are visible) or 

    91        - Form page 1

    92     collapsed (childrens are hidden) state. Model items of type HbDataFormModelItem::FormPageItem,

    92          - Group 1

    93     HbDataFormModelItem::GroupItem and HbDataFormModelItem::GroupPageItem can be expanded 

    93            - Group page 1

    94     or collapsed. Which in turn means that these types of model item can only have children. 

    94              - %Data item 1

    95     Each item in model is represented by either an instance of HbDataFormViewItem or classes which 

    95              - %Data item 2

    96     are derived from HbDataFormViewItem. HbDataFormViewItem can be subclassed for

    96              - %Data item 3

    97        - %Data item 4

    98        - Form page 2

    99          - %Data item 5

   100          - Group 2

   101            - %Data item 6

   102            - Group page 2

   103              - %Data item 7

   104              - %Data item 8

   105        - Group 3

   106          - %Data item 9

   107 

   108     To build the structure create first the HbDataForm object and set the model 

   109     to the form with the setModel() method. Set properties of each data item 

   110     with methods of HbDataFormModelItem class. The data is parsed when the 

   111     visualization instance of each item is created and set on each item.

   112 

   113     Items which have children (i.e. form pages, groups, and group pages) can be 

   114     in expanded (i.e. children are visible) or collapsed (i.e. children are 

   115     hidden) state. Each item in data form model is represented by an 

   116     HbDataFormViewItem object. HbDataForm uses HbDataFormViewItem prototype to 

   117     instantiate the data form items. HbDataFormViewItem can be subclassed for 

    98     

   119 

    99     The Model hierarchy can be created using the convenient API's provided in model class like

   120     The signals emitted by HbDataForm are the following:

   100     appendDataFormPage(), appendDataFormGroup(), appendDataFormGroupPage() and 

   121     \li itemShown(const QModelIndex &index) signal is emitted when the 

   101     appendDataFormItem(). All these API's return HbDataFormModelItem instance corresponding 

   122     HbDataFormViewItem corresponding to \a index is shown. You can connect to 

   102     to each HbDataFormModelItem::DataItemType type on which user can set item 

   123     this signal and fetch the instance of HbDataFormViewItem from HbDataForm 

   103     specific(content widget) data. Otherwise each HbDataFormModelItem can be created individually

   124     with HbAbstractItemView::itemByIndex().

   104     by passing the corresponding type of item (GroupItem, GroupPageItem, FormPageItem) and create

   125     \li dataChanged(const QModelIndex &topLeft, const QModelIndex &bottomRight) 

   105     the tree of HbDataFormModelItem using setParent API or by passing the parent 

   126     signal is emitted when the HbDataFormModel is updated \a topLeft and \a 

   106     HbDataFormModelItem in constructor. Later the top level HbDataFormModelItem can be added in 

   127     bottomRight will be same since every node has only one column. You can 

   107     model.

   128     connect to this signal and fetch the instance of

   108 

   129     - HbDataFormViewItem from HbDataForm with HbAbstractItemView::itemByIndex() or

   109     After setting model in HbDataForm using setModel(), the visualization gets created.

   130     - HbDataFormModelItem with HbDataFormModel::itemFromIndex(). HbDataForm 

   110     Only the items inside the expanded form page, group or group page are created. When an item's

   131     takes care of updating the corresponding the visualization of item when you 

   111     visualization is created, HbDataForm emits itemShown(constQModelIndex&) signal. The application 

   132     update the model with HbDataFormModelItem::setContentWidgetData().

   112     can connect to this signal and when corresponding slot is called then application can get

   133 

   113     HbDataFormViewItem instance and even content widget instance. Use HbAbstractItemView::itemByIndex()

   134     You can also provide the connection information to the corresponding content 

   114     to get HbDataFormViewItem instance. Use HbDataFormViewItem::dataItemContentWidget() to get

   135     widget of each HbDataFormModelItem with the \link HbDataForm::addConnection(HbDataFormModelItem * item, const char* signal, QObject *receiver, const char* slot) HbDataForm::addConnection()\endlink 

   115     content widget instance.

   136     method. The connection is established when the item visualization is 

   116     

   137     created. You can use \link HbDataForm::removeConnection(HbDataFormModelItem *item, const char* signal, QObject *receiver, const char* slot) HbDataForm::removeConnection()\endlink and HbDataForm::removeAllConnection() 

   117     The signals emitted by HbDataForm

   138     methods in the same way. You can establish and remove the connection also at 

   118     \li itemShown(const QModelIndex &index) Emitted when the HbDataFormViewItem corresponding to

   139     runtime.

   119     \a index is shown. User can connect to this signal and can fetch the instance of 

   140 

   120     HbDataFormViewItem from HbDataForm using the API dataFormViewItem(const QModelIndex &index).

   141     \sa HbDataFormViewItem, HbDataFormModel, and HbDataFormModelItem

   121     This signal is only emitted for model items of type greater than HbDataFormModelItem::GroupPageItem

   142     

   122 

   143     \section _usecases_hbdataform Using the HbDataForm class

   123     The user can also provide connection information to correspoding content widget of each 

   144     

   124     HbDataFormModelItem using API 

   145     \subsection _uc_hbdataform_001 Creating a data form.

   125     addConnection(HbDataFormModelItem* item, const char* signal, QObject* receiver, const char* slot)

   146     

   126     provided in HbDataForm. The connection will be established when the item visualization is created.

   147     The following example shows how to create a data form. The code

   127     Using addConnection() API user can also connect to hbdialog's signals(for ex: aboutToClose) in case 

   148     - creates the data form and data form model

   128     of popup items like radio button list item and multi selection list item. Below code snippet demonstrates

   149     - adds the data form model items (i.e. groups, group pages, and data items)

   129     the same:

   150     - sets the model to the view

   130 

   151     

   131     \code

   152     

   132     HbDataFormModelItem *days = model->appendDataFormItem(HbDataFormModelItem::MultiselectionItem,

   153     \snippet{ultimatecodesnippet/ultimatecodesnippet.cpp,31}

   133                                     QString("Days"), themeGeneral);

   154     

   134     QStringList multiItems;

   155     The code creates the following structure:

   135     multiItems<<"Sunday"<<"Monday"<<"Tuesday"<<"Wednesday"<<"Thursday"<<"Friday";

   156     - Group 1                              - group

   136     days->setContentWidgetData(QString("items"), multiItems);

   157       - %Data Item 1  (check box)              - data item

   137     QList<QVariant> selected;

   158         - Check box added to group            - text property of the data item

   138     selected<<2<<3;

   159       - %Data Item 2 (text item)              - data item

   139     days->setContentWidgetData(QString("selectedItems"), selected);

   160         - Text Item added to group            - text property of the data item

   140     days->setContentWidgetData(QString("items"), multiItems);

   161     - %Data Item 3  (combo box)              - data item

   141     form->addConnection(days, SIGNAL(aboutToShow()), this, SLOT(aboutToShow()));

   162     - Profile                              - group

   142     form->addConnection(days, SIGNAL(aboutToHide()()), this, SLOT(aboutToHide()()));

   163       - Silent                              - group page

   143     form->addConnection(days, SIGNAL(aboutToClose()), this, SLOT(aboutToClose()));

   164         - Slider                              - data item

   144     form->addConnection(days, SIGNAL(finished(HbAction*)), this, SLOT(finished(HbAction*)));

   165       - General                              - group page

   145 

   166       - Meeting                              - group page

   146     \endcode

   167         

   147 

   168     The generated data form is the following:

   148     Similar way 

   169 

   149     removeConnection(HbDataFormModelItem *item, const char* signal, QObject *receiver, const char* slot)

   170     \image html hbsettingform.png

   150     and removeAllConnection() API can be used. Connection can be established or removed even at runtime.

   171 

   151     An example of how to make connection and setting the content widget property:

   172     The picture below shows the generated data form in the landscape mode.

   152 

   173 

   174     \image html hbsettingform_landscape.png

   175 

   176      \subsection _uc_hbdataform_002 Connecting the "sliderReleased" signal to the "volumeChanged" slot.

   177 

   178     In the following example the content widget is a slider whose 

   179     "sliderReleased"  \a signal is connected to the "volumeChanged" slot which 

   180     handles the changed volume.

   181     

   169     

   198 

   170     An example of how to create HbDataForm:

   199      \subsection _uc_hbdataform_003 Creating the model hierarchy.

   171     \snippet{ultimatecodesnippet/ultimatecodesnippet.cpp,31}

   200 

   172 

   201     You can create the model hierarchy with the \link 

   173     The output generated by the above code looks like:

   202     HbDataFormModel::appendDataFormPage() appendDataFormPage()\endlink, \link 

   174 

   203     HbDataFormModel::appendDataFormGroup() appendDataFormGroup()\endlink, \link 

   175     \image html hbsettingform.png

   204     HbDataFormModel::appendDataFormGroupPage() 

   176 

   205     appendDataFormGroupPage()\endlink, and \link 

   177     This is how HbDataForm will look like in landscape mode:

   206     HbDataFormModel::appendDataFormItem() appendDataFormItem()\endlink methods 

   178 

   207     of the HbDataFormModel class. All of these methods will return 

   179     \image html hbsettingform_landscape.png

   208     HbDataFormModelItem object corresponding to each type in which the user can 

   180 

   209     set item specific data. 

   181     \sa HbDataFormViewItem, HbDataFormModel, HbDataFormModelItem

   210     

   182 

   211     After running the setModel method the visualization is created . The items 

   183     Creating Custom Item:

   212     of expanded groups and group pages are created. The data form emits the 

   184 

   213     itemShown(const QModelIndex &index) signal when an the  visualization of 

   185     Application developer can create custom DataItem by deriving from HbDataFormViewItem and setting this as 

   214     item is created. The application can get HbDataFormViewItem and content 

   186     prototype using setItemProtoType() API. Application has to override virtual API's createCustomWidget(),

   215     widget from HbDataForm using QModelIndex.

   187     restore()and save(). createCustomWidget() API should return the corresponding custom HbWidget which

   216 */

   188     can also be a compound widget. Signal connection for child widgets inside the compound widget should

   217 

   189     be taken care by the application. restore() API will be called by the framework when the model data 

   218 /*!

   190     is changed. So restore() should take care of updating the visual items with correspoding data from model. 

   219     \fn void HbDataForm::itemShown(const QModelIndex &index)

   191     save() API should update the model. App developer should connect respective widgets SIGNALs to SLOT save() 

   220 

   192     and update the data to model .

   221     This signal is emitted when HbDataFormViewItem corresponding to \a index is 

   193 

   222     shown.

   194 */

   223 

   195 

   224 */

   196 /*!

   225 

   197     \fn void HbAbstractItemView::itemShown(const QModelIndex &index)

   226 /*!

   198 

   227     Constructs a data form with the given \a parent.

   199     This signal is emitted when HbDataFormViewItem corresponding to \a index is shown.

   200 

   201 */

   202 

   203 /*!

   204     Constructs DataForm with given \a parent.

   205     \param parent parent .

   218     Constructs a data form with a private class object \a dd, 

   240     Constructs a data form with the given private class object \a dd, 

   231     Destructs the data form.

   253     Destructor.

   237 /*!

   259 /*! Scrolls the view so that the data form item of given \a index is shown at 

   238     \reimp

   260 the given \a hint position of the screen. By default the data form does not 

   239 

   261 scroll, so to make it scroll connect to the activated signal first and then call 

   240     Scrolls the view so that the item represented by \a index position is changed as per \a hint

   262 this method.

   241     parameter. By default HbDataForm does not scrolls. Application developer is supposed to 

   263     

   242     call this API if he wants this behaviour. User can connect to itemShown signal and then

   264     \param index - item of the data form to be scrolled to the \a hint position. 

   243     can call this API.

   265     \param hint - position the item is scrolled to on the view, for example to 

   266     the top or center. The values of \a hint are the following:

   267 

   268     - EnsureVisible (default)

   269     - PositionAtTop

   270     - PositionAtBottom

   271     - PositionAtCenter

   272 

   254     Sets the item referred to by \a index to either collapse or expanded state, 

   283     Expands and collapses the given item specified by \a index, depending on the 

   255     depending on the value of \a expanded. If \a expanded is true then child item are 

   284     given \a expanded value. If it is \c true, the item is expanded. If it is \c 

   256     supposed to be visible and in that case itemShown will be emitted for all the

   285     false, the item is collapsed. When the item is

   257     new data items which were created.

   286     

   287     - expanded, its child items are shown.

   288     - collapsed, its child items are not shown.

   287     Returns true if the model item at \a index is expanded otherwise returns false.

   322     Returns \c true if the given model item is expanded (i.e. children are 

   323     visible), otherwise returns \c false.

   324     

   325     \param index - the model item

   305     Sets the heading of HbDataForm with the \a heading provided. Heading is displayed on 

   343     Sets the data form's heading to be the given \a heading. The heading is 

   306     top of the HbDataForm. Heading is non-focusable.

   344     displayed on the top of form and it is non-focusable.

   307 

   345 

   308     \sa heading 

   346     \sa heading, setDescription and description

   309     \sa setDescription

   310     \sa description

   315 

   351     prepareGeometryChange();

   344     Returns heading of HbDataForm.

   380     Returns the heading of the data form.

   345 

   381 

   346     \sa setHeading

   382     \sa setHeading, setDescription and description

   347     \sa setDescription

   348     \sa description

   363     Sets the description of HbDataForm with the \a description. Description is displayed 

   397     Sets the data form's description to be the given \a description. The 

   364     below heading. Description is non-focusable.

   398     description is displayed below the heading and it is non-focusable.

   365 

   399 

   366     \sa description

   400     \sa description, setHeading and heading

   367     \sa setHeading

   368     \sa heading

   373 

   405     prepareGeometryChange();

   402     Returns description of HbDataForm.

   434     Returns the description of the data form.

   403 

   435 

   404     \sa setDescription

   436     \sa setDescription, setHeading and heading

   405     \sa setHeading

   406     \sa heading

   424     Returns the style primitive of HbDataForm depending upon the type \a primitive.

   454     Returns the style primitive of HbDataForm depending on the type \a primitive.

   432         case HbStyle::P_DataForm_heading_background:

   462         case HbStylePrivate::P_DataForm_heading_background:

   434         case HbStyle::P_DataForm_heading:

   464         case HbStylePrivate::P_DataForm_heading:

   436         case HbStyle::P_DataForm_description:

   466         case HbStylePrivate::P_DataForm_description:

   443 /*!

   473 

   444     \reimp

   474 

   445 

   475 /*!

   446     If \a model passed is NULL then all values of data form are reset. Calls the

   476     Sets the data form model to the given \a model. If the given \a model is 

   447     setModel of base class. This API does not clears the heading and description set

   477     NULL then all values of the data form are reset. This method does not clear 

   448     for HbDataForm. If with new \a model user does not wants heading and description

   478     the heading and description of the data form. If you want the heading and 

   449     then he should call setHeading and setDescription with empty string.

   479     description of the data model to be empty, call HbDataForm::setHeading() and 

   450 

   480     HbDataForm::setDescription() with an empty string as a parameter.

   481     

   469 /*!

   500 

   470     \reimp

   501 /*!

   471 */

   502 

   503 */

   504 

   496     \reimp

   529     Initializes the style option data form defined by \a option with the data 

   497 

   530     form values.

   498     Initializes \a option with the values from HbDataForm.

   531     

   532     \param option - Style option data form to be initialized.

   508     \reimp

   542 

   516     \reimp

   550 

   548     This API can be used to connect with the signal of HbDataFormViewItem's content widget.

   582     Connects the \a signal of content widget \a item to the \a slot of \a 

   549     For example: If HbDataFormModelItem is of type DataItemType::SliderItem then user

   583     receiver object.

   550     can connect to the signals of slider using this API.

   584     

   551     Example Usage:

   585     \param item - %Data form model item.

   552     \code

   586     \param signal - Signal of the content widget. 

   553     HbDataForm *form = new HbDataForm();

   587     \param receiver - Object whose slot is called. 

   554     HbDataFormModel *model = new HbDataFormModel();

   588     \param slot - Slot of \a receiver object which is called when \a signal is emitted.

   555     HbDataFormModelItem *sliderItem = model->appendDataFormItem(HbDataFormModelItem::SliderItem);

   556     form->addConnection(sliderItem, SIGNAL(sliderReleased()), 

   557         this, SLOT(volumeChanged()));

   558     \endcode

   559 

   560     \param item Instance of model item 

   561     \param signal Signal of content widget. 

   562     \param receiver Instance of object whose slot will be called 

   563     \param slot Slot of \a receiver which will get called when signal is emitted

   565     \sa removeConnection

   590     \sa removeConnection 

   566     \sa removeAllConnection

   585     This API can be used to remove the signal connection which was established using the

   609     Removes the connection between the signal of content widget object and the 

   586     addConnection API.

   610     slot of receiver object.

   587 

   611 

   588     \sa addConnection

   612     \param item - %Data form model item.

   589     \sa removeAllConnection

   613 	\param signal - The signal of content widget object.

   614 	\param receiver - The object whose slot is called.

   615 	\param slot - The slot of \a receiver object which is called when \a signal is emitted.

   616 

   617     \sa addConnection and removeAllConnection

   603     Removes the connection of all the contentwidget of all the items which has been established.

   631     Removes all the connections between signals and slots of all content widgets 

   604     The connection information stored inside data form is also cleared.

   632     of all items. The connection information stored in the underlying data form 

   605 

   633     is also cleared.

   606     \sa removeConnection

   634 

   607     \sa addConnection

   635     \sa removeConnection and addConnection

   618     Removes all connections to the contentwidget of HbDataFormModelItem's corresponding 

   646     Removes all the connections of the content widget \a item. The connection 

   619     visual Item ( HbdataFormViewItem ).The connection information of correspoding 

   647     information stored in the underlying data form is also cleared.

   620     HbDataFormModelItem stored inside data form also cleared.