1/* vi: ts=8 sts=4 sw=4
2
3 This file is part of the KDE project, module kfile.
4 SPDX-FileCopyrightText: 2000 Geert Jansen <jansen@kde.org>
5 SPDX-FileCopyrightText: 2000 Kurt Granroth <granroth@kde.org>
6 SPDX-FileCopyrightText: 1997 Christoph Neerfeld <chris@kde.org>
7 SPDX-FileCopyrightText: 2002 Carsten Pfeiffer <pfeiffer@kde.org>
8 SPDX-FileCopyrightText: 2021 Kai Uwe Broulik <kde@broulik.de>
9
10 SPDX-License-Identifier: LGPL-2.0-only
11*/
12
13#ifndef KICONDIALOG_H
14#define KICONDIALOG_H
15
16#include "kiconwidgets_export.h"
17
18#include <QDialog>
19#include <QPushButton>
20#include <memory>
21
22#include <kiconloader.h>
23
24/**
25 * @class KIconDialog kicondialog.h KIconDialog
26 *
27 * Dialog for interactive selection of icons. Use the function
28 * getIcon() to let the user select an icon.
29 *
30 * @short An icon selection dialog.
31 */
32class KICONWIDGETS_EXPORT KIconDialog : public QDialog
33{
34 Q_OBJECT
35
36public:
37 /**
38 * Constructs an icon selection dialog using the global icon loader.
39 *
40 * @param parent The parent widget.
41 */
42 explicit KIconDialog(QWidget *parent = nullptr);
43
44 /**
45 * Destructs the dialog.
46 */
47 ~KIconDialog() override;
48
49 /**
50 * Sets a strict icon size policy for allowed icons.
51 *
52 * @param policy When true, only icons of the specified group's
53 * size in getIcon() are shown.
54 * When false, icons not available at the desired group's size will
55 * also be selectable.
56 */
57 void setStrictIconSize(bool policy);
58 /**
59 * Returns true if a strict icon size policy is set.
60 */
61 bool strictIconSize() const;
62
63 /**
64 * Sets the location of the custom icon directory. Only local directory
65 * paths are allowed.
66 */
67 void setCustomLocation(const QString &location);
68
69 /**
70 * Sets the size of the icons to be shown / selected.
71 * @see KIconLoader::StdSizes
72 * @see iconSize
73 */
74 void setIconSize(int size);
75 /**
76 * Returns the icon size set via setIconSize() or 0, if the default
77 * icon size will be used.
78 */
79 int iconSize() const;
80
81 /**
82 * Sets the icon that is initially selected in the dialog.
83 *
84 * @note Changing this after the dialog has been shown has no effect.
85 * @note If the given icon cannot be found in the current context,
86 * no icon will be selected.
87 * @param iconName The name of the icon to select
88 * @since 5.89
89 */
90 void setSelectedIcon(const QString &iconName);
91
92 /**
93 * Allows you to set the same parameters as in the class method
94 * getIcon(), as well as two additional parameters to lock
95 * the choice between system and user directories and to lock the
96 * custom icon directory itself.
97 */
98 void setup(KIconLoader::Group group,
99 KIconLoader::Context context = KIconLoader::Application,
100 bool strictIconSize = false,
101 int iconSize = 0,
102 bool user = false,
103 bool lockUser = false,
104 bool lockCustomDir = false);
105
106 /**
107 * exec()utes this modal dialog and returns the name of the selected icon,
108 * or QString() if the dialog was aborted.
109 * @returns the name of the icon, suitable for loading with KIconLoader.
110 * @see getIcon
111 */
112 QString openDialog();
113
114 /**
115 * show()s this dialog and emits a newIconName(const QString&) signal when
116 * successful. QString() will be emitted if the dialog was aborted.
117 */
118 void showDialog();
119
120 /**
121 * Pops up the dialog an lets the user select an icon.
122 *
123 * @param group The icon group this icon is intended for. Providing the
124 * group shows the icons in the dialog with the same appearance as when
125 * used outside the dialog.
126 * @param context The initial icon context. Initially, the icons having
127 * this context are shown in the dialog. The user can change this.
128 * @param strictIconSize When true, only icons of the specified group's size
129 * are shown, otherwise icon not available in the desired group's size
130 * will also be selectable.
131 * @param iconSize the size of the icons -- the default of the icon group
132 * if set to 0
133 * @param user Begin with the "user icons" instead of "system icons".
134 * @param parent The parent widget of the dialog.
135 * @param title The title to use for the dialog.
136 * @return The name of the icon, suitable for loading with KIconLoader.
137 */
138 static QString getIcon(KIconLoader::Group group = KIconLoader::Desktop,
139 KIconLoader::Context context = KIconLoader::Application,
140 bool strictIconSize = false,
141 int iconSize = 0,
142 bool user = false,
143 QWidget *parent = nullptr,
144 const QString &title = QString());
145
146Q_SIGNALS:
147 void newIconName(const QString &iconName);
148
149protected:
150 void showEvent(QShowEvent *event) override;
151
152protected Q_SLOTS:
153 void slotOk();
154
155private:
156 std::unique_ptr<class KIconDialogPrivate> const d;
157
158 friend class KIconDialogPrivate;
159
160 Q_DISABLE_COPY(KIconDialog)
161};
162
163#endif // KICONDIALOG_H
164

source code of kiconthemes/src/widgets/kicondialog.h