summaryrefslogtreecommitdiffabout
path: root/kaddressbook/views/cardview.h
Unidiff
Diffstat (limited to 'kaddressbook/views/cardview.h') (more/less context) (ignore whitespace changes)
-rw-r--r--kaddressbook/views/cardview.h14
1 files changed, 11 insertions, 3 deletions
diff --git a/kaddressbook/views/cardview.h b/kaddressbook/views/cardview.h
index 2ea3771..9c245ea 100644
--- a/kaddressbook/views/cardview.h
+++ b/kaddressbook/views/cardview.h
@@ -1,343 +1,351 @@
1#ifndef CARDVIEW_H 1#ifndef CARDVIEW_H
2#define CARDVIEW_H 2#define CARDVIEW_H
3 3
4#include <qscrollview.h> 4#include <q3scrollview.h>
5#include <qptrlist.h> 5#include <q3ptrlist.h>
6#include <qstring.h> 6#include <qstring.h>
7#include <qrect.h> 7#include <qrect.h>
8#include <qpair.h> 8#include <qpair.h>
9#include <qpoint.h> 9#include <qpoint.h>
10//Added by qt3to4:
11#include <QWheelEvent>
12#include <QResizeEvent>
13#include <QFocusEvent>
14#include <QLabel>
15#include <QMouseEvent>
16#include <QKeyEvent>
17#include <QEvent>
10 18
11class QLabel; 19class QLabel;
12class QPainter; 20class QPainter;
13class QResizeEvent; 21class QResizeEvent;
14class QMouseEvent; 22class QMouseEvent;
15class CardView; 23class CardView;
16class CardViewPrivate; 24class CardViewPrivate;
17class CardViewItemPrivate; 25class CardViewItemPrivate;
18class CardViewTip; 26class CardViewTip;
19 27
20/** Represents a single card (item) in the card view. A card has a caption 28/** Represents a single card (item) in the card view. A card has a caption
21* and a list of fields. A Field is a label<->value pair. The labels in a 29* and a list of fields. A Field is a label<->value pair. The labels in a
22* card should be unique, since they will be used to index the values. 30* card should be unique, since they will be used to index the values.
23*/ 31*/
24class CardViewItem 32class CardViewItem
25{ 33{
26 friend class CardView; 34 friend class CardView;
27 35
28 public: 36 public:
29 /** A single field in the card view. The first item is the label 37 /** A single field in the card view. The first item is the label
30 * and the second item is the value. 38 * and the second item is the value.
31 */ 39 */
32 typedef QPair<QString, QString> Field; 40 typedef QPair<QString, QString> Field;
33 41
34 /** Constructor. 42 /** Constructor.
35 * 43 *
36 * @param parent The CardView that this card should be displayed on. 44 * @param parent The CardView that this card should be displayed on.
37 * @param caption The caption of the card. This is the text that will 45 * @param caption The caption of the card. This is the text that will
38 * appear at the top of the card. This is also the string that will 46 * appear at the top of the card. This is also the string that will
39 * be used to sort the cards in the view. 47 * be used to sort the cards in the view.
40 */ 48 */
41 CardViewItem(CardView *parent, QString caption = QString::null); 49 CardViewItem(CardView *parent, QString caption = QString::null);
42 virtual ~CardViewItem(); 50 virtual ~CardViewItem();
43 51
44 /** @return The caption of the card, or QString::null if none was ever 52 /** @return The caption of the card, or QString::null if none was ever
45 * set. 53 * set.
46 */ 54 */
47 const QString &caption() const; 55 const QString &caption() const;
48 56
49 /** Sets the caption of the card. This is the text that will 57 /** Sets the caption of the card. This is the text that will
50 * appear at the top of the card. This is also the string that will 58 * appear at the top of the card. This is also the string that will
51 * be used to sort the cards in the view. 59 * be used to sort the cards in the view.
52 */ 60 */
53 void setCaption(const QString &caption); 61 void setCaption(const QString &caption);
54 62
55 /** Paints the card using the given painter and color group. The 63 /** Paints the card using the given painter and color group. The
56 * card will handle painting itself selected if it is selected. 64 * card will handle painting itself selected if it is selected.
57 */ 65 */
58 virtual void paintCard(QPainter *p, QColorGroup &cg); 66 virtual void paintCard(QPainter *p, QColorGroup &cg);
59 67
60 /** Repaints the card. This is done by sending a repaint event to the 68 /** Repaints the card. This is done by sending a repaint event to the
61 * view with the clip rect defined as this card. 69 * view with the clip rect defined as this card.
62 */ 70 */
63 virtual void repaintCard(); 71 virtual void repaintCard();
64 72
65 /** Adds a field to the card. 73 /** Adds a field to the card.
66 * 74 *
67 * @param label The label of the field. The field labels must be unique 75 * @param label The label of the field. The field labels must be unique
68 * within a card. 76 * within a card.
69 * @param The value of the field. 77 * @param The value of the field.
70 */ 78 */
71 void insertField(const QString &label, const QString &value); 79 void insertField(const QString &label, const QString &value);
72 80
73 /** Removes the field with label <i>label</i> from the card. 81 /** Removes the field with label <i>label</i> from the card.
74 */ 82 */
75 void removeField(const QString &label); 83 void removeField(const QString &label);
76 84
77 /** @return The value of the field with label <i>label</i>. 85 /** @return The value of the field with label <i>label</i>.
78 */ 86 */
79 QString fieldValue(const QString &label); 87 QString fieldValue(const QString &label);
80 88
81 /** Removes all the fields from this card. 89 /** Removes all the fields from this card.
82 */ 90 */
83 void clearFields(); 91 void clearFields();
84 92
85 /** @return The next card item. The order of the items will be the same 93 /** @return The next card item. The order of the items will be the same
86 * as the display order in the view. 0 will be returned if this is the 94 * as the display order in the view. 0 will be returned if this is the
87 * last card. 95 * last card.
88 */ 96 */
89 CardViewItem *nextItem(); 97 CardViewItem *nextItem();
90 98
91 /** @return True if this card is currently selected, false otherwise. 99 /** @return True if this card is currently selected, false otherwise.
92 */ 100 */
93 bool isSelected() const; 101 bool isSelected() const;
94 102
95 /** Called by the parent card view when the mouse has been resting for 103 /** Called by the parent card view when the mouse has been resting for
96 * a certain amount of time. If the label or value at pos is obscured 104 * a certain amount of time. If the label or value at pos is obscured
97 * (trimmed) make the label display the full text. 105 * (trimmed) make the label display the full text.
98 */ 106 */
99 void showFullString( const QPoint &pos, CardViewTip *tip ); 107 void showFullString( const QPoint &pos, CardViewTip *tip );
100 108
101 /** @return a pointer to the Field at the position itempos 109 /** @return a pointer to the Field at the position itempos
102 * in this item. 0 is returned if itempos is in the caption. 110 * in this item. 0 is returned if itempos is in the caption.
103 * @param itempos the position in item coordinates 111 * @param itempos the position in item coordinates
104 */ 112 */
105 Field *fieldAt( const QPoint &itempos ) const; 113 Field *fieldAt( const QPoint &itempos ) const;
106 114
107 CardView *cardView() { return mView; }; 115 CardView *cardView() { return mView; };
108 116
109 /** @return The height of this item as rendered, in pixels. 117 /** @return The height of this item as rendered, in pixels.
110 118
111 if @p allowCache is true, the item may use an internally 119 if @p allowCache is true, the item may use an internally
112 cached value rather than recalculating from scratch. The 120 cached value rather than recalculating from scratch. The
113 argument is mainly to allow the cardView to change global settings (like 121 argument is mainly to allow the cardView to change global settings (like
114 maxFieldLines) that might influence the items heights 122 maxFieldLines) that might influence the items heights
115 */ 123 */
116 int height( bool allowCache=true ) const; 124 int height( bool allowCache=true ) const;
117 125
118 protected: 126 protected:
119 /** Sets the card as selected. This is usually only called from the 127 /** Sets the card as selected. This is usually only called from the
120 * card view. 128 * card view.
121 */ 129 */
122 void setSelected(bool selected); 130 void setSelected(bool selected);
123 131
124 private: 132 private:
125 /** Sets the default values. 133 /** Sets the default values.
126 */ 134 */
127 void initialize(); 135 void initialize();
128 136
129 /** Trims a string to the width <i>width</i> using the font metrics 137 /** Trims a string to the width <i>width</i> using the font metrics
130 * to determine the width of each char. If the string is longer than 138 * to determine the width of each char. If the string is longer than
131 * <i>width</i>, then the string will be trimmed and a '...' will 139 * <i>width</i>, then the string will be trimmed and a '...' will
132 * be appended. 140 * be appended.
133 */ 141 */
134 QString trimString(const QString &text, int width, QFontMetrics &fm); 142 QString trimString(const QString &text, int width, QFontMetrics &fm);
135 143
136 CardViewItemPrivate *d; 144 CardViewItemPrivate *d;
137 CardView *mView; 145 CardView *mView;
138}; 146};
139 147
140/** The CardView is a method of displaying data in cards. This idea is 148/** The CardView is a method of displaying data in cards. This idea is
141* similar to the idea of a rolodex or business cards. Each card has a 149* similar to the idea of a rolodex or business cards. Each card has a
142* caption and a list of fields, which are label<->value pairs. The CardView 150* caption and a list of fields, which are label<->value pairs. The CardView
143* displays multiple cards in a grid. The Cards are sorted based on their 151* displays multiple cards in a grid. The Cards are sorted based on their
144* caption. 152* caption.
145* 153*
146* The CardView class is designed to mirror the API of the QListView or 154* The CardView class is designed to mirror the API of the QListView or
147* QIconView. The CardView is also completely independant of KAddressBook and 155* QIconView. The CardView is also completely independant of KAddressBook and
148* can be used elsewhere. With the exception of a few simple config checks, 156* can be used elsewhere. With the exception of a few simple config checks,
149* the CardView is also 100% independant of KDE. 157* the CardView is also 100% independant of KDE.
150*/ 158*/
151class CardView : public QScrollView 159class CardView : public Q3ScrollView
152{ 160{
153 friend class CardViewItem; 161 friend class CardViewItem;
154 162
155 Q_OBJECT 163 Q_OBJECT
156 164
157 public: 165 public:
158 /** Constructor. 166 /** Constructor.
159 */ 167 */
160 CardView(QWidget *parent, const char *name); 168 CardView(QWidget *parent, const char *name);
161 virtual ~CardView(); 169 virtual ~CardView();
162 170
163 /** Inserts the item into the card view. This method does not have 171 /** Inserts the item into the card view. This method does not have
164 * to be called if you created the item with a proper parent. Once 172 * to be called if you created the item with a proper parent. Once
165 * inserted, the CardView takes ownership of the item. 173 * inserted, the CardView takes ownership of the item.
166 */ 174 */
167 void insertItem(CardViewItem *item); 175 void insertItem(CardViewItem *item);
168 176
169 /** Takes the item from the view. The item will not be deleted and 177 /** Takes the item from the view. The item will not be deleted and
170 * ownership of the item is returned to the caller. 178 * ownership of the item is returned to the caller.
171 */ 179 */
172 void takeItem(CardViewItem *item); 180 void takeItem(CardViewItem *item);
173 181
174 /** Clears the view and deletes all card view items 182 /** Clears the view and deletes all card view items
175 */ 183 */
176 void clear(); 184 void clear();
177 185
178 /** @return The current item, the item that has the focus. 186 /** @return The current item, the item that has the focus.
179 * Whenever the view has focus, this item has a focus rectangle painted 187 * Whenever the view has focus, this item has a focus rectangle painted
180 * at it's border. 188 * at it's border.
181 * @sa setCurrentItem() 189 * @sa setCurrentItem()
182 */ 190 */
183 CardViewItem *currentItem(); 191 CardViewItem *currentItem();
184 192
185 /** Sets the CardViewItem @p item to the current item in the view. 193 /** Sets the CardViewItem @p item to the current item in the view.
186 */ 194 */
187 void setCurrentItem( CardViewItem *item ); 195 void setCurrentItem( CardViewItem *item );
188 196
189 /** @return The item found at the given point, or 0 if there is no item 197 /** @return The item found at the given point, or 0 if there is no item
190 * at that point. 198 * at that point.
191 */ 199 */
192 CardViewItem *itemAt(const QPoint &viewPos); 200 CardViewItem *itemAt(const QPoint &viewPos);
193 201
194 /** @return The bounding rect of the given item. 202 /** @return The bounding rect of the given item.
195 */ 203 */
196 QRect itemRect(const CardViewItem *item); 204 QRect itemRect(const CardViewItem *item);
197 205
198 /** Ensures that the given item is in the viewable area of the widget 206 /** Ensures that the given item is in the viewable area of the widget
199 */ 207 */
200 void ensureItemVisible(const CardViewItem *item); 208 void ensureItemVisible(const CardViewItem *item);
201 209
202 /** Repaints the given item. 210 /** Repaints the given item.
203 */ 211 */
204 void repaintItem(const CardViewItem *item); 212 void repaintItem(const CardViewItem *item);
205 213
206 enum SelectionMode { Single, Multi, Extended, NoSelection }; 214 enum SelectionMode { Single, Multi, Extended, NoSelection };
207 215
208 /** Sets the selection mode. 216 /** Sets the selection mode.
209 * 217 *
210 * @see QListView 218 * @see QListView
211 */ 219 */
212 void setSelectionMode(SelectionMode mode); 220 void setSelectionMode(SelectionMode mode);
213 221
214 /** @return The current selection mode. 222 /** @return The current selection mode.
215 */ 223 */
216 SelectionMode selectionMode() const; 224 SelectionMode selectionMode() const;
217 225
218 /** Selects or deselects the given item. This method honors the current 226 /** Selects or deselects the given item. This method honors the current
219 * selection mode, so if other items are selected, they may be unselected. 227 * selection mode, so if other items are selected, they may be unselected.
220 */ 228 */
221 void setSelected(CardViewItem *item, bool selected); 229 void setSelected(CardViewItem *item, bool selected);
222 230
223 /** Selects or deselects all items. 231 /** Selects or deselects all items.
224 */ 232 */
225 void selectAll(bool state); 233 void selectAll(bool state);
226 234
227 /** @return True if the given item is selected, false otherwise. 235 /** @return True if the given item is selected, false otherwise.
228 */ 236 */
229 bool isSelected(CardViewItem *item) const; 237 bool isSelected(CardViewItem *item) const;
230 238
231 /** @return The first selected item. In single select mode, this will be 239 /** @return The first selected item. In single select mode, this will be
232 * the only selected item, in other modes this will be the first selected 240 * the only selected item, in other modes this will be the first selected
233 * item, but others may exist. 0 if no item is selected. 241 * item, but others may exist. 0 if no item is selected.
234 */ 242 */
235 CardViewItem *selectedItem() const; 243 CardViewItem *selectedItem() const;
236 244
237 /** @return The first item in the view. This may be 0 if no items have 245 /** @return The first item in the view. This may be 0 if no items have
238 * been inserted. This method combined with CardViewItem::nextItem() 246 * been inserted. This method combined with CardViewItem::nextItem()
239 * can be used to iterator through the list of items. 247 * can be used to iterator through the list of items.
240 */ 248 */
241 CardViewItem *firstItem() const; 249 CardViewItem *firstItem() const;
242 250
243 /** @return The item after the given item or 0 if the item is the last 251 /** @return The item after the given item or 0 if the item is the last
244 * item. 252 * item.
245 */ 253 */
246 CardViewItem *itemAfter(CardViewItem *item); 254 CardViewItem *itemAfter(CardViewItem *item);
247 255
248 /** @return The number of items in the view. 256 /** @return The number of items in the view.
249 */ 257 */
250 int childCount() const; 258 int childCount() const;
251 259
252 /** Attempts to find the first item matching the params. 260 /** Attempts to find the first item matching the params.
253 * 261 *
254 * @param text The text to match. 262 * @param text The text to match.
255 * @param label The label of the field to match against. 263 * @param label The label of the field to match against.
256 * @param compare The compare method to use in doing the search. 264 * @param compare The compare method to use in doing the search.
257 * 265 *
258 * @return The first matching item, or 0 if no items match. 266 * @return The first matching item, or 0 if no items match.
259 */ 267 */
260/*US 268/*US
261 CardViewItem *findItem(const QString &text, const QString &label, 269 CardViewItem *findItem(const QString &text, const QString &label,
262 Qt::StringComparisonMode compare = Qt::BeginsWith); 270 Qt::StringComparisonMode compare = Qt::BeginsWith);
263*/ 271*/
264 272
265 /** Returns the amounts of pixels required for one column. 273 /** Returns the amounts of pixels required for one column.
266 * This depends on wheather drawSeparators is enabled: 274 * This depends on wheather drawSeparators is enabled:
267 * If so, it is itemWidth + 2*itemSpacing + separatorWidth 275 * If so, it is itemWidth + 2*itemSpacing + separatorWidth
268 * If not, it is itemWidth + itemSpacing 276 * If not, it is itemWidth + itemSpacing
269 * @see itemWidth(), setItemWidth(), itemSpacing() and setItemSpacing() 277 * @see itemWidth(), setItemWidth(), itemSpacing() and setItemSpacing()
270 */ 278 */
271 uint columnWidth(); 279 uint columnWidth();
272 280
273 /** Sets if the border around a card should be draw. The border is a thing 281 /** Sets if the border around a card should be draw. The border is a thing
274 * (1 or 2 pixel) line that bounds the card. When drawn, it shows when 282 * (1 or 2 pixel) line that bounds the card. When drawn, it shows when
275 * a card is highlighted and when it isn't. 283 * a card is highlighted and when it isn't.
276 */ 284 */
277 void setDrawCardBorder(bool enabled); 285 void setDrawCardBorder(bool enabled);
278 286
279 /** @return True if borders are drawn, false otherwise. 287 /** @return True if borders are drawn, false otherwise.
280 */ 288 */
281 bool drawCardBorder() const; 289 bool drawCardBorder() const;
282 290
283 /** Sets if the column separator should be drawn. The column separator 291 /** Sets if the column separator should be drawn. The column separator
284 * is a thin verticle line (1 or 2 pixels) that is used to separate the 292 * is a thin verticle line (1 or 2 pixels) that is used to separate the
285 * columns in the list view. The separator is just for esthetics and it 293 * columns in the list view. The separator is just for esthetics and it
286 * does not serve a functional purpose. 294 * does not serve a functional purpose.
287 */ 295 */
288 void setDrawColSeparators(bool enabled); 296 void setDrawColSeparators(bool enabled);
289 297
290 /** @return True if column separators are drawn, false otherwise. 298 /** @return True if column separators are drawn, false otherwise.
291 */ 299 */
292 bool drawColSeparators() const; 300 bool drawColSeparators() const;
293 301
294 /** Sets if the field labels should be drawn. The field labels are the 302 /** Sets if the field labels should be drawn. The field labels are the
295 * unique strings used to identify the fields. Sometimes drawing these 303 * unique strings used to identify the fields. Sometimes drawing these
296 * labels makes sense as a source of clarity for the user, othertimes they 304 * labels makes sense as a source of clarity for the user, othertimes they
297 * waste too much space and do not assist the user. 305 * waste too much space and do not assist the user.
298 */ 306 */
299 void setDrawFieldLabels(bool enabled); 307 void setDrawFieldLabels(bool enabled);
300 308
301 /** @return True if the field labels are drawn, false otherwise. 309 /** @return True if the field labels are drawn, false otherwise.
302 */ 310 */
303 bool drawFieldLabels() const; 311 bool drawFieldLabels() const;
304 312
305 /** Sets if fields with no value should be drawn (of cause the label only, 313 /** Sets if fields with no value should be drawn (of cause the label only,
306 * but it allows for embedded editing sometimes...) 314 * but it allows for embedded editing sometimes...)
307 */ 315 */
308 void setShowEmptyFields(bool show); 316 void setShowEmptyFields(bool show);
309 317
310 /** @return Wheather empty fields should be shown 318 /** @return Wheather empty fields should be shown
311 */ 319 */
312 bool showEmptyFields() const; 320 bool showEmptyFields() const;
313 321
314 /** @return the advisory internal margin in items. Setting a value above 1 means 322 /** @return the advisory internal margin in items. Setting a value above 1 means
315 * a space between the item contents and the focus recttangle drawn around 323 * a space between the item contents and the focus recttangle drawn around
316 * the current item. The default value is 0. 324 * the current item. The default value is 0.
317 * The value should be used by CardViewItem and derived classes. 325 * The value should be used by CardViewItem and derived classes.
318 * Note that this should not be greater than half of the minimal item width, 326 * Note that this should not be greater than half of the minimal item width,
319 * which is 80. It is currently not checked, so setting a value greater than 40 327 * which is 80. It is currently not checked, so setting a value greater than 40
320 * will probably mean a crash in the items painting routine. 328 * will probably mean a crash in the items painting routine.
321 * @private Note: I looked for a value in QStyle::PixelMetric to use, but I could 329 * @private Note: I looked for a value in QStyle::PixelMetric to use, but I could
322 * not see a usefull one. One may turn up in a future version of Qt. 330 * not see a usefull one. One may turn up in a future version of Qt.
323 */ 331 */
324 uint itemMargin(); 332 uint itemMargin();
325 333
326 /** Sets the internal item margin. @see itemMargin(). 334 /** Sets the internal item margin. @see itemMargin().
327 */ 335 */
328 void setItemMargin( uint margin ); 336 void setItemMargin( uint margin );
329 337
330 /** @return the item spacing. 338 /** @return the item spacing.
331 * The item spacing is the space (in pixels) between each item in a 339 * The item spacing is the space (in pixels) between each item in a
332 * column, between the items and column separators if drawn, and between 340 * column, between the items and column separators if drawn, and between
333 * the items and the borders of the widget. The default value is set to 341 * the items and the borders of the widget. The default value is set to
334 * 10. 342 * 10.
335 * @private Note: There is no usefull QStyle::PixelMetric to use for this atm. 343 * @private Note: There is no usefull QStyle::PixelMetric to use for this atm.
336 * An option would be using KDialog::spacingHint(). 344 * An option would be using KDialog::spacingHint().
337 */ 345 */
338 uint itemSpacing(); 346 uint itemSpacing();
339 347
340 /** Sets the item spacing. 348 /** Sets the item spacing.
341 * @see itemSpacing() 349 * @see itemSpacing()
342 */ 350 */
343 void setItemSpacing( uint spacing ); 351 void setItemSpacing( uint spacing );