summaryrefslogtreecommitdiffabout
path: root/kaddressbook/kaddressbookview.h
authorzautrix <zautrix>2004-06-26 19:01:18 (UTC)
committer zautrix <zautrix>2004-06-26 19:01:18 (UTC)
commitb9aad1f15dc600e4dbe4c62d3fcced6363188ba3 (patch) (unidiff)
tree2c3d4004fb21c72cba65793859f9bcd8ffd3a49c /kaddressbook/kaddressbookview.h
downloadkdepimpi-b9aad1f15dc600e4dbe4c62d3fcced6363188ba3.zip
kdepimpi-b9aad1f15dc600e4dbe4c62d3fcced6363188ba3.tar.gz
kdepimpi-b9aad1f15dc600e4dbe4c62d3fcced6363188ba3.tar.bz2
Initial revision
Diffstat (limited to 'kaddressbook/kaddressbookview.h') (more/less context) (ignore whitespace changes)
-rw-r--r--kaddressbook/kaddressbookview.h295
1 files changed, 295 insertions, 0 deletions
diff --git a/kaddressbook/kaddressbookview.h b/kaddressbook/kaddressbookview.h
new file mode 100644
index 0000000..7457080
--- a/dev/null
+++ b/kaddressbook/kaddressbookview.h
@@ -0,0 +1,295 @@
1/*
2 This file is part of KAddressBook.
3 Copyright (c) 2002 Mike Pilone <mpilone@slac.com>
4
5 This program is free software; you can redistribute it and/or modify
6 it under the terms of the GNU General Public License as published by
7 the Free Software Foundation; either version 2 of the License, or
8 (at your option) any later version.
9
10 This program is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 GNU General Public License for more details.
14
15 You should have received a copy of the GNU General Public License
16 along with this program; if not, write to the Free Software
17 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
18
19 As a special exception, permission is given to link this program
20 with any edition of Qt, and distribute the resulting executable,
21 without including the source code for Qt in the source distribution.
22*/
23
24#ifndef KADDRESSBOOKVIEW_H
25#define KADDRESSBOOKVIEW_H
26
27#ifndef KAB_EMBEDDED
28#include <klibloader.h>
29#endif //KAB_EMBEDDED
30
31class KConfig;
32class QDropEvent;
33
34#include <qstringlist.h>
35#include <kabc/field.h>
36#include <qwidget.h>
37
38#include "viewconfigurewidget.h"
39#include "filter.h"
40
41namespace KABC { class AddressBook; }
42
43/**
44 Base class for all views in kaddressbook. This class implements
45 all the common methods needed to provide a view to the user.
46
47 To implement a specific view (table, card, etc), just inherit from
48 this class and implement all the pure virtuals.
49
50 @author Mike Pilone <mpilone@slac.com>
51 */
52class KAddressBookView : public QWidget
53{
54 Q_OBJECT
55
56 public:
57 enum DefaultFilterType { None = 0, Active = 1, Specific = 2 };
58
59 KAddressBookView( KABC::AddressBook *ab, QWidget *parent, const char *name );
60 virtual ~KAddressBookView();
61
62 /**
63 Must be overloaded in subclasses. Should return a list of
64 all the uids of selected contacts.
65 */
66 virtual QStringList selectedUids() = 0;
67
68 /**
69 Called whenever this view should read the config. This can be used
70 as a sign that the config has changed, therefore the view should
71 assume the worst and rebuild itself if necessary. For example,
72 in a table view this method may be called when the user adds or
73 removes columns from the view.
74
75 If overloaded in the subclass, do not forget to call super class's
76 method.
77
78 @param config The KConfig object to read from. The group will already
79 be set, so do not change the group.
80 */
81 virtual void readConfig( KConfig *config );
82
83 /**
84 Called whenever this view should write the config. The view should not
85 write out information handled by the application, such as which fields
86 are visible. The view should only write out information specific
87 to itself (i.e.: All information in the ViewConfigWidget)
88
89 If overloaded in the subclass, do not forget to call the super class's
90 method.
91
92 @param config The KConfig object to read from. The group will already
93 be set, so do not change the group.
94 */
95 virtual void writeConfig( KConfig *config );
96
97 /**
98 Returns a QString with all the selected email addresses concatenated
99 together with a ',' seperator.
100 */
101 virtual QString selectedEmails();
102
103 /**
104 Return the type of the view: Icon, Table, etc. Please make sure that
105 this is the same value that ViewWrapper::type() will return for your
106 view.
107 */
108 virtual QString type() const = 0;
109
110 /**
111 Returns a list of the fields that should be displayed. The list
112 is composed of the fields proper names (ie: Home Address), so
113 the view may need to translate them in order to get the
114 value from the addressee.
115
116 This list is generated from the config file, so it is advisable to call
117 this method whenever a readConfig() is called in order to get the newest
118 list of fields.
119 */
120 KABC::Field::List fields() const;
121
122 /**
123 Sets the active filter. This filter will be used for filtering
124 the list of addressees to display. The view will <b>not</b>
125 automatically refresh itself, so in most cases you will want to call
126 KAddressBookView::refresh() after this method.
127 */
128 void setFilter( const Filter& );
129
130 /**
131 @return The default filter type selection. If the selection
132 is SpecificFilter, the name of the filter can be retrieved with
133 defaultFilterName()
134 */
135 DefaultFilterType defaultFilterType() const;
136
137 /**
138 @return The name of the default filter. This string is
139 only valid if defaultFilterType() is returning SpecificFilter.
140 */
141 const QString &defaultFilterName() const;
142
143 /**
144 @return The address book.
145 */
146 KABC::AddressBook *addressBook() const;
147
148 public slots:
149 /**
150 Must be overloaded in subclasses to refresh the view.
151 Refreshing includes updating the view to ensure that only items
152 in the document are visible. If <i>uid</i> is valid, only the
153 addressee with uid needs to be refreshed. This is an optimization
154 only.
155 */
156 virtual void refresh( QString uid = QString::null ) = 0;
157
158 /**
159 This method must be overloaded in subclasses. Select (highlight)
160 the addressee matching <i>uid</i>. If uid
161 is equal to QString::null, then all addressees should be selected.
162 */
163#ifndef KAB_EMBEDDED
164//MOC_SKIP_BEGIN
165 virtual void setSelected( QString uid = QString::null, bool selected = true ) = 0;
166//MOC_SKIP_END
167#else //KAB_EMBEDDED
168 //US my moc can not handle the default parameters. Is this a problem ???
169 virtual void setSelected( QString uid, bool selected) = 0;
170#endif //KAB_EMBEDDED
171
172 signals:
173 /**
174 This signal should be emitted by a subclass whenever an addressee
175 is modified.
176 */
177 void modified();
178
179 /**
180 This signal should be emitted by a subclass whenever an addressee
181 is selected. Selected means that the addressee was given the focus.
182 Some widgets may call this 'highlighted'. The view is responsible for
183 emitting this signal multiple times if multiple items are selected,
184 with the last item selected being the last emit.
185
186 @param uid The uid of the selected addressee.
187
188 @see KListView
189 */
190 void selected( const QString &uid );
191 void deleteRequest();
192 /**
193 This signal should be emitted by a subclass whenever an addressee
194 is executed. This is defined by the KDE system wide config, but it
195 either means single or doubleclicked.
196
197 @param ui The uid of the selected addressee
198
199 @see KListView
200 */
201 void executed( const QString &uid );
202
203 /**
204 This signal is emitted whenever a user attempts to start a drag
205 in the view. The slot connected to this signal would usually want
206 to create a QDragObject.
207 */
208 void startDrag();
209
210 /**
211 This signal is emitted whenever the user drops something on the
212 view. The individual view should handle checking if the item is
213 droppable (ie: if it is a vcard).
214 */
215 void dropped( QDropEvent* );
216
217 protected:
218 /**
219 Returns a list of the addressees that should be displayed. This method
220 should always be used by the subclass to get a list of addressees. This
221 method internally takes many factors into account, including the current
222 filter.
223 */
224 KABC::Addressee::List addressees();
225
226 /**
227 This method returns the widget that should be used as the parent for
228 all view components. By using this widget as the parent and not
229 'this', the view subclass has the option of placing other widgets
230 around the view (ie: search fields, etc). Do not delete this widget!
231 */
232 QWidget *viewWidget();
233
234 private:
235 void initGUI();
236
237 DefaultFilterType mDefaultFilterType;
238 Filter mFilter;
239 QString mDefaultFilterName;
240 KABC::AddressBook *mAddressBook;
241 KABC::Field::List mFieldList;
242
243 QWidget *mViewWidget;
244};
245
246#ifndef KAB_EMBEDDED
247//MOC_SKIP_BEGIN
248class ViewFactory : public KLibFactory
249//MOC_SKIP_END
250#else //KAB_EMBEDDED
251class ViewFactory
252#endif //KAB_EMBEDDED
253{
254
255 public:
256 virtual KAddressBookView *view( KABC::AddressBook *ab, QWidget *parent,
257 const char *name = 0 ) = 0;
258
259 /**
260 @return The type of the view. This is normally a small one word
261 string (ie: Table, Icon, Tree, etc).
262 */
263 virtual QString type() const = 0;
264
265 /**
266 @return The description of the view. This should be a 3 to
267 4 line string (don't actually use return characters in the string)
268 describing the features offered by the view.
269 */
270 virtual QString description() const = 0;
271
272 /**
273 Creates a config dialog for the view type. The default
274 implementation will return a ViewConfigDialog. This default
275 dialog will allow the user to set the visible fields only. If
276 you need more config options (as most views will), this method
277 can be overloaded to return your sublcass of ViewConfigDialog.
278 If this method is over loaded the base classes method should
279 <B>not</B> be called.
280 */
281 virtual ViewConfigureWidget *configureWidget( KABC::AddressBook *ab,
282 QWidget *parent,
283 const char *name = 0 );
284
285 protected:
286 virtual QObject* createObject( QObject*, const char*, const char*,
287 const QStringList & )
288 {
289 return 0;
290 }
291
292};
293
294
295#endif