| changeset 3 | 11d3954df52a |
| parent 2 | 06ff229162e9 |
| child 5 | 627c4a0fd0e7 |
| 2:06ff229162e9 | 3:11d3954df52a |
|---|---|
41 |
41 |
42 /*! |
42 /*! |
43 @beta |
43 @beta |
44 @hbwidgets |
44 @hbwidgets |
45 \class HbDataForm |
45 \class HbDataForm |
46 \brief HbDataForm represents hierarchical dataitems in the form of groups,pages and |
46 \brief HbDataForm represents hierarchical dataitems in form of form pages, groups, group pages |
47 items. |
47 and data items. |
48 The HbDataForm class provides a default view implementation of dataform. |
48 HbDataForm implements a hierarchical representation of view items for each model items from |
49 A HbDataForm implements a hierarchical representation of data items from a model. |
49 HbDataFormModel. |
50 |
50 |
51 HbDataForm implements the interfaces defined by the HbAbstractItemView class to allow |
51 HbDataForm implements the interfaces defined by the HbAbstractItemView class to allow |
52 it to display data provided by models derived from the QAbstractItemModel class. |
52 it to display data provided by models which are derived from QAbstractItemModel class. |
53 |
53 |
54 It is simple to construct a dataform displaying data from a model. The user has to create |
54 It is simple to construct a dataform displaying data from a model. The user has to create |
55 HbDataFormModel and create the hierarchy of HbDataFormModelItems .The hierarchy is |
55 HbDataFormModel and create the hierarchy of HbDataFormModelItems.The hierarchy is |
56 similar to the following. |
56 similar to the following. |
57 |
57 |
58 - HbDataForm |
58 - HbDataForm |
59 - HbDataFormPage1 |
59 - HbDataFormPage1 |
60 - HbDataGroup1 |
60 - HbDataGroup1 |
68 - HbDataGroupPage2 |
68 - HbDataGroupPage2 |
69 - HbDataItem |
69 - HbDataItem |
70 - HbDataItem |
70 - HbDataItem |
71 - HbDataItem |
71 - HbDataItem |
72 - HbDataItem |
72 - HbDataItem |
73 - HbDataGroup3 |
|
74 - HbDataItem |
|
75 - HbDataItem |
|
76 - HbDataItem |
|
77 - HbDataItem |
|
78 - HbDataItem |
|
73 |
79 |
74 HbDataItem can be the child of HbDataForm, HbDataFormPage,HbDataGroup and |
80 HbDataItem can be the child of HbDataForm, HbDataFormPage, HbDataGroup and |
75 HbDataGroupPage. An instance of HbDataForm has to be created and model should be set |
81 HbDataGroupPage. An instance of HbDataForm has to be created and model should be set |
76 to the form using setModel(HbDataFormModel) API. |
82 to the form using setModel( ) API. |
77 The properties of each DataItem node can be set using HbDataFormModelItem convenient |
83 The properties of each data item node can be set using HbDataFormModelItem convenient |
78 API's. These data are parsed while the visualization instance of each item is created and |
84 API's like setContentWidgetData( ). These model data are parsed and set while the visualization |
79 set on each item. |
85 instance of each item is created. |
80 |
86 |
81 The model/view architecture ensures that the contents of the data view are updated as the |
87 The model/view architecture ensures that the view contents are updated as and when the data in |
82 model changes. |
88 model changes. |
83 |
89 |
84 Items that have children can be in expanded (children are visible) or collapsed |
90 Only model items that can have children can be in expanded (childrens are visible) or |
85 (children are hidden) state. DataItems of type HbDataFormPage, HbDataGroup and |
91 collapsed (childrens are hidden) state. Model items of type HbDataFormModelItem::FormPageItem, |
86 HbDataGroupPage can be expanded and collapsed. HbDataItem of type FormPageItem, |
92 HbDataFormModelItem::GroupItem and HbDataFormModelItem::GroupPageItem can be expanded |
87 GroupItem, GroupPageItem can only have children. Each item in model is represented by an |
93 or collapsed. Which in turn means that these types of model item can only have children. |
88 instance of HbDataFormViewItem. HbDataForm uses HbDataFormViewItem prototype to instantiate |
94 Each item in model is represented by either an instance of HbDataFormViewItem or classes which |
89 the HbDataForm items. HbDataFormViewItem can be subclassed for customization purposes. |
95 are derived from HbDataFormViewItem. HbDataFormViewItem can be subclassed for |
96 customization purposes. |
|
90 |
97 |
91 The Model hierarchy can be created using the convenient API's provided on model class like |
98 The Model hierarchy can be created using the convenient API's provided in model class like |
92 appendDataFormPage , appendDataFormGroup ,appendDataFormGroupPage and |
99 appendDataFormPage(), appendDataFormGroup(), appendDataFormGroupPage() and |
93 appendDataFormItem. All of these will return HbDataFormModelItem instance correspoding |
100 appendDataFormItem(). All these API's return HbDataFormModelItem instance corresponding |
94 to each type on which user can set item specific data. Otherwise each HbDataFormModelItem can |
101 to each HbDataFormModelItem::DataItemType type on which user can set item |
95 be created individually by passing the corresponding type of item (GroupItem, GroupPageItem, |
102 specific(content widget) data. Otherwise each HbDataFormModelItem can be created individually |
96 FormPageItem) and create the tree of HbDataFormModelItem using setParent API |
103 by passing the corresponding type of item (GroupItem, GroupPageItem, FormPageItem) and create |
97 or by passing the parent HbDataFormModelItem in constructor. Later the top level |
104 the tree of HbDataFormModelItem using setParent API or by passing the parent |
98 HbDataFormModelItem can be added inside the model. |
105 HbDataFormModelItem in constructor. Later the top level HbDataFormModelItem can be added in |
99 |
106 model. |
100 After doing the setModel, the visualization gets created . Only the items inside the expanded |
107 |
101 group or group page instances are created. When an item's visualization is created , |
108 After setting model in HbDataForm using setModel(), the visualization gets created. |
102 DataForm emits activated(constQModelIndex&) signal. The application can get |
109 Only the items inside the expanded form page, group or group page are created. When an item's |
103 HbDataFormViewItem and content widget from DataForm using QModelIndex. |
110 visualization is created, HbDataForm emits itemShown(constQModelIndex&) signal. The application |
111 can connect to this signal and when corresponding slot is called then application can get |
|
112 HbDataFormViewItem instance and even content widget instance. Use HbAbstractItemView::itemByIndex() |
|
113 to get HbDataFormViewItem instance. Use HbDataFormViewItem::dataItemContentWidget() to get |
|
114 content widget instance. |
|
104 |
115 |
105 The signal emitted by HbDataForm |
116 The signals emitted by HbDataForm |
106 \li activated(const QModelIndex &index) Emitted when the HbDataFormViewItem corresponding to |
117 \li itemShown(const QModelIndex &index) Emitted when the HbDataFormViewItem corresponding to |
107 \a index is shown. User can connect to this signal and can fetch the instance of |
118 \a index is shown. User can connect to this signal and can fetch the instance of |
108 HbDataFormViewItem from HbDataForm using the API dataFormViewItem(const QModelIndex &index). |
119 HbDataFormViewItem from HbDataForm using the API dataFormViewItem(const QModelIndex &index). |
109 \li dataChanged(const QModelIndex &topLeft, const QModelIndex &bottomRight) emitted when the |
120 This signal is only emitted for model items of type greater than HbDataFormModelItem::GroupPageItem |
110 HbDataFormModel is updated \atopLeft and \abottomRight will be same since every node has only one column. |
121 |
111 User can connect to this signal and can fetch the instance of HbDataFormViewItem from HbDataForm |
122 The user can also provide connection information to correspoding content widget of each |
112 using the API dataFormViewItem(const QModelIndex &index) or user can fetch HbDataFormModelItem using API |
123 HbDataFormModelItem using API |
113 itemFromIndex(const QModelIndex &index) in HbDataFormModel .When user updates model using |
124 addConnection(HbDataFormModelItem* item, const char* signal, QObject* receiver, const char* slot) |
114 setContentWidgetData API provided in HbDataFormModelItem class, then DataForm takes care of updating the |
125 provided in HbDataForm. The connection will be established when the item visualization is created. |
115 corresponding item's visualization. |
126 Similar way |
116 |
127 removeConnection(HbDataFormModelItem *item, const char* signal, QObject *receiver, const char* slot) |
117 The user can also provide connection information to correspoding content widget of each HbDataFormModelItem |
128 and removeAllConnection() API can be used. Connection can be established or removed even at runtime. |
118 using API addConnection(HbDataFormModelItem* item, const char* signal, QObject* receiver, consta char* slot) |
129 An example of how to make connection and setting the content widget property: |
119 provided in HbDataForm class.The connection will be established when the item visualization is created . |
130 |
120 similar way removeConnection(HbDataFormModelItem *item, const char* signal, QObject *receiver, const char* slot) |
131 \code |
121 and removeAllConnection() API can be used. Connection can be established or removed even at runtime also. |
132 HbDataForm *form = new HbDataForm(); |
133 model = new HbDataFormModel(); |
|
134 |
|
135 HbDataFormModelItem *sliderItem = |
|
136 model->appendDataFormItem(HbDataFormModelItem::SliderItem, QString("slider")); |
|
137 //Set the content widget properties. In this case its HbSlider. |
|
138 sliderItem->setContentWidgetData("maximum", 200); |
|
139 sliderItem->setContentWidgetData("minimum", 0); |
|
140 sliderItem->setContentWidgetData("value", 100); |
|
141 //Make a connection to HbSlider valueChanged signal. |
|
142 form->addConnection(sliderItem, SIGNAL(valueChanged(int)), this, SLOT(sliderValueChanged(int))); |
|
143 |
|
144 form->setModel(model); |
|
145 setWidget(form); |
|
146 \endcode |
|
122 |
147 |
123 An example of how to create HbDataForm: |
148 An example of how to create HbDataForm: |
124 \snippet{ultimatecodesnippet/ultimatecodesnippet.cpp,31} |
149 \snippet{ultimatecodesnippet/ultimatecodesnippet.cpp,31} |
125 |
150 |
126 The output generated by the above code looks like: |
151 The output generated by the above code looks like: |
132 \image html hbsettingform_landscape.png |
157 \image html hbsettingform_landscape.png |
133 |
158 |
134 \sa HbDataFormViewItem, HbDataFormModel, HbDataFormModelItem |
159 \sa HbDataFormViewItem, HbDataFormModel, HbDataFormModelItem |
135 |
160 |
136 Creating Custom Item: |
161 Creating Custom Item: |
162 |
|
137 Application developer can create custom DataItem by deriving from HbDataFormViewItem and setting this as |
163 Application developer can create custom DataItem by deriving from HbDataFormViewItem and setting this as |
138 prototype(setItemProtoType() API). |
164 prototype using setItemProtoType() API. Application has to override virtual API's createCustomWidget(), |
139 Application has to override virtual API's createCustomWidget() , restore()and save(). |
165 restore()and save(). createCustomWidget() API should return the corresponding custom HbWidget which |
140 createCustomWidget() API should return the corresponding custom HbWidget which can also be a compound widget. |
166 can also be a compound widget. Signal connection for child widgets inside the compound widget should |
141 Signal connection for child widgets inside the compound widget should taken care by the application. |
167 be taken care by the application. restore() API will be called by the framework when the model data |
142 restore() API will be called by the framework when the model data is changed. |
168 is changed. So restore() should take care of updating the visual items with correspoding data from model. |
143 So restore() should take care of updating the visual items with correspoding data from model. |
169 save() API should update the model. App developer should connect respective widgets SIGNALs to SLOT save() |
144 save() API should update the model.App developer should connect respective widgets SIGNALs to SLOT save() |
|
145 and update the data to model . |
170 and update the data to model . |
146 |
171 |
147 */ |
172 */ |
148 |
173 |
149 /*! |
174 /*! |
150 \fn void HbAbstractItemView::activated(const QModelIndex &index) |
175 \fn void HbAbstractItemView::itemShown(const QModelIndex &index) |
151 |
176 |
152 This signal is emitted when HbDataFormViewItem corresponding to \a index is shown. |
177 This signal is emitted when HbDataFormViewItem corresponding to \a index is shown. |
153 |
178 |
154 */ |
179 */ |
155 |
180 |
163 { |
188 { |
164 Q_D( HbDataForm ); |
189 Q_D( HbDataForm ); |
165 d->q_ptr = this; |
190 d->q_ptr = this; |
166 d->init(); |
191 d->init(); |
167 setVerticalScrollBarPolicy(ScrollBarAlwaysOff); |
192 setVerticalScrollBarPolicy(ScrollBarAlwaysOff); |
168 //d->mHeadingWidget->createPrimitives(); |
|
169 //static_cast<HbDataItemContainer*>(container())->setFormHeading(d->mHeadingWidget); |
|
170 } |
193 } |
171 |
194 |
172 /*! |
195 /*! |
173 Constructs a data form with a private class object \a dd, |
196 Constructs a data form with a private class object \a dd, |
174 \a container and \a parent. |
197 \a container and \a parent. |
190 } |
213 } |
191 |
214 |
192 /*! |
215 /*! |
193 \reimp |
216 \reimp |
194 |
217 |
195 Scrolls the view so that the item represented by \a index comes at the middle of |
218 Scrolls the view so that the item represented by \a index position is changed as per \a hint |
196 screen. By default HbDataForm does not scrolls. Application developer is supposed to |
219 parameter. By default HbDataForm does not scrolls. Application developer is supposed to |
197 call this API if he wants this behaviour. User can connect to activated signal and then |
220 call this API if he wants this behaviour. User can connect to itemShown signal and then |
198 can call this API. |
221 can call this API. |
199 */ |
222 */ |
200 void HbDataForm::scrollTo(const QModelIndex &index, ScrollHint hint) |
223 void HbDataForm::scrollTo(const QModelIndex &index, ScrollHint hint) |
201 { |
224 { |
202 //Q_D(HbDataForm); |
|
203 //d->revealItem(d->mContainer->itemByIndex(index), PositionAtCenter); |
|
204 HbAbstractItemView::scrollTo(index, hint); |
225 HbAbstractItemView::scrollTo(index, hint); |
205 } |
226 } |
206 |
227 |
207 |
228 |
208 /*! |
229 /*! |
209 @beta |
230 @beta |
210 |
231 |
211 Sets the item referred to by \a index to either collapse or expanded, |
232 Sets the item referred to by \a index to either collapse or expanded state, |
212 depending on the value of \a expanded. If \a expanded is true then child item are |
233 depending on the value of \a expanded. If \a expanded is true then child item are |
213 supposed to be visible. |
234 supposed to be visible and in that case itemShown will be emitted for all the |
235 new data items which were created. |
|
214 |
236 |
215 \sa isExpanded |
237 \sa isExpanded |
216 */ |
238 */ |
217 void HbDataForm::setExpanded(const QModelIndex &index, bool expanded) |
239 void HbDataForm::setExpanded(const QModelIndex &index, bool expanded) |
218 { |
240 { |
233 } |
255 } |
234 |
256 |
235 /*! |
257 /*! |
236 @beta |
258 @beta |
237 |
259 |
238 Returns true if the model item \a index is expanded otherwise returns false. |
260 Returns true if the model item at \a index is expanded otherwise returns false. |
239 |
261 |
240 \sa setExpanded |
262 \sa setExpanded |
241 */ |
263 */ |
242 bool HbDataForm::isExpanded(const QModelIndex &index) const |
264 bool HbDataForm::isExpanded(const QModelIndex &index) const |
243 { |
265 { |
254 @beta |
276 @beta |
255 |
277 |
256 Sets the heading of HbDataForm with the \a heading provided. Heading is displayed on |
278 Sets the heading of HbDataForm with the \a heading provided. Heading is displayed on |
257 top of the HbDataForm. Heading is non-focusable. |
279 top of the HbDataForm. Heading is non-focusable. |
258 |
280 |
259 \sa heading |
281 \sa heading |
282 \sa setDescription |
|
283 \sa description |
|
260 */ |
284 */ |
261 void HbDataForm::setHeading(const QString &heading) |
285 void HbDataForm::setHeading(const QString &heading) |
262 { |
286 { |
263 Q_D(HbDataForm); |
287 Q_D(HbDataForm); |
264 |
288 |
290 /*! |
314 /*! |
291 @beta |
315 @beta |
292 |
316 |
293 Returns heading of HbDataForm. |
317 Returns heading of HbDataForm. |
294 |
318 |
295 \sa setHeading |
319 \sa setHeading |
320 \sa setDescription |
|
321 \sa description |
|
296 */ |
322 */ |
297 QString HbDataForm::heading() const |
323 QString HbDataForm::heading() const |
298 { |
324 { |
299 Q_D(const HbDataForm); |
325 Q_D(const HbDataForm); |
300 if(d->mHeadingWidget) { |
326 if(d->mHeadingWidget) { |
309 |
335 |
310 Sets the description of HbDataForm with the \a description. Description is displayed |
336 Sets the description of HbDataForm with the \a description. Description is displayed |
311 below heading. Description is non-focusable. |
337 below heading. Description is non-focusable. |
312 |
338 |
313 \sa description |
339 \sa description |
340 \sa setHeading |
|
341 \sa heading |
|
314 */ |
342 */ |
315 void HbDataForm::setDescription(const QString &description) |
343 void HbDataForm::setDescription(const QString &description) |
316 { |
344 { |
317 Q_D(HbDataForm); |
345 Q_D(HbDataForm); |
318 |
346 |
345 @beta |
373 @beta |
346 |
374 |
347 Returns description of HbDataForm. |
375 Returns description of HbDataForm. |
348 |
376 |
349 \sa setDescription |
377 \sa setDescription |
378 \sa setHeading |
|
379 \sa heading |
|
350 */ |
380 */ |
351 QString HbDataForm::description() const |
381 QString HbDataForm::description() const |
352 { |
382 { |
353 Q_D(const HbDataForm); |
383 Q_D(const HbDataForm); |
354 if(d->mHeadingWidget) { |
384 if(d->mHeadingWidget) { |
410 |
440 |
411 |
441 |
412 /*! |
442 /*! |
413 \reimp |
443 \reimp |
414 */ |
444 */ |
415 |
|
416 void HbDataForm::dataChanged(const QModelIndex &topLeft, const QModelIndex &bottomRight) |
445 void HbDataForm::dataChanged(const QModelIndex &topLeft, const QModelIndex &bottomRight) |
417 { |
446 { |
418 Q_UNUSED(bottomRight); |
447 Q_UNUSED(bottomRight); |
419 if(topLeft.isValid()) { |
448 if(topLeft.isValid()) { |
420 |
449 |
485 } |
514 } |
486 } |
515 } |
487 } |
516 } |
488 |
517 |
489 /*! |
518 /*! |
490 @alpha |
519 @beta |
491 |
520 |
492 This API can be used to connect with the signal of HbDataFormViewItem's content widget. |
521 This API can be used to connect with the signal of HbDataFormViewItem's content widget. |
493 For example: If HbDataFormModelItem is of type DataItemType::SliderItem then user |
522 For example: If HbDataFormModelItem is of type DataItemType::SliderItem then user |
494 can connect to the signals of slider using this API. |
523 can connect to the signals of slider using this API. |
495 Example Usage: |
524 Example Usage: |
504 \param item Instance of model item |
533 \param item Instance of model item |
505 \param signal Signal of content widget. |
534 \param signal Signal of content widget. |
506 \param receiver Instance of object whose slot will be called |
535 \param receiver Instance of object whose slot will be called |
507 \param slot Slot of \a receiver which will get called when signal is emitted |
536 \param slot Slot of \a receiver which will get called when signal is emitted |
508 |
537 |
509 \sa removeConnection |
538 \sa removeConnection |
539 \sa removeAllConnection |
|
510 */ |
540 */ |
511 void HbDataForm::addConnection(HbDataFormModelItem * item, |
541 void HbDataForm::addConnection(HbDataFormModelItem * item, |
512 const char* signal, |
542 const char* signal, |
513 QObject *receiver, |
543 QObject *receiver, |
514 const char* slot) |
544 const char* slot) |
521 d->mConnectionList.insertMulti(item, itemSignal); |
551 d->mConnectionList.insertMulti(item, itemSignal); |
522 d->connectNow(item, signal, receiver, slot); |
552 d->connectNow(item, signal, receiver, slot); |
523 } |
553 } |
524 |
554 |
525 /*! |
555 /*! |
526 @alpha |
556 @beta |
527 |
557 |
528 This API can be used to remove the signal connection which was established using the |
558 This API can be used to remove the signal connection which was established using the |
529 addConnection API. |
559 addConnection API. |
530 |
560 |
531 \sa addConnection |
561 \sa addConnection |
562 \sa removeAllConnection |
|
532 */ |
563 */ |
533 void HbDataForm::removeConnection(HbDataFormModelItem * item, |
564 void HbDataForm::removeConnection(HbDataFormModelItem * item, |
534 const char* signal, |
565 const char* signal, |
535 QObject *receiver, |
566 QObject *receiver, |
536 const char* slot) |
567 const char* slot) |
538 Q_D(HbDataForm); |
569 Q_D(HbDataForm); |
539 d->removeConnection(item, signal, receiver, slot); |
570 d->removeConnection(item, signal, receiver, slot); |
540 } |
571 } |
541 |
572 |
542 /*! |
573 /*! |
543 @alpha |
574 @beta |
544 |
575 |
545 Removes the connection of all the contentwidget of all the items which has been established . |
576 Removes the connection of all the contentwidget of all the items which has been established. |
546 The connection information stored inside DataForm also cleared. |
577 The connection information stored inside data form is also cleared. |
547 |
578 |
548 \sa removeAllConnection |
579 \sa removeConnection |
580 \sa addConnection |
|
549 */ |
581 */ |
550 void HbDataForm::removeAllConnection() |
582 void HbDataForm::removeAllConnection() |
551 { |
583 { |
552 Q_D(HbDataForm); |
584 Q_D(HbDataForm); |
553 d->removeAllConnection(); |
585 d->removeAllConnection(); |
554 } |
586 } |
555 |
587 |
556 /*! |
588 /*! |
557 @alpha |
589 @beta |
558 |
590 |
559 Removes the all connections of the contentwidget of HbDataFormModelItem's corresponding |
591 Removes all connections to the contentwidget of HbDataFormModelItem's corresponding |
560 visual Item ( HbdataFormViewItem).The connection information of correspoding |
592 visual Item ( HbdataFormViewItem ).The connection information of correspoding |
561 HbDataFormModelItem stored inside DataForm also cleared. |
593 HbDataFormModelItem stored inside data form also cleared. |
562 |
594 |
563 \sa removeAllConnection |
595 \sa removeAllConnection |
564 */ |
596 */ |
565 void HbDataForm::removeAllConnection(HbDataFormModelItem *item) |
597 void HbDataForm::removeAllConnection(HbDataFormModelItem *item) |
566 { |
598 { |