diff -r 06ff229162e9 -r 11d3954df52a src/hbwidgets/dataform/hbdataform.cpp --- a/src/hbwidgets/dataform/hbdataform.cpp Fri May 14 16:09:54 2010 +0300 +++ b/src/hbwidgets/dataform/hbdataform.cpp Thu May 27 13:10:59 2010 +0300 @@ -43,16 +43,16 @@ @beta @hbwidgets \class HbDataForm - \brief HbDataForm represents hierarchical dataitems in the form of groups,pages and - items. - The HbDataForm class provides a default view implementation of dataform. - A HbDataForm implements a hierarchical representation of data items from a model. + \brief HbDataForm represents hierarchical dataitems in form of form pages, groups, group pages + and data items. + HbDataForm implements a hierarchical representation of view items for each model items from + HbDataFormModel. HbDataForm implements the interfaces defined by the HbAbstractItemView class to allow - it to display data provided by models derived from the QAbstractItemModel class. + it to display data provided by models which are derived from QAbstractItemModel class. It is simple to construct a dataform displaying data from a model. The user has to create - HbDataFormModel and create the hierarchy of HbDataFormModelItems .The hierarchy is + HbDataFormModel and create the hierarchy of HbDataFormModelItems.The hierarchy is similar to the following. - HbDataForm @@ -70,55 +70,80 @@ - HbDataItem - HbDataItem - HbDataItem + - HbDataGroup3 + - HbDataItem + - HbDataItem + - HbDataItem + - HbDataItem + - HbDataItem - HbDataItem can be the child of HbDataForm, HbDataFormPage,HbDataGroup and + HbDataItem can be the child of HbDataForm, HbDataFormPage, HbDataGroup and HbDataGroupPage. An instance of HbDataForm has to be created and model should be set - to the form using setModel(HbDataFormModel) API. - The properties of each DataItem node can be set using HbDataFormModelItem convenient - API's. These data are parsed while the visualization instance of each item is created and - set on each item. + to the form using setModel( ) API. + The properties of each data item node can be set using HbDataFormModelItem convenient + API's like setContentWidgetData( ). These model data are parsed and set while the visualization + instance of each item is created. - The model/view architecture ensures that the contents of the data view are updated as the + The model/view architecture ensures that the view contents are updated as and when the data in model changes. - Items that have children can be in expanded (children are visible) or collapsed - (children are hidden) state. DataItems of type HbDataFormPage, HbDataGroup and - HbDataGroupPage can be expanded and collapsed. HbDataItem of type FormPageItem, - GroupItem, GroupPageItem can only have children. Each item in model is represented by an - instance of HbDataFormViewItem. HbDataForm uses HbDataFormViewItem prototype to instantiate - the HbDataForm items. HbDataFormViewItem can be subclassed for customization purposes. + Only model items that can have children can be in expanded (childrens are visible) or + collapsed (childrens are hidden) state. Model items of type HbDataFormModelItem::FormPageItem, + HbDataFormModelItem::GroupItem and HbDataFormModelItem::GroupPageItem can be expanded + or collapsed. Which in turn means that these types of model item can only have children. + Each item in model is represented by either an instance of HbDataFormViewItem or classes which + are derived from HbDataFormViewItem. HbDataFormViewItem can be subclassed for + customization purposes. - The Model hierarchy can be created using the convenient API's provided on model class like - appendDataFormPage , appendDataFormGroup ,appendDataFormGroupPage and - appendDataFormItem. All of these will return HbDataFormModelItem instance correspoding - to each type on which user can set item specific data. Otherwise each HbDataFormModelItem can - be created individually by passing the corresponding type of item (GroupItem, GroupPageItem, - FormPageItem) and create the tree of HbDataFormModelItem using setParent API - or by passing the parent HbDataFormModelItem in constructor. Later the top level - HbDataFormModelItem can be added inside the model. + The Model hierarchy can be created using the convenient API's provided in model class like + appendDataFormPage(), appendDataFormGroup(), appendDataFormGroupPage() and + appendDataFormItem(). All these API's return HbDataFormModelItem instance corresponding + to each HbDataFormModelItem::DataItemType type on which user can set item + specific(content widget) data. Otherwise each HbDataFormModelItem can be created individually + by passing the corresponding type of item (GroupItem, GroupPageItem, FormPageItem) and create + the tree of HbDataFormModelItem using setParent API or by passing the parent + HbDataFormModelItem in constructor. Later the top level HbDataFormModelItem can be added in + model. - After doing the setModel, the visualization gets created . Only the items inside the expanded - group or group page instances are created. When an item's visualization is created , - DataForm emits activated(constQModelIndex&) signal. The application can get - HbDataFormViewItem and content widget from DataForm using QModelIndex. + After setting model in HbDataForm using setModel(), the visualization gets created. + Only the items inside the expanded form page, group or group page are created. When an item's + visualization is created, HbDataForm emits itemShown(constQModelIndex&) signal. The application + can connect to this signal and when corresponding slot is called then application can get + HbDataFormViewItem instance and even content widget instance. Use HbAbstractItemView::itemByIndex() + to get HbDataFormViewItem instance. Use HbDataFormViewItem::dataItemContentWidget() to get + content widget instance. - The signal emitted by HbDataForm - \li activated(const QModelIndex &index) Emitted when the HbDataFormViewItem corresponding to + The signals emitted by HbDataForm + \li itemShown(const QModelIndex &index) Emitted when the HbDataFormViewItem corresponding to \a index is shown. User can connect to this signal and can fetch the instance of HbDataFormViewItem from HbDataForm using the API dataFormViewItem(const QModelIndex &index). - \li dataChanged(const QModelIndex &topLeft, const QModelIndex &bottomRight) emitted when the - HbDataFormModel is updated \atopLeft and \abottomRight will be same since every node has only one column. - User can connect to this signal and can fetch the instance of HbDataFormViewItem from HbDataForm - using the API dataFormViewItem(const QModelIndex &index) or user can fetch HbDataFormModelItem using API - itemFromIndex(const QModelIndex &index) in HbDataFormModel .When user updates model using - setContentWidgetData API provided in HbDataFormModelItem class, then DataForm takes care of updating the - corresponding item's visualization. + This signal is only emitted for model items of type greater than HbDataFormModelItem::GroupPageItem + + The user can also provide connection information to correspoding content widget of each + HbDataFormModelItem using API + addConnection(HbDataFormModelItem* item, const char* signal, QObject* receiver, const char* slot) + provided in HbDataForm. The connection will be established when the item visualization is created. + Similar way + removeConnection(HbDataFormModelItem *item, const char* signal, QObject *receiver, const char* slot) + and removeAllConnection() API can be used. Connection can be established or removed even at runtime. + An example of how to make connection and setting the content widget property: - The user can also provide connection information to correspoding content widget of each HbDataFormModelItem - using API addConnection(HbDataFormModelItem* item, const char* signal, QObject* receiver, consta char* slot) - provided in HbDataForm class.The connection will be established when the item visualization is created . - similar way removeConnection(HbDataFormModelItem *item, const char* signal, QObject *receiver, const char* slot) - and removeAllConnection() API can be used. Connection can be established or removed even at runtime also. + \code + HbDataForm *form = new HbDataForm(); + model = new HbDataFormModel(); + + HbDataFormModelItem *sliderItem = + model->appendDataFormItem(HbDataFormModelItem::SliderItem, QString("slider")); + //Set the content widget properties. In this case its HbSlider. + sliderItem->setContentWidgetData("maximum", 200); + sliderItem->setContentWidgetData("minimum", 0); + sliderItem->setContentWidgetData("value", 100); + //Make a connection to HbSlider valueChanged signal. + form->addConnection(sliderItem, SIGNAL(valueChanged(int)), this, SLOT(sliderValueChanged(int))); + + form->setModel(model); + setWidget(form); + \endcode An example of how to create HbDataForm: \snippet{ultimatecodesnippet/ultimatecodesnippet.cpp,31} @@ -134,20 +159,20 @@ \sa HbDataFormViewItem, HbDataFormModel, HbDataFormModelItem Creating Custom Item: + Application developer can create custom DataItem by deriving from HbDataFormViewItem and setting this as - prototype(setItemProtoType() API). - Application has to override virtual API's createCustomWidget() , restore()and save(). - createCustomWidget() API should return the corresponding custom HbWidget which can also be a compound widget. - Signal connection for child widgets inside the compound widget should taken care by the application. - restore() API will be called by the framework when the model data is changed. - So restore() should take care of updating the visual items with correspoding data from model. - save() API should update the model.App developer should connect respective widgets SIGNALs to SLOT save() + prototype using setItemProtoType() API. Application has to override virtual API's createCustomWidget(), + restore()and save(). createCustomWidget() API should return the corresponding custom HbWidget which + can also be a compound widget. Signal connection for child widgets inside the compound widget should + be taken care by the application. restore() API will be called by the framework when the model data + is changed. So restore() should take care of updating the visual items with correspoding data from model. + save() API should update the model. App developer should connect respective widgets SIGNALs to SLOT save() and update the data to model . */ /*! - \fn void HbAbstractItemView::activated(const QModelIndex &index) + \fn void HbAbstractItemView::itemShown(const QModelIndex &index) This signal is emitted when HbDataFormViewItem corresponding to \a index is shown. @@ -165,8 +190,6 @@ d->q_ptr = this; d->init(); setVerticalScrollBarPolicy(ScrollBarAlwaysOff); - //d->mHeadingWidget->createPrimitives(); - //static_cast(container())->setFormHeading(d->mHeadingWidget); } /*! @@ -192,15 +215,13 @@ /*! \reimp - Scrolls the view so that the item represented by \a index comes at the middle of - screen. By default HbDataForm does not scrolls. Application developer is supposed to - call this API if he wants this behaviour. User can connect to activated signal and then + Scrolls the view so that the item represented by \a index position is changed as per \a hint + parameter. By default HbDataForm does not scrolls. Application developer is supposed to + call this API if he wants this behaviour. User can connect to itemShown signal and then can call this API. */ void HbDataForm::scrollTo(const QModelIndex &index, ScrollHint hint) { - //Q_D(HbDataForm); - //d->revealItem(d->mContainer->itemByIndex(index), PositionAtCenter); HbAbstractItemView::scrollTo(index, hint); } @@ -208,9 +229,10 @@ /*! @beta - Sets the item referred to by \a index to either collapse or expanded, + Sets the item referred to by \a index to either collapse or expanded state, depending on the value of \a expanded. If \a expanded is true then child item are - supposed to be visible. + supposed to be visible and in that case itemShown will be emitted for all the + new data items which were created. \sa isExpanded */ @@ -235,7 +257,7 @@ /*! @beta - Returns true if the model item \a index is expanded otherwise returns false. + Returns true if the model item at \a index is expanded otherwise returns false. \sa setExpanded */ @@ -256,7 +278,9 @@ Sets the heading of HbDataForm with the \a heading provided. Heading is displayed on top of the HbDataForm. Heading is non-focusable. - \sa heading + \sa heading + \sa setDescription + \sa description */ void HbDataForm::setHeading(const QString &heading) { @@ -292,7 +316,9 @@ Returns heading of HbDataForm. - \sa setHeading + \sa setHeading + \sa setDescription + \sa description */ QString HbDataForm::heading() const { @@ -311,6 +337,8 @@ below heading. Description is non-focusable. \sa description + \sa setHeading + \sa heading */ void HbDataForm::setDescription(const QString &description) { @@ -347,6 +375,8 @@ Returns description of HbDataForm. \sa setDescription + \sa setHeading + \sa heading */ QString HbDataForm::description() const { @@ -412,7 +442,6 @@ /*! \reimp */ - void HbDataForm::dataChanged(const QModelIndex &topLeft, const QModelIndex &bottomRight) { Q_UNUSED(bottomRight); @@ -487,7 +516,7 @@ } /*! - @alpha + @beta This API can be used to connect with the signal of HbDataFormViewItem's content widget. For example: If HbDataFormModelItem is of type DataItemType::SliderItem then user @@ -506,7 +535,8 @@ \param receiver Instance of object whose slot will be called \param slot Slot of \a receiver which will get called when signal is emitted - \sa removeConnection + \sa removeConnection + \sa removeAllConnection */ void HbDataForm::addConnection(HbDataFormModelItem * item, const char* signal, @@ -523,12 +553,13 @@ } /*! - @alpha + @beta This API can be used to remove the signal connection which was established using the addConnection API. - \sa addConnection + \sa addConnection + \sa removeAllConnection */ void HbDataForm::removeConnection(HbDataFormModelItem * item, const char* signal, @@ -540,12 +571,13 @@ } /*! - @alpha + @beta - Removes the connection of all the contentwidget of all the items which has been established . - The connection information stored inside DataForm also cleared. + Removes the connection of all the contentwidget of all the items which has been established. + The connection information stored inside data form is also cleared. - \sa removeAllConnection + \sa removeConnection + \sa addConnection */ void HbDataForm::removeAllConnection() { @@ -554,11 +586,11 @@ } /*! - @alpha + @beta - Removes the all connections of the contentwidget of HbDataFormModelItem's corresponding - visual Item ( HbdataFormViewItem).The connection information of correspoding - HbDataFormModelItem stored inside DataForm also cleared. + Removes all connections to the contentwidget of HbDataFormModelItem's corresponding + visual Item ( HbdataFormViewItem ).The connection information of correspoding + HbDataFormModelItem stored inside data form also cleared. \sa removeAllConnection */