20 ** |
20 ** |
21 ** If you have questions regarding the use of this file, please contact |
21 ** If you have questions regarding the use of this file, please contact |
22 ** Nokia at developer.feedback@nokia.com. |
22 ** Nokia at developer.feedback@nokia.com. |
23 ** |
23 ** |
24 ****************************************************************************/ |
24 ****************************************************************************/ |
25 #include <hblistwidgetitem.h> |
25 |
|
26 #include "hblistwidgetitem.h" |
26 #include "hblistwidgetitem_p.h" |
27 #include "hblistwidgetitem_p.h" |
27 |
28 |
28 #include "hblistmodel_p.h" |
29 #include "hblistmodel_p.h" |
29 #include <hblistwidget.h> |
30 #include <hblistwidget.h> |
30 #include <hbicon.h> |
31 #include <hbicon.h> |
33 |
34 |
34 /*! |
35 /*! |
35 @beta |
36 @beta |
36 @hbwidgets |
37 @hbwidgets |
37 \class HbListWidgetItem |
38 \class HbListWidgetItem |
38 \brief HbListWidgetItem represents a list item. It is part of convenience list API together with HbListWidget. |
39 \brief The HbListWidgetItem class provides an item for use with the HbListWidget class. |
39 |
40 |
40 As this is a convenience API it is supposed to be easy to use. For that reason complicated list items are not possible |
41 As HbListWidget by itself supports the use of very basic items in simple lists, HbListWidgetItem provides together with HbListWidget a convenience API for adding, modifying, and removing more versatile items in simple lists. So, if you want to have list items consisting of more than an icon and a text, create HbListWidgetItem objects and add them to an HbListWidget object. The list item of HbListWidgetItem class consists of three columns and its features are as follows: |
41 to be created. HbListWidgetItem supports at maximum two text items and two icon items. |
42 - The left and right columns have one row and they can contain an icon. |
42 Either primary text or primary icon must always be provided. Icons are shown only in default size. |
43 - The middle column can have two rows and both rows can contain text. |
43 |
44 - At least the primary text is required. |
44 A view item created from this item consists of three columns at maximum. |
45 |
45 - First column contains primary icon |
46 \section _usecases_hblistwidgetitem Using the HbListWidgetItem class |
46 - Middle column has one or two rows to show text(s) |
47 |
47 - Last column contains secondary icon |
48 \subsection _uc_hblistwidgetitem_001 Creating a list item and adding two icons and two rows of text into it. |
48 - Any column can be empty |
49 |
49 |
50 The following code snippet creates a list item with icons in the left and right columns and two rows of text in the middle column. |
50 The following code snippet presents how to create an list item with icons in the left |
|
51 and right columns and two rows of text in the middle column. |
|
52 |
51 |
53 \snippet{unittest_hblistwidgetitem.cpp,1} |
52 \snippet{unittest_hblistwidgetitem.cpp,1} |
54 |
53 |
55 \sa HbListWidget |
54 \sa HbListWidget |
56 |
|
57 */ |
55 */ |
58 |
56 |
59 /*! |
57 /*! |
60 \fn QBrush HbListWidgetItem::background() const |
58 \fn QBrush HbListWidgetItem::background() const |
61 |
59 |
62 Returns item's background. |
60 Returns the background of the item. |
63 |
61 |
64 \sa setBackground |
62 \sa setBackground |
65 */ |
63 */ |
66 |
64 |
67 /*! |
65 /*! |
68 \fn void HbListWidgetItem::setBackground(const QVariant &background) |
66 \fn void HbListWidgetItem::setBackground(const QVariant &background) |
69 |
67 |
70 Sets the item's background to the specified \a background. Supported |
68 Sets the background of the item to the given \a background. Supported types are as follows: |
71 background types are HbIcon and QBrush types plus any type that can be |
69 - HbIcon |
72 converted to those types. |
70 - QBrush |
|
71 - any type that can be converted to HbIcon or QBrush |
73 |
72 |
74 \sa background |
73 \sa background |
75 */ |
74 */ |
76 |
75 |
77 /*! |
76 /*! |
78 Constructs an empty list widget item with the given \a type. |
77 Constructs an empty list widget item of the given \a type. If no type is specified then Hb::StandardItem is used. |
79 |
78 |
80 Default type for item is Hb::StandardItem. |
79 |
81 */ |
80 */ |
82 HbListWidgetItem::HbListWidgetItem(int type) : |
81 HbListWidgetItem::HbListWidgetItem(int type) : |
83 d(new HbListWidgetItemPrivate(this)) |
82 d(new HbListWidgetItemPrivate(this)) |
84 { |
83 { |
85 if (type != Hb::StandardItem) { |
84 if (type != Hb::StandardItem) { |
101 delete d; |
100 delete d; |
102 } |
101 } |
103 |
102 |
104 |
103 |
105 /*! |
104 /*! |
106 Returns the item's application-specific data for the given role, |
105 Returns |
107 or an invalid QVariant if there is no data for the role. |
106 - the item's application-specific data of the given \a role if the data exists. |
|
107 - an invalid QVariant if there is no data of the given \a role for the item. |
108 */ |
108 */ |
109 QVariant HbListWidgetItem::data(int role) const |
109 QVariant HbListWidgetItem::data(int role) const |
110 { |
110 { |
111 return d->data(role); |
111 return d->data(role); |
112 } |
112 } |
113 |
113 |
114 /*! |
114 /*! |
115 Sets the item's data for the given role to the specified value. |
115 Sets the item's data for the given \a role to the given \a value. It can be used to store application-specific data into an item. |
116 Can be used to store application-specific data in an item. |
116 |
117 |
117 Specialized functions in section 'see also' are recommended setting user data. |
118 Specialised functions in section 'see also' are recommended setting user data. |
118 \param role - Role for the data of the item. |
119 |
119 */ |
120 \sa setText() |
|
121 \sa setSecondaryText() |
|
122 \sa setIcon() |
|
123 \sa setSecondaryIcon() |
|
124 */ |
|
125 void HbListWidgetItem::setData(const QVariant &value, int role) |
120 void HbListWidgetItem::setData(const QVariant &value, int role) |
126 { |
121 { |
127 d->setData(value,role); |
122 d->setData(value,role); |
128 if (d->mModel) |
123 if (d->mModel) |
129 d->mModel->itemChanged(this); |
124 d->mModel->itemChanged(this); |
151 if (d->mModel) |
146 if (d->mModel) |
152 d->mModel->itemChanged(this); |
147 d->mModel->itemChanged(this); |
153 } |
148 } |
154 |
149 |
155 /*! |
150 /*! |
156 Returns item's secondary text. |
151 Returns the secondary text of the item. |
157 |
152 |
158 \sa setSecondaryText |
153 \sa setSecondaryText |
159 */ |
154 */ |
160 QString HbListWidgetItem::secondaryText() const |
155 QString HbListWidgetItem::secondaryText() const |
161 { |
156 { |
162 return d->data(Qt::DisplayRole, 1).toString(); |
157 return d->data(Qt::DisplayRole, 1).toString(); |
163 } |
158 } |
164 |
159 |
165 /*! |
160 /*! |
166 Sets the item's secondary text to the specified \a text. |
161 Sets the item's secondary text to the given \a text. |
167 |
162 |
168 \sa secondaryText |
163 \sa secondaryText |
169 */ |
164 */ |
170 void HbListWidgetItem::setSecondaryText(const QString &text) |
165 void HbListWidgetItem::setSecondaryText(const QString &text) |
171 { |
166 { |
173 if (d->mModel) |
168 if (d->mModel) |
174 d->mModel->itemChanged(this); |
169 d->mModel->itemChanged(this); |
175 } |
170 } |
176 |
171 |
177 /*! |
172 /*! |
178 Returns item's icon. |
173 Returns the item's icon. |
179 |
174 |
180 \sa setIcon |
175 \sa setIcon |
181 */ |
176 */ |
182 HbIcon HbListWidgetItem::icon() const |
177 HbIcon HbListWidgetItem::icon() const |
183 { |
178 { |
184 return d->data(Qt::DecorationRole, 0).value<HbIcon>(); |
179 return d->data(Qt::DecorationRole, 0).value<HbIcon>(); |
185 } |
180 } |
186 |
181 |
187 /*! |
182 /*! |
188 Sets the item's icon to the specified \a icon. |
183 Sets the item's icon to the given \a icon. |
189 |
184 |
190 \sa icon |
185 \sa icon |
191 */ |
186 */ |
192 void HbListWidgetItem::setIcon(const HbIcon &icon) |
187 void HbListWidgetItem::setIcon(const HbIcon &icon) |
193 { |
188 { |
195 if (d->mModel) |
190 if (d->mModel) |
196 d->mModel->itemChanged(this); |
191 d->mModel->itemChanged(this); |
197 } |
192 } |
198 |
193 |
199 /*! |
194 /*! |
200 Returns item's secondary icon. |
195 Returns the item's secondary icon. |
201 |
196 |
202 \sa setSecondaryIcon |
197 \sa setSecondaryIcon |
203 */ |
198 */ |
204 HbIcon HbListWidgetItem::secondaryIcon() const |
199 HbIcon HbListWidgetItem::secondaryIcon() const |
205 { |
200 { |
206 return d->data(Qt::DecorationRole, 1).value<HbIcon>(); |
201 return d->data(Qt::DecorationRole, 1).value<HbIcon>(); |
207 } |
202 } |
208 |
203 |
209 /*! |
204 /*! |
210 Sets the item's secondary icon to the specified \a icon. |
205 Sets the item's secondary icon to the given \a icon. |
211 |
206 |
212 \sa secondaryIcon |
207 \sa secondaryIcon |
213 */ |
208 */ |
214 void HbListWidgetItem::setSecondaryIcon(const HbIcon &icon) |
209 void HbListWidgetItem::setSecondaryIcon(const HbIcon &icon) |
215 { |
210 { |
217 if (d->mModel) |
212 if (d->mModel) |
218 d->mModel->itemChanged(this); |
213 d->mModel->itemChanged(this); |
219 } |
214 } |
220 |
215 |
221 /*! |
216 /*! |
222 Sets whether the item is enabled. |
217 Enables the user interaction with item. |
223 |
218 |
224 If enabled is true, the item is \a enabled, meaning that the user can interact with the item; if \a enabled is false, |
219 \param enabled - If the value is \c true, the user can interact with the item. If the value is \c false, the user cannot interact with the item. |
225 the user cannot interact with the item. |
|
226 */ |
220 */ |
227 void HbListWidgetItem::setEnabled(bool enabled) |
221 void HbListWidgetItem::setEnabled(bool enabled) |
228 { |
222 { |
229 if (enabled != (bool)(d->flags & Qt::ItemIsEnabled)) { |
223 if (enabled != (bool)(d->flags & Qt::ItemIsEnabled)) { |
230 if (enabled) { |
224 if (enabled) { |