Diffstat (limited to 'kaddressbook/views/cardview.h') (more/less context) (ignore whitespace changes)
-rw-r--r-- | kaddressbook/views/cardview.h | 473 |
1 files changed, 473 insertions, 0 deletions
diff --git a/kaddressbook/views/cardview.h b/kaddressbook/views/cardview.h new file mode 100644 index 0000000..37dddb6 --- a/dev/null +++ b/kaddressbook/views/cardview.h | |||
@@ -0,0 +1,473 @@ | |||
1 | #ifndef CARDVIEW_H | ||
2 | #define CARDVIEW_H | ||
3 | |||
4 | #include <qscrollview.h> | ||
5 | #include <qptrlist.h> | ||
6 | #include <qstring.h> | ||
7 | #include <qrect.h> | ||
8 | #include <qpair.h> | ||
9 | #include <qpoint.h> | ||
10 | |||
11 | class QLabel; | ||
12 | class QPainter; | ||
13 | class QResizeEvent; | ||
14 | class QMouseEvent; | ||
15 | class CardView; | ||
16 | class CardViewPrivate; | ||
17 | class CardViewItemPrivate; | ||
18 | class CardViewTip; | ||
19 | |||
20 | /** 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 | ||
22 | * card should be unique, since they will be used to index the values. | ||
23 | */ | ||
24 | class CardViewItem | ||
25 | { | ||
26 | friend class CardView; | ||
27 | |||
28 | public: | ||
29 | /** A single field in the card view. The first item is the label | ||
30 | * and the second item is the value. | ||
31 | */ | ||
32 | typedef QPair<QString, QString> Field; | ||
33 | |||
34 | /** Constructor. | ||
35 | * | ||
36 | * @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 | ||
38 | * appear at the top of the card. This is also the string that will | ||
39 | * be used to sort the cards in the view. | ||
40 | */ | ||
41 | CardViewItem(CardView *parent, QString caption = QString::null); | ||
42 | virtual ~CardViewItem(); | ||
43 | |||
44 | /** @return The caption of the card, or QString::null if none was ever | ||
45 | * set. | ||
46 | */ | ||
47 | const QString &caption() const; | ||
48 | |||
49 | /** 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 | ||
51 | * be used to sort the cards in the view. | ||
52 | */ | ||
53 | void setCaption(const QString &caption); | ||
54 | |||
55 | /** Paints the card using the given painter and color group. The | ||
56 | * card will handle painting itself selected if it is selected. | ||
57 | */ | ||
58 | virtual void paintCard(QPainter *p, QColorGroup &cg); | ||
59 | |||
60 | /** Repaints the card. This is done by sending a repaint event to the | ||
61 | * view with the clip rect defined as this card. | ||
62 | */ | ||
63 | virtual void repaintCard(); | ||
64 | |||
65 | /** Adds a field to the card. | ||
66 | * | ||
67 | * @param label The label of the field. The field labels must be unique | ||
68 | * within a card. | ||
69 | * @param The value of the field. | ||
70 | */ | ||
71 | void insertField(const QString &label, const QString &value); | ||
72 | |||
73 | /** Removes the field with label <i>label</i> from the card. | ||
74 | */ | ||
75 | void removeField(const QString &label); | ||
76 | |||
77 | /** @return The value of the field with label <i>label</i>. | ||
78 | */ | ||
79 | QString fieldValue(const QString &label); | ||
80 | |||
81 | /** Removes all the fields from this card. | ||
82 | */ | ||
83 | void clearFields(); | ||
84 | |||
85 | /** @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 | ||
87 | * last card. | ||
88 | */ | ||
89 | CardViewItem *nextItem(); | ||
90 | |||
91 | /** @return True if this card is currently selected, false otherwise. | ||
92 | */ | ||
93 | bool isSelected() const; | ||
94 | |||
95 | /** 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 | ||
97 | * (trimmed) make the label display the full text. | ||
98 | */ | ||
99 | void showFullString( const QPoint &pos, CardViewTip *tip ); | ||
100 | |||
101 | /** @return a pointer to the Field at the position itempos | ||
102 | * in this item. 0 is returned if itempos is in the caption. | ||
103 | * @param itempos the position in item coordinates | ||
104 | */ | ||
105 | Field *fieldAt( const QPoint &itempos ) const; | ||
106 | |||
107 | CardView *cardView() { return mView; }; | ||
108 | |||
109 | /** @return The height of this item as rendered, in pixels. | ||
110 | |||
111 | if @p allowCache is true, the item may use an internally | ||
112 | cached value rather than recalculating from scratch. The | ||
113 | argument is mainly to allow the cardView to change global settings (like | ||
114 | maxFieldLines) that might influence the items heights | ||
115 | */ | ||
116 | int height( bool allowCache=true ) const; | ||
117 | |||
118 | protected: | ||
119 | /** Sets the card as selected. This is usually only called from the | ||
120 | * card view. | ||
121 | */ | ||
122 | void setSelected(bool selected); | ||
123 | |||
124 | private: | ||
125 | /** Sets the default values. | ||
126 | */ | ||
127 | void initialize(); | ||
128 | |||
129 | /** 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 | ||
131 | * <i>width</i>, then the string will be trimmed and a '...' will | ||
132 | * be appended. | ||
133 | */ | ||
134 | QString trimString(const QString &text, int width, QFontMetrics &fm); | ||
135 | |||
136 | CardViewItemPrivate *d; | ||
137 | CardView *mView; | ||
138 | }; | ||
139 | |||
140 | /** 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 | ||
142 | * 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 | ||
144 | * caption. | ||
145 | * | ||
146 | * The CardView class is designed to mirror the API of the QListView or | ||
147 | * QIconView. The CardView is also completely independant of KAddressBook and | ||
148 | * can be used elsewhere. With the exception of a few simple config checks, | ||
149 | * the CardView is also 100% independant of KDE. | ||
150 | */ | ||
151 | class CardView : public QScrollView | ||
152 | { | ||
153 | friend class CardViewItem; | ||
154 | |||
155 | Q_OBJECT | ||
156 | |||
157 | public: | ||
158 | /** Constructor. | ||
159 | */ | ||
160 | CardView(QWidget *parent, const char *name); | ||
161 | virtual ~CardView(); | ||
162 | |||
163 | /** 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 | ||
165 | * inserted, the CardView takes ownership of the item. | ||
166 | */ | ||
167 | void insertItem(CardViewItem *item); | ||
168 | |||
169 | /** Takes the item from the view. The item will not be deleted and | ||
170 | * ownership of the item is returned to the caller. | ||
171 | */ | ||
172 | void takeItem(CardViewItem *item); | ||
173 | |||
174 | /** Clears the view and deletes all card view items | ||
175 | */ | ||
176 | void clear(); | ||
177 | |||
178 | /** @return The current item, the item that has the focus. | ||
179 | * Whenever the view has focus, this item has a focus rectangle painted | ||
180 | * at it's border. | ||
181 | * @sa setCurrentItem() | ||
182 | */ | ||
183 | CardViewItem *currentItem(); | ||
184 | |||
185 | /** Sets the CardViewItem @p item to the current item in the view. | ||
186 | */ | ||
187 | void setCurrentItem( CardViewItem *item ); | ||
188 | |||
189 | /** @return The item found at the given point, or 0 if there is no item | ||
190 | * at that point. | ||
191 | */ | ||
192 | CardViewItem *itemAt(const QPoint &viewPos); | ||
193 | |||
194 | /** @return The bounding rect of the given item. | ||
195 | */ | ||
196 | QRect itemRect(const CardViewItem *item); | ||
197 | |||
198 | /** Ensures that the given item is in the viewable area of the widget | ||
199 | */ | ||
200 | void ensureItemVisible(const CardViewItem *item); | ||
201 | |||
202 | /** Repaints the given item. | ||
203 | */ | ||
204 | void repaintItem(const CardViewItem *item); | ||
205 | |||
206 | enum SelectionMode { Single, Multi, Extended, NoSelection }; | ||
207 | |||
208 | /** Sets the selection mode. | ||
209 | * | ||
210 | * @see QListView | ||
211 | */ | ||
212 | void setSelectionMode(SelectionMode mode); | ||
213 | |||
214 | /** @return The current selection mode. | ||
215 | */ | ||
216 | SelectionMode selectionMode() const; | ||
217 | |||
218 | /** Selects or deselects the given item. This method honors the current | ||
219 | * selection mode, so if other items are selected, they may be unselected. | ||
220 | */ | ||
221 | void setSelected(CardViewItem *item, bool selected); | ||
222 | |||
223 | /** Selects or deselects all items. | ||
224 | */ | ||
225 | void selectAll(bool state); | ||
226 | |||
227 | /** @return True if the given item is selected, false otherwise. | ||
228 | */ | ||
229 | bool isSelected(CardViewItem *item) const; | ||
230 | |||
231 | /** @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 | ||
233 | * item, but others may exist. 0 if no item is selected. | ||
234 | */ | ||
235 | CardViewItem *selectedItem() const; | ||
236 | |||
237 | /** @return The first item in the view. This may be 0 if no items have | ||
238 | * been inserted. This method combined with CardViewItem::nextItem() | ||
239 | * can be used to iterator through the list of items. | ||
240 | */ | ||
241 | CardViewItem *firstItem() const; | ||
242 | |||
243 | /** @return The item after the given item or 0 if the item is the last | ||
244 | * item. | ||
245 | */ | ||
246 | CardViewItem *itemAfter(CardViewItem *item); | ||
247 | |||
248 | /** @return The number of items in the view. | ||
249 | */ | ||
250 | int childCount() const; | ||
251 | |||
252 | /** Attempts to find the first item matching the params. | ||
253 | * | ||
254 | * @param text The text to match. | ||
255 | * @param label The label of the field to match against. | ||
256 | * @param compare The compare method to use in doing the search. | ||
257 | * | ||
258 | * @return The first matching item, or 0 if no items match. | ||
259 | */ | ||
260 | /*US | ||
261 | CardViewItem *findItem(const QString &text, const QString &label, | ||
262 | Qt::StringComparisonMode compare = Qt::BeginsWith); | ||
263 | */ | ||
264 | |||
265 | /** Returns the amounts of pixels required for one column. | ||
266 | * This depends on wheather drawSeparators is enabled: | ||
267 | * If so, it is itemWidth + 2*itemSpacing + separatorWidth | ||
268 | * If not, it is itemWidth + itemSpacing | ||
269 | * @see itemWidth(), setItemWidth(), itemSpacing() and setItemSpacing() | ||
270 | */ | ||
271 | uint columnWidth(); | ||
272 | |||
273 | /** 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 | ||
275 | * a card is highlighted and when it isn't. | ||
276 | */ | ||
277 | void setDrawCardBorder(bool enabled); | ||
278 | |||
279 | /** @return True if borders are drawn, false otherwise. | ||
280 | */ | ||
281 | bool drawCardBorder() const; | ||
282 | |||
283 | /** 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 | ||
285 | * columns in the list view. The separator is just for esthetics and it | ||
286 | * does not serve a functional purpose. | ||
287 | */ | ||
288 | void setDrawColSeparators(bool enabled); | ||
289 | |||
290 | /** @return True if column separators are drawn, false otherwise. | ||
291 | */ | ||
292 | bool drawColSeparators() const; | ||
293 | |||
294 | /** Sets if the field labels should be drawn. The field labels are the | ||
295 | * unique strings used to identify the fields. Sometimes drawing these | ||
296 | * labels makes sense as a source of clarity for the user, othertimes they | ||
297 | * waste too much space and do not assist the user. | ||
298 | */ | ||
299 | void setDrawFieldLabels(bool enabled); | ||
300 | |||
301 | /** @return True if the field labels are drawn, false otherwise. | ||
302 | */ | ||
303 | bool drawFieldLabels() const; | ||
304 | |||
305 | /** Sets if fields with no value should be drawn (of cause the label only, | ||
306 | * but it allows for embedded editing sometimes...) | ||
307 | */ | ||
308 | void setShowEmptyFields(bool show); | ||
309 | |||
310 | /** @return Wheather empty fields should be shown | ||
311 | */ | ||
312 | bool showEmptyFields() const; | ||
313 | |||
314 | /** @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 | ||
316 | * the current item. The default value is 0. | ||
317 | * 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, | ||
319 | * 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. | ||
321 | * @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. | ||
323 | */ | ||
324 | uint itemMargin(); | ||
325 | |||
326 | /** Sets the internal item margin. @see itemMargin(). | ||
327 | */ | ||
328 | void setItemMargin( uint margin ); | ||
329 | |||
330 | /** @return the item spacing. | ||
331 | * 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 | ||
333 | * the items and the borders of the widget. The default value is set to | ||
334 | * 10. | ||
335 | * @private Note: There is no usefull QStyle::PixelMetric to use for this atm. | ||
336 | * An option would be using KDialog::spacingHint(). | ||
337 | */ | ||
338 | uint itemSpacing(); | ||
339 | |||
340 | /** Sets the item spacing. | ||
341 | * @see itemSpacing() | ||
342 | */ | ||
343 | void setItemSpacing( uint spacing ); | ||
344 | |||
345 | /** @return the width made available to the card items. */ | ||
346 | int itemWidth() const; | ||
347 | |||
348 | /** Sets the width made available to card items. */ | ||
349 | void setItemWidth( int width ); | ||
350 | |||
351 | /** Sets the header font */ | ||
352 | void setHeaderFont( const QFont &fnt ); | ||
353 | |||
354 | /** @return the header font */ | ||
355 | QFont headerFont() const; | ||
356 | |||
357 | /** @reimp */ | ||
358 | void setFont( const QFont &fnt ); | ||
359 | |||
360 | /** Sets the column separator width */ | ||
361 | void setSeparatorWidth( int width ); | ||
362 | |||
363 | /** @return the column separator width */ | ||
364 | int separatorWidth(); | ||
365 | |||
366 | /** Sets the maximum number of lines to display pr field. | ||
367 | If set to 0 (the default) all lines will be displayed. | ||
368 | */ | ||
369 | void setMaxFieldLines( int howmany ); | ||
370 | |||
371 | /** @return the maximum number of lines pr field */ | ||
372 | int maxFieldLines() const; | ||
373 | |||
374 | signals: | ||
375 | /** Emitted whenever the selection changes. This means a user highlighted | ||
376 | * a new item or unhighlighted a currently selected item. | ||
377 | */ | ||
378 | void selectionChanged(); | ||
379 | |||
380 | /** Same as above method, only it carries the item that was selected. This | ||
381 | * method will only be emitted in single select mode, since it defineds | ||
382 | * which item was selected. | ||
383 | */ | ||
384 | void selectionChanged(CardViewItem *); | ||
385 | |||
386 | /** This method is emitted whenever an item is clicked. | ||
387 | */ | ||
388 | void clicked(CardViewItem *); | ||
389 | |||
390 | /** Emitted whenever the user 'executes' an item. This is dependant on | ||
391 | * the KDE global config. This could be a single click or a doubleclick. | ||
392 | * Also emitted when the return key is pressed on an item. | ||
393 | */ | ||
394 | void executed(CardViewItem *); | ||
395 | |||
396 | /** Emitted whenever the user double clicks on an item. | ||
397 | */ | ||
398 | void doubleClicked(CardViewItem *); | ||
399 | |||
400 | /** Emitted when the current item changes | ||
401 | */ | ||
402 | void currentChanged( CardViewItem * ); | ||
403 | |||
404 | /** Emitted when the return key is pressed in an item. | ||
405 | */ | ||
406 | void returnPressed( CardViewItem * ); | ||
407 | |||
408 | protected: | ||
409 | /** Determines which cards intersect that region and tells them to paint | ||
410 | * themselves. | ||
411 | */ | ||
412 | void drawContents(QPainter *p, int clipx, int clipy, int clipw, int cliph); | ||
413 | |||
414 | /** Sets the layout to dirty and repaints. | ||
415 | */ | ||
416 | void resizeEvent(QResizeEvent *e); | ||
417 | |||
418 | /** Changes the direction the canvas scolls. | ||
419 | */ | ||
420 | void contentsWheelEvent(QWheelEvent *e); | ||
421 | |||
422 | /** Sets the layout to dirty and calls for a repaint. | ||
423 | */ | ||
424 | void setLayoutDirty(bool dirty); | ||
425 | |||
426 | /** Does the math based on the bounding rect of the cards to properly | ||
427 | * lay the cards out on the screen. This is only done if the layout is | ||
428 | * marked as dirty. | ||
429 | */ | ||
430 | void calcLayout(); | ||
431 | |||
432 | // virtual void mousePressEvent(QMouseEvent *e); | ||
433 | // virtual void mouseReleaseEvent(QMouseEvent *e); | ||
434 | // virtual void mouseMoveEvent(QMouseEvent *e); | ||
435 | |||
436 | virtual void contentsMousePressEvent(QMouseEvent *e); | ||
437 | virtual void contentsMouseMoveEvent(QMouseEvent *e); | ||
438 | virtual void contentsMouseReleaseEvent(QMouseEvent *e); | ||
439 | virtual void contentsMouseDoubleClickEvent(QMouseEvent *e); | ||
440 | |||
441 | virtual void enterEvent( QEvent * ); | ||
442 | virtual void leaveEvent( QEvent * ); | ||
443 | |||
444 | virtual void focusInEvent( QFocusEvent * ); | ||
445 | virtual void focusOutEvent( QFocusEvent * ); | ||
446 | |||
447 | virtual void keyPressEvent( QKeyEvent * ); | ||
448 | |||
449 | /** Overload this method to be told when a drag should be started. | ||
450 | * In most cases you will want to start a drag event with the currently | ||
451 | * selected item. | ||
452 | */ | ||
453 | virtual void startDrag(); | ||
454 | |||
455 | private slots: | ||
456 | /** Called by a timer to display a label with truncated text. | ||
457 | * Pop up a label, if there is a field with obscured text or | ||
458 | * label at the cursor position. | ||
459 | */ | ||
460 | void tryShowFullText(); | ||
461 | |||
462 | private: | ||
463 | /** draws and erases the rubber bands while columns are resized. | ||
464 | * @p pos is the horizontal position inside the viewport to use as | ||
465 | * the anchor. | ||
466 | * If pos is 0, only erase is done. | ||
467 | */ | ||
468 | void drawRubberBands( int pos ); | ||
469 | |||
470 | CardViewPrivate *d; | ||
471 | }; | ||
472 | |||
473 | #endif | ||