1/*
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
26 * \inmodule KIconWidgets
27 *
28 * \brief An icon selection dialog.
29 *
30 * Dialog for interactive selection of icons. Use the function
31 * getIcon() to let the user select an icon.
32 */
33class KICONWIDGETS_EXPORT KIconDialog : public QDialog
34{
35 Q_OBJECT
36
37public:
38 /*!
39 * Constructs an icon selection dialog using the global icon loader.
40 *
41 * \a parent The parent widget.
42 */
43 explicit KIconDialog(QWidget *parent = nullptr);
44
45 ~KIconDialog() override;
46
47 /*!
48 * Sets a strict icon size policy for allowed icons.
49 *
50 * \a policy When true, only icons of the specified group's
51 * size in getIcon() are shown.
52 *
53 * When false, icons not available at the desired group's size will
54 * also be selectable.
55 */
56 void setStrictIconSize(bool policy);
57
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 * \sa KIconLoader::StdSizes
72 * \sa 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 *
88 * \a iconName The name of the icon to select
89 * \since 5.89
90 */
91 void setSelectedIcon(const QString &iconName);
92
93 /*!
94 * Allows you to set the same parameters as in the class method
95 * getIcon(), as well as two additional parameters to lock
96 * the choice between system and user directories and to lock the
97 * custom icon directory itself.
98 */
99 void setup(KIconLoader::Group group,
100 KIconLoader::Context context = KIconLoader::Application,
101 bool strictIconSize = false,
102 int iconSize = 0,
103 bool user = false,
104 bool lockUser = false,
105 bool lockCustomDir = false);
106
107 /*!
108 * exec()utes this modal dialog and returns the name of the selected icon,
109 * or QString() if the dialog was aborted.
110 * Returns the name of the icon, suitable for loading with KIconLoader.
111 * \sa getIcon
112 */
113 QString openDialog();
114
115 /*!
116 * show()s this dialog and emits a newIconName(const QString&) signal when
117 * successful. QString() will be emitted if the dialog was aborted.
118 */
119 void showDialog();
120
121 /*!
122 * Pops up the dialog an lets the user select an icon.
123 *
124 * \a group The icon group this icon is intended for. Providing the
125 * group shows the icons in the dialog with the same appearance as when
126 * used outside the dialog.
127 *
128 * \a context The initial icon context. Initially, the icons having
129 * this context are shown in the dialog. The user can change this.
130 *
131 * \a strictIconSize When true, only icons of the specified group's size
132 * are shown, otherwise icon not available in the desired group's size
133 * will also be selectable.
134 *
135 * \a iconSize the size of the icons -- the default of the icon group
136 * if set to 0
137 *
138 * \a user Begin with the "user icons" instead of "system icons".
139 *
140 * \a parent The parent widget of the dialog.
141 *
142 * \a title The title to use for the dialog.
143 *
144 * Returns The name of the icon, suitable for loading with KIconLoader.
145 */
146 static QString getIcon(KIconLoader::Group group = KIconLoader::Desktop,
147 KIconLoader::Context context = KIconLoader::Application,
148 bool strictIconSize = false,
149 int iconSize = 0,
150 bool user = false,
151 QWidget *parent = nullptr,
152 const QString &title = QString());
153
154Q_SIGNALS:
155 /*!
156 *
157 */
158 void newIconName(const QString &iconName);
159
160protected:
161 void showEvent(QShowEvent *event) override;
162
163protected Q_SLOTS:
164 void slotOk();
165
166private:
167 std::unique_ptr<class KIconDialogPrivate> const d;
168
169 friend class KIconDialogPrivate;
170
171 Q_DISABLE_COPY(KIconDialog)
172};
173
174#endif // KICONDIALOG_H
175

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