KIconThemes

kicondialog.h
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 <[email protected]>
5  SPDX-FileCopyrightText: 2000 Kurt Granroth <[email protected]>
6  SPDX-FileCopyrightText: 1997 Christoph Neerfeld <[email protected]>
7  SPDX-FileCopyrightText: 2002 Carsten Pfeiffer <[email protected]>
8  SPDX-FileCopyrightText: 2021 Kai Uwe Broulik <[email protected]>
9 
10  SPDX-License-Identifier: LGPL-2.0-only
11 */
12 
13 #ifndef KICONDIALOG_H
14 #define KICONDIALOG_H
15 
16 #include "kiconthemes_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  */
32 class KICONTHEMES_EXPORT KIconDialog : public QDialog
33 {
34  Q_OBJECT
35 
36 public:
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  * Constructs an icon selection dialog using a specific icon loader.
46  *
47  * @param loader The icon loader to use.
48  * @param parent The parent widget.
49  */
50  explicit KIconDialog(KIconLoader *loader, QWidget *parent = nullptr);
51 
52  /**
53  * Destructs the dialog.
54  */
55  ~KIconDialog() override;
56 
57  /**
58  * Sets a strict icon size policy for allowed icons.
59  *
60  * @param policy When true, only icons of the specified group's
61  * size in getIcon() are shown.
62  * When false, icons not available at the desired group's size will
63  * also be selectable.
64  */
65  void setStrictIconSize(bool policy);
66  /**
67  * Returns true if a strict icon size policy is set.
68  */
69  bool strictIconSize() const;
70 
71  /**
72  * Sets the location of the custom icon directory. Only local directory
73  * paths are allowed.
74  */
75  void setCustomLocation(const QString &location);
76 
77  /**
78  * Sets the size of the icons to be shown / selected.
79  * @see KIconLoader::StdSizes
80  * @see iconSize
81  */
82  void setIconSize(int size);
83  /**
84  * Returns the icon size set via setIconSize() or 0, if the default
85  * icon size will be used.
86  */
87  int iconSize() const;
88 
89  /**
90  * Sets the icon that is initially selected in the dialog.
91  *
92  * @note Changing this after the dialog has been shown has no effect.
93  * @note If the given icon cannot be found in the current context,
94  * no icon will be selected.
95  * @param iconName The name of the icon to select
96  * @since 5.89
97  */
98  void setSelectedIcon(const QString &iconName);
99 
100  /**
101  * Allows you to set the same parameters as in the class method
102  * getIcon(), as well as two additional parameters to lock
103  * the choice between system and user directories and to lock the
104  * custom icon directory itself.
105  */
106  void setup(KIconLoader::Group group,
108  bool strictIconSize = false,
109  int iconSize = 0,
110  bool user = false,
111  bool lockUser = false,
112  bool lockCustomDir = false);
113 
114  /**
115  * exec()utes this modal dialog and returns the name of the selected icon,
116  * or QString() if the dialog was aborted.
117  * @returns the name of the icon, suitable for loading with KIconLoader.
118  * @see getIcon
119  */
120  QString openDialog();
121 
122  /**
123  * show()s this dialog and emits a newIconName(const QString&) signal when
124  * successful. QString() will be emitted if the dialog was aborted.
125  */
126  void showDialog();
127 
128  /**
129  * Pops up the dialog an lets the user select an icon.
130  *
131  * @param group The icon group this icon is intended for. Providing the
132  * group shows the icons in the dialog with the same appearance as when
133  * used outside the dialog.
134  * @param context The initial icon context. Initially, the icons having
135  * this context are shown in the dialog. The user can change this.
136  * @param strictIconSize When true, only icons of the specified group's size
137  * are shown, otherwise icon not available in the desired group's size
138  * will also be selectable.
139  * @param iconSize the size of the icons -- the default of the icon group
140  * if set to 0
141  * @param user Begin with the "user icons" instead of "system icons".
142  * @param parent The parent widget of the dialog.
143  * @param title The title to use for the dialog.
144  * @return The name of the icon, suitable for loading with KIconLoader.
145  */
146  static QString getIcon(KIconLoader::Group group = KIconLoader::Desktop,
148  bool strictIconSize = false,
149  int iconSize = 0,
150  bool user = false,
151  QWidget *parent = nullptr,
152  const QString &title = QString());
153 
154 Q_SIGNALS:
155  void newIconName(const QString &iconName);
156 
157 protected Q_SLOTS:
158  void slotOk();
159 
160 private:
161  std::unique_ptr<class KIconDialogPrivate> const d;
162 
163  friend class ShowEventFilter;
164  friend class KIconDialogPrivate;
165 
167 
168 };
169 
170 #endif // KICONDIALOG_H
Q_SLOTSQ_SLOTS
An icon selection dialog.
Definition: kicondialog.h:32
@ Desktop
Desktop icons.
Definition: kiconloader.h:129
Q_SIGNALSQ_SIGNALS
@ Application
An icon that represents an application.
Definition: kiconloader.h:84
Context
Defines the context of the icon.
Definition: kiconloader.h:81
Group
The group of the icon.
Definition: kiconloader.h:125
Q_DISABLE_COPY(Class)
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Fri Aug 12 2022 03:55:48 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.