1/* vi: ts=8 sts=4 sw=4
2 *
3 * This file is part of the KDE project, module kfile.
4 * Copyright (C) 2000 Geert Jansen <jansen@kde.org>
5 * (C) 2000 Kurt Granroth <granroth@kde.org>
6 * (C) 1997 Christoph Neerfeld <chris@kde.org>
7 * (C) 2002 Carsten Pfeiffer <pfeiffer@kde.org>
8 *
9 * This is free software; it comes under the GNU Library General
10 * Public License, version 2. See the file "COPYING.LIB" for the
11 * exact licensing terms.
12 */
13
14#ifndef KICONDIALOG_H
15#define KICONDIALOG_H
16
17#include <kio/kio_export.h>
18
19#include <QtCore/QStringList>
20#include <QtGui/QPushButton>
21
22#include <kdialog.h>
23#include <klistwidget.h>
24
25class KIconLoader;
26
27/**
28 * Icon canvas for KIconDialog.
29 */
30class KIO_EXPORT KIconCanvas: public KListWidget
31{
32 Q_OBJECT
33
34public:
35 /**
36 * Creates a new icon canvas.
37 *
38 * @param parent The parent widget.
39 */
40 explicit KIconCanvas(QWidget *parent=0L);
41
42 /**
43 * Destroys the icon canvas.
44 */
45 ~KIconCanvas();
46
47 /**
48 * Load icons into the canvas.
49 */
50 void loadFiles(const QStringList& files);
51
52 /**
53 * Returns the current icon.
54 */
55 QString getCurrent() const;
56
57public Q_SLOTS:
58 /**
59 * Call this slot to stop the loading of the icons.
60 */
61 void stopLoading();
62
63Q_SIGNALS:
64 /**
65 * Emitted when the current icon has changed.
66 */
67 void nameChanged(const QString&);
68
69 /**
70 * This signal is emitted when the loading of the icons
71 * has started.
72 *
73 * @param count The number of icons to be loaded.
74 */
75 void startLoading(int count);
76
77 /**
78 * This signal is emitted whenever an icon has been loaded.
79 *
80 * @param number The number of the currently loaded item.
81 */
82 void progress(int number);
83
84 /**
85 * This signal is emitted when the loading of the icons
86 * has been finished.
87 */
88 void finished();
89
90private:
91 class KIconCanvasPrivate;
92 KIconCanvasPrivate* const d;
93
94 Q_DISABLE_COPY(KIconCanvas)
95
96 Q_PRIVATE_SLOT(d, void _k_slotLoadFiles())
97 Q_PRIVATE_SLOT(d, void _k_slotCurrentChanged(QListWidgetItem *item))
98};
99
100
101/**
102 * Dialog for interactive selection of icons. Use the function
103 * getIcon() let the user select an icon.
104 *
105 * @short An icon selection dialog.
106 */
107class KIO_EXPORT KIconDialog: public KDialog
108{
109 Q_OBJECT
110
111public:
112 /**
113 * Constructs an icon selection dialog using the global iconloader.
114 *
115 * @param parent The parent widget.
116 */
117 explicit KIconDialog(QWidget *parent=0L);
118
119 /**
120 * Constructs an icon selection dialog using a specific iconloader.
121 *
122 * @param loader The icon loader to use.
123 * @param parent The parent widget.
124 */
125 explicit KIconDialog(KIconLoader *loader, QWidget *parent=0);
126
127 /**
128 * Destructs the dialog.
129 */
130 ~KIconDialog();
131
132 /**
133 * Sets a strict icon size policy for allowed icons. When true,
134 * only icons of the specified group's size in getIcon() are shown.
135 * When false, icons not available at the desired group's size will
136 * also be selectable.
137 */
138 void setStrictIconSize(bool b);
139 /**
140 * Returns true if a strict icon size policy is set.
141 */
142 bool strictIconSize() const;
143 /**
144 * sets a custom icon directory
145 */
146 void setCustomLocation( const QString& location );
147
148 /**
149 * Sets the size of the icons to be shown / selected.
150 * @see KIconLoader::StdSizes
151 * @see iconSize
152 */
153 void setIconSize(int size);
154
155 /**
156 * Returns the iconsize set via setIconSize() or 0, if the default
157 * iconsize will be used.
158 */
159 int iconSize() const;
160
161 /**
162 * Allows you to set the same parameters as in the class method
163 * getIcon(), as well as two additional parameters to lock
164 * the choice between system and user dirs and to lock the custom user
165 * dir itself.
166 */
167
168 void setup( KIconLoader::Group group,
169 KIconLoader::Context context = KIconLoader::Application,
170 bool strictIconSize = false, int iconSize = 0,
171 bool user = false, bool lockUser = false,
172 bool lockCustomDir = false );
173
174 /**
175 * exec()utes this modal dialog and returns the name of the selected icon,
176 * or QString() if the dialog was aborted.
177 * @returns the name of the icon, suitable for loading with KIconLoader.
178 * @see getIcon
179 */
180 QString openDialog();
181
182 /**
183 * show()es this dialog and emits a newIcon(const QString&) signal when
184 * successful. QString() will be emitted if the dialog was aborted.
185 */
186 void showDialog();
187
188 /**
189 * Pops up the dialog an lets the user select an icon.
190 *
191 * @param group The icon group this icon is intended for. Providing the
192 * group shows the icons in the dialog with the same appearance as when
193 * used outside the dialog.
194 * @param context The initial icon context. Initially, the icons having
195 * this context are shown in the dialog. The user can change this.
196 * @param strictIconSize When true, only icons of the specified group's size
197 * are shown, otherwise icon not available in the desired group's size
198 * will also be selectable.
199 * @param iconSize the size of the icons -- the default of the icongroup
200 * if set to 0
201 * @param user Begin with the "user icons" instead of "system icons".
202 * @param parent The parent widget of the dialog.
203 * @param caption The caption to use for the dialog.
204 * @return The name of the icon, suitable for loading with KIconLoader.
205 */
206 static QString getIcon(KIconLoader::Group group=KIconLoader::Desktop,
207 KIconLoader::Context context=KIconLoader::Application,
208 bool strictIconSize=false, int iconSize = 0,
209 bool user=false, QWidget *parent=0,
210 const QString &caption=QString());
211
212Q_SIGNALS:
213 void newIconName(const QString&);
214
215protected Q_SLOTS:
216 void slotOk();
217
218private:
219 class KIconDialogPrivate;
220 KIconDialogPrivate* const d;
221
222 Q_DISABLE_COPY(KIconDialog)
223
224 Q_PRIVATE_SLOT(d, void _k_slotContext(int))
225 Q_PRIVATE_SLOT(d, void _k_slotStartLoading(int))
226 Q_PRIVATE_SLOT(d, void _k_slotProgress(int))
227 Q_PRIVATE_SLOT(d, void _k_slotFinished())
228 Q_PRIVATE_SLOT(d, void _k_slotAcceptIcons())
229 Q_PRIVATE_SLOT(d, void _k_slotBrowse())
230 Q_PRIVATE_SLOT(d, void _k_slotOtherIconClicked())
231 Q_PRIVATE_SLOT(d, void _k_slotSystemIconClicked())
232};
233
234
235/**
236 * A pushbutton for choosing an icon. Pressing on the button will open a
237 * KIconDialog for the user to select an icon. The current icon will be
238 * displayed on the button.
239 *
240 * @see KIconDialog
241 * @short A push button that allows selection of an icon.
242 */
243class KIO_EXPORT KIconButton: public QPushButton
244{
245 Q_OBJECT
246 Q_PROPERTY( QString icon READ icon WRITE setIcon RESET resetIcon )
247 Q_PROPERTY( int iconSize READ iconSize WRITE setIconSize)
248 Q_PROPERTY( bool strictIconSize READ strictIconSize WRITE setStrictIconSize )
249
250public:
251 /**
252 * Constructs a KIconButton using the global iconloader.
253 *
254 * @param parent The parent widget.
255 */
256 explicit KIconButton(QWidget *parent=0L);
257
258 /**
259 * Constructs a KIconButton using a specific KIconLoader.
260 *
261 * @param loader The icon loader to use.
262 * @param parent The parent widget.
263 */
264 KIconButton(KIconLoader *loader, QWidget *parent);
265 /**
266 * Destructs the button.
267 */
268 ~KIconButton();
269
270 /**
271 * Sets a strict icon size policy for allowed icons. When true,
272 * only icons of the specified group's size in setIconType are allowed,
273 * and only icons of that size will be shown in the icon dialog.
274 */
275 void setStrictIconSize(bool b);
276 /**
277 * Returns true if a strict icon size policy is set.
278 */
279 bool strictIconSize() const;
280
281 /**
282 * Sets the icon group and context. Use KIconLoader::NoGroup if you want to
283 * allow icons for any group in the given context.
284 */
285 void setIconType(KIconLoader::Group group, KIconLoader::Context context, bool user=false);
286
287 /**
288 * Sets the button's initial icon.
289 */
290 void setIcon(const QString& icon);
291
292 void setIcon(const QIcon& icon);
293
294 /**
295 * Resets the icon (reverts to an empty button).
296 */
297 void resetIcon();
298
299 /**
300 * Returns the name of the selected icon.
301 */
302 const QString &icon() const;
303
304 /**
305 * Sets the size of the icon to be shown / selected.
306 * @see KIconLoader::StdSizes
307 * @see iconSize
308 */
309 void setIconSize( int size );
310
311 /**
312 * Returns the iconsize set via setIconSize() or 0, if the default
313 * iconsize will be used.
314 */
315 int iconSize() const;
316
317 /**
318 * Sets the size of the icon to be shown on the button
319 * @see KIconLoader::StdSizes
320 * @see buttonIconSize
321 * @since 4.1
322 */
323 void setButtonIconSize( int size );
324
325 /**
326 * Returns the Button's Icon-Size
327 * @since 4.1
328 */
329 int buttonIconSize() const;
330
331
332Q_SIGNALS:
333 /**
334 * Emitted when the icon has changed.
335 */
336 void iconChanged(const QString &icon);
337
338private:
339 class KIconButtonPrivate;
340 KIconButtonPrivate* const d;
341
342 Q_DISABLE_COPY(KIconButton)
343
344 Q_PRIVATE_SLOT(d, void _k_slotChangeIcon())
345 Q_PRIVATE_SLOT(d, void _k_newIconName(const QString&))
346};
347
348
349#endif // KICONDIALOG_H
350