--- a/src/hbwidgets/dataform/hbdataform.cpp Tue Jul 06 14:36:53 2010 +0300
+++ b/src/hbwidgets/dataform/hbdataform.cpp Wed Aug 18 10:05:37 2010 +0300
@@ -44,112 +44,141 @@
@beta
@hbwidgets
\class HbDataForm
- \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 which are derived from QAbstractItemModel class.
+ \brief The HbDataForm class is for showing and entering data in
+ hierarchically organized pages and groups of a form.
- 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
- similar to the following.
-
- - HbDataForm
- - HbDataFormPage1
- - HbDataGroup1
- - HbDataGroupPage1
- - HbDataItem
- - HbDataItem
- - HbDataItem
- - HbDataItem
- - HbDataFormPage2
- - HbDataGroup2
- - HbDataGroupPage2
- - HbDataItem
- - HbDataItem
- - HbDataItem
- - HbDataItem
- - HbDataGroup3
- - HbDataItem
- - HbDataItem
- - HbDataItem
- - HbDataItem
- - HbDataItem
-
- 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( ) 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.
+ A data form contains data items for showing and entering data in an
+ application. Each data item shown in a data form can contain an input widget
+ and an optional text label. Text fields, sliders and check boxes are typical
+ widgets used to show and collect data in an application. If a complex data
+ form contains many data items a user may be required to scroll the data form
+ content. To reduce the need to scroll, the data items can be organised into
+ elements whose hierarchy is the following:
+ - %Data form
+ - Form pages
+ - Groups
+ - Group pages
- The model/view architecture ensures that the view contents are updated as and when the data in
- model changes.
+ The data form uses a model-view architecture. HbDataFormModel represents the
+ data model for the form. You add HbDataFormModelItem objects (i.e. form
+ pages, groups, group pages and data items) to a data form model by creating
+ a HbDataFormModel object and adding HbDataFormModelItem objects to it. You
+ can then create a data form widget to show the data by creating an
+ HbDataForm object and setting its data form model. The model-view
+ architecture ensures that the content of the data form view is updated as
+ the data form model changes.
- 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 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
+ The important thing to note is that you do not create data form widgets
+ directly in your data form. The HbDataForm object creates the appropriate UI
+ widget type for each data item in your data form model. You must specify the
+ type of widget that is shown in the data form when you create your data form
model.
- 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.
+ HbDataForm implements the interface defined by the HbAbstractItemView class
+ to display the data provided by the data form model. This model is derived
+ from the QAbstractItemModel class. To construct a data form for displaying
+ the data from a data form model, create HbDataFormModel and the hierarchy of
+ HbDataFormModelItem objects. The following rules apply in the hierarchy:
+ - A form page can be a child of the data form only.
+ - A group can be a child of the data form or a form page.
+ - A group page can be a child of a group only.
+ - A data item can be the child of data form, form page, group, and group page.
+
+ The hierarchy can be for example the following:
- 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).
- This signal is only emitted for model items of type greater than HbDataFormModelItem::GroupPageItem
+ - %Data form
+ - Form page 1
+ - Group 1
+ - Group page 1
+ - %Data item 1
+ - %Data item 2
+ - %Data item 3
+ - %Data item 4
+ - Form page 2
+ - %Data item 5
+ - Group 2
+ - %Data item 6
+ - Group page 2
+ - %Data item 7
+ - %Data item 8
+ - Group 3
+ - %Data item 9
- 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.
- Using addConnection() API user can also connect to hbdialog's signals(for ex: aboutToClose) in case
- of popup items like radio button list item and multi selection list item. Below code snippet demonstrates
- the same:
+ To build the structure create first the HbDataForm object and set the model
+ to the form with the setModel() method. Set properties of each data item
+ with methods of HbDataFormModelItem class. The data is parsed when the
+ visualization instance of each item is created and set on each item.
+
+ Items which have children (i.e. form pages, groups, and group pages) can be
+ in expanded (i.e. children are visible) or collapsed (i.e. children are
+ hidden) state. Each item in data form model is represented by an
+ HbDataFormViewItem object. HbDataForm uses HbDataFormViewItem prototype to
+ instantiate the data form items. HbDataFormViewItem can be subclassed for
+ customization purposes.
- \code
- HbDataFormModelItem *days = model->appendDataFormItem(HbDataFormModelItem::MultiselectionItem,
- QString("Days"), themeGeneral);
- QStringList multiItems;
- multiItems<<"Sunday"<<"Monday"<<"Tuesday"<<"Wednesday"<<"Thursday"<<"Friday";
- days->setContentWidgetData(QString("items"), multiItems);
- QList<QVariant> selected;
- selected<<2<<3;
- days->setContentWidgetData(QString("selectedItems"), selected);
- days->setContentWidgetData(QString("items"), multiItems);
- form->addConnection(days, SIGNAL(aboutToShow()), this, SLOT(aboutToShow()));
- form->addConnection(days, SIGNAL(aboutToHide()()), this, SLOT(aboutToHide()()));
- form->addConnection(days, SIGNAL(aboutToClose()), this, SLOT(aboutToClose()));
- form->addConnection(days, SIGNAL(finished(HbAction*)), this, SLOT(finished(HbAction*)));
+ The signals emitted by HbDataForm are the following:
+ \li itemShown(const QModelIndex &index) signal is emitted when the
+ HbDataFormViewItem corresponding to \a index is shown. You can connect to
+ this signal and fetch the instance of HbDataFormViewItem from HbDataForm
+ with HbAbstractItemView::itemByIndex().
+ \li dataChanged(const QModelIndex &topLeft, const QModelIndex &bottomRight)
+ signal is emitted when the HbDataFormModel is updated \a topLeft and \a
+ bottomRight will be same since every node has only one column. You can
+ connect to this signal and fetch the instance of
+ - HbDataFormViewItem from HbDataForm with HbAbstractItemView::itemByIndex() or
+ - HbDataFormModelItem with HbDataFormModel::itemFromIndex(). HbDataForm
+ takes care of updating the corresponding the visualization of item when you
+ update the model with HbDataFormModelItem::setContentWidgetData().
+
+ You can also provide the connection information to the corresponding content
+ widget of each HbDataFormModelItem with the \link HbDataForm::addConnection(HbDataFormModelItem * item, const char* signal, QObject *receiver, const char* slot) HbDataForm::addConnection()\endlink
+ method. The connection is established when the item visualization is
+ created. You can use \link HbDataForm::removeConnection(HbDataFormModelItem *item, const char* signal, QObject *receiver, const char* slot) HbDataForm::removeConnection()\endlink and HbDataForm::removeAllConnection()
+ methods in the same way. You can establish and remove the connection also at
+ runtime.
- \endcode
+ \sa HbDataFormViewItem, HbDataFormModel, and HbDataFormModelItem
+
+ \section _usecases_hbdataform Using the HbDataForm class
+
+ \subsection _uc_hbdataform_001 Creating a data form.
+
+ The following example shows how to create a data form. The code
+ - creates the data form and data form model
+ - adds the data form model items (i.e. groups, group pages, and data items)
+ - sets the model to the view
+
+
+ \snippet{ultimatecodesnippet/ultimatecodesnippet.cpp,31}
+
+ The code creates the following structure:
+ - Group 1 - group
+ - %Data Item 1 (check box) - data item
+ - Check box added to group - text property of the data item
+ - %Data Item 2 (text item) - data item
+ - Text Item added to group - text property of the data item
+ - %Data Item 3 (combo box) - data item
+ - Profile - group
+ - Silent - group page
+ - Slider - data item
+ - General - group page
+ - Meeting - group page
+
+ The generated data form is the following:
- 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:
+ \image html hbsettingform.png
+
+ The picture below shows the generated data form in the landscape mode.
+
+ \image html hbsettingform_landscape.png
+ \subsection _uc_hbdataform_002 Connecting the "sliderReleased" signal to the "volumeChanged" slot.
+
+ In the following example the content widget is a slider whose
+ "sliderReleased" \a signal is connected to the "volumeChanged" slot which
+ handles the changed volume.
+
\code
HbDataForm *form = new HbDataForm();
model = new HbDataFormModel();
@@ -166,43 +195,36 @@
form->setModel(model);
setWidget(form);
\endcode
-
- An example of how to create HbDataForm:
- \snippet{ultimatecodesnippet/ultimatecodesnippet.cpp,31}
- The output generated by the above code looks like:
-
- \image html hbsettingform.png
-
- This is how HbDataForm will look like in landscape mode:
-
- \image html hbsettingform_landscape.png
+ \subsection _uc_hbdataform_003 Creating the model hierarchy.
- \sa HbDataFormViewItem, HbDataFormModel, HbDataFormModelItem
-
- Creating Custom Item:
+ You can create the model hierarchy with the \link
+ HbDataFormModel::appendDataFormPage() appendDataFormPage()\endlink, \link
+ HbDataFormModel::appendDataFormGroup() appendDataFormGroup()\endlink, \link
+ HbDataFormModel::appendDataFormGroupPage()
+ appendDataFormGroupPage()\endlink, and \link
+ HbDataFormModel::appendDataFormItem() appendDataFormItem()\endlink methods
+ of the HbDataFormModel class. All of these methods will return
+ HbDataFormModelItem object corresponding to each type in which the user can
+ set item specific data.
+
+ After running the setModel method the visualization is created . The items
+ of expanded groups and group pages are created. The data form emits the
+ itemShown(const QModelIndex &index) signal when an the visualization of
+ item is created. The application can get HbDataFormViewItem and content
+ widget from HbDataForm using QModelIndex.
+*/
- Application developer can create custom DataItem by deriving from HbDataFormViewItem and setting this as
- 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 HbDataForm::itemShown(const QModelIndex &index)
+
+ This signal is emitted when HbDataFormViewItem corresponding to \a index is
+ shown.
*/
/*!
- \fn void HbAbstractItemView::itemShown(const QModelIndex &index)
-
- This signal is emitted when HbDataFormViewItem corresponding to \a index is shown.
-
-*/
-
-/*!
- Constructs DataForm with given \a parent.
- \param parent parent .
+ Constructs a data form with the given \a parent.
*/
HbDataForm::HbDataForm(QGraphicsItem *parent)
: HbAbstractItemView(*new HbDataFormPrivate(), new HbDataItemContainer(),
@@ -215,7 +237,7 @@
}
/*!
- Constructs a data form with a private class object \a dd,
+ Constructs a data form with the given private class object \a dd,
\a container and \a parent.
*/
HbDataForm::HbDataForm(HbDataFormPrivate &dd, HbAbstractItemContainer *container,
@@ -228,19 +250,26 @@
}
/*!
- Destructs the data form.
+ Destructor.
*/
HbDataForm::~HbDataForm()
{
}
-/*!
- \reimp
+/*! Scrolls the view so that the data form item of given \a index is shown at
+the given \a hint position of the screen. By default the data form does not
+scroll, so to make it scroll connect to the activated signal first and then call
+this method.
+
+ \param index - item of the data form to be scrolled to the \a hint position.
+ \param hint - position the item is scrolled to on the view, for example to
+ the top or center. The values of \a hint are the following:
- 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.
+ - EnsureVisible (default)
+ - PositionAtTop
+ - PositionAtBottom
+ - PositionAtCenter
+
*/
void HbDataForm::scrollTo(const QModelIndex &index, ScrollHint hint)
{
@@ -251,10 +280,12 @@
/*!
@beta
- 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 and in that case itemShown will be emitted for all the
- new data items which were created.
+ Expands and collapses the given item specified by \a index, depending on the
+ given \a expanded value. If it is \c true, the item is expanded. If it is \c
+ false, the item is collapsed. When the item is
+
+ - expanded, its child items are shown.
+ - collapsed, its child items are not shown.
\sa isExpanded
*/
@@ -276,6 +307,10 @@
// significance since these items cannot expand( do not have children )
else {
+ HbDataFormModelItem *modelItem = static_cast<HbDataFormModel *>(model())->itemFromIndex(index);
+ if(modelItem->type() == HbDataFormModelItem::GroupPageItem ) {
+ d->collapseAllGroupPages(index.parent());
+ }
d->mContainer->setItemTransientStateValue(index, "expanded", expanded);
}
}
@@ -284,7 +319,10 @@
/*!
@beta
- Returns true if the model item at \a index is expanded otherwise returns false.
+ Returns \c true if the given model item is expanded (i.e. children are
+ visible), otherwise returns \c false.
+
+ \param index - the model item
\sa setExpanded
*/
@@ -302,17 +340,15 @@
/*!
@beta
- Sets the heading of HbDataForm with the \a heading provided. Heading is displayed on
- top of the HbDataForm. Heading is non-focusable.
+ Sets the data form's heading to be the given \a heading. The heading is
+ displayed on the top of form and it is non-focusable.
- \sa heading
- \sa setDescription
- \sa description
+ \sa heading, setDescription and description
*/
void HbDataForm::setHeading(const QString &heading)
{
Q_D(HbDataForm);
-
+ prepareGeometryChange();
if(heading.isEmpty() && d->mHeadingWidget) {
if(!d->mHeadingWidget->mPageCombo && d->mHeadingWidget->mDescription.isEmpty()) {
// delete the FormheadingWidget
@@ -341,11 +377,9 @@
/*!
@beta
- Returns heading of HbDataForm.
+ Returns the heading of the data form.
- \sa setHeading
- \sa setDescription
- \sa description
+ \sa setHeading, setDescription and description
*/
QString HbDataForm::heading() const
{
@@ -360,17 +394,15 @@
/*!
@beta
- Sets the description of HbDataForm with the \a description. Description is displayed
- below heading. Description is non-focusable.
+ Sets the data form's description to be the given \a description. The
+ description is displayed below the heading and it is non-focusable.
- \sa description
- \sa setHeading
- \sa heading
+ \sa description, setHeading and heading
*/
void HbDataForm::setDescription(const QString &description)
{
Q_D(HbDataForm);
-
+ prepareGeometryChange();
if(description.isEmpty() && d->mHeadingWidget) {
if(!d->mHeadingWidget->mPageCombo && d->mHeadingWidget->mHeading.isEmpty()) {
// delete the FormheadingWidget
@@ -399,11 +431,9 @@
/*!
@beta
- Returns description of HbDataForm.
+ Returns the description of the data form.
- \sa setDescription
- \sa setHeading
- \sa heading
+ \sa setDescription, setHeading and heading
*/
QString HbDataForm::description() const
{
@@ -421,7 +451,7 @@
\reimp
- Returns the style primitive of HbDataForm depending upon the type \a primitive.
+ Returns the style primitive of HbDataForm depending on the type \a primitive.
\sa primitive
*/
QGraphicsItem* HbDataForm::primitive(HbStyle::Primitive primitive) const
@@ -429,25 +459,26 @@
Q_D(const HbDataForm);
switch (primitive) {
- case HbStyle::P_DataForm_heading_background:
+ case HbStylePrivate::P_DataForm_heading_background:
return d->mHeadingWidget->mBackgroundItem;
- case HbStyle::P_DataForm_heading:
+ case HbStylePrivate::P_DataForm_heading:
return d->mHeadingWidget->mHeadingItem;
- case HbStyle::P_DataForm_description:
+ case HbStylePrivate::P_DataForm_description:
return d->mHeadingWidget->mDescriptionItem;
default:
return 0;
}
}
-/*!
- \reimp
+
- If \a model passed is NULL then all values of data form are reset. Calls the
- setModel of base class. This API does not clears the heading and description set
- for HbDataForm. If with new \a model user does not wants heading and description
- then he should call setHeading and setDescription with empty string.
-
+/*!
+ Sets the data form model to the given \a model. If the given \a model is
+ NULL then all values of the data form are reset. This method does not clear
+ the heading and description of the data form. If you want the heading and
+ description of the data model to be empty, call HbDataForm::setHeading() and
+ HbDataForm::setDescription() with an empty string as a parameter.
+
\sa setHeading, setDescription
*/
void HbDataForm::setModel(QAbstractItemModel *model, HbAbstractViewItem *prototype)
@@ -466,9 +497,11 @@
}
+
/*!
- \reimp
+
*/
+
void HbDataForm::dataChanged(const QModelIndex &topLeft, const QModelIndex &bottomRight)
{
Q_UNUSED(bottomRight);
@@ -493,9 +526,10 @@
}
}
/*!
- \reimp
-
- Initializes \a option with the values from HbDataForm.
+ Initializes the style option data form defined by \a option with the data
+ form values.
+
+ \param option - Style option data form to be initialized.
*/
void HbDataForm::initStyleOption(HbStyleOptionDataForm *option)
{
@@ -505,7 +539,7 @@
/*!
- \reimp
+
*/
void HbDataForm::rowsInserted(const QModelIndex &parent, int start, int end)
{
@@ -513,7 +547,7 @@
}
/*!
- \reimp
+
*/
void HbDataForm::rowsAboutToBeRemoved(const QModelIndex &index, int start, int end)
{
@@ -545,25 +579,15 @@
/*!
@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
- can connect to the signals of slider using this API.
- Example Usage:
- \code
- HbDataForm *form = new HbDataForm();
- HbDataFormModel *model = new HbDataFormModel();
- HbDataFormModelItem *sliderItem = model->appendDataFormItem(HbDataFormModelItem::SliderItem);
- form->addConnection(sliderItem, SIGNAL(sliderReleased()),
- this, SLOT(volumeChanged()));
- \endcode
-
- \param item Instance of model item
- \param signal Signal of content widget.
- \param receiver Instance of object whose slot will be called
- \param slot Slot of \a receiver which will get called when signal is emitted
+ Connects the \a signal of content widget \a item to the \a slot of \a
+ receiver object.
+
+ \param item - %Data form model item.
+ \param signal - Signal of the content widget.
+ \param receiver - Object whose slot is called.
+ \param slot - Slot of \a receiver object which is called when \a signal is emitted.
- \sa removeConnection
- \sa removeAllConnection
+ \sa removeConnection
*/
void HbDataForm::addConnection(HbDataFormModelItem * item,
const char* signal,
@@ -582,11 +606,15 @@
/*!
@beta
- This API can be used to remove the signal connection which was established using the
- addConnection API.
+ Removes the connection between the signal of content widget object and the
+ slot of receiver object.
- \sa addConnection
- \sa removeAllConnection
+ \param item - %Data form model item.
+ \param signal - The signal of content widget object.
+ \param receiver - The object whose slot is called.
+ \param slot - The slot of \a receiver object which is called when \a signal is emitted.
+
+ \sa addConnection and removeAllConnection
*/
void HbDataForm::removeConnection(HbDataFormModelItem * item,
const char* signal,
@@ -600,11 +628,11 @@
/*!
@beta
- 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.
+ Removes all the connections between signals and slots of all content widgets
+ of all items. The connection information stored in the underlying data form
+ is also cleared.
- \sa removeConnection
- \sa addConnection
+ \sa removeConnection and addConnection
*/
void HbDataForm::removeAllConnection()
{
@@ -615,9 +643,8 @@
/*!
@beta
- 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.
+ Removes all the connections of the content widget \a item. The connection
+ information stored in the underlying data form is also cleared.
\sa removeAllConnection
*/