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,247 +1,255 @@
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