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.h473
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
11class QLabel;
12class QPainter;
13class QResizeEvent;
14class QMouseEvent;
15class CardView;
16class CardViewPrivate;
17class CardViewItemPrivate;
18class 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*/
24class 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*/
151class 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