1 | /* vi: ts=8 sts=4 sw=4 |
2 | * |
3 | * This file is part of the KDE project, module kdecore. |
4 | * Copyright (C) 2000 Geert Jansen <jansen@kde.org> |
5 | * Antonio Larrosa <larrosa@kde.org> |
6 | * |
7 | * This library is free software; you can redistribute it and/or |
8 | * modify it under the terms of the GNU Library General Public |
9 | * License version 2 as published by the Free Software Foundation. |
10 | * |
11 | * This library is distributed in the hope that it will be useful, |
12 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
13 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
14 | * Library General Public License for more details. |
15 | * |
16 | * You should have received a copy of the GNU Library General Public License |
17 | * along with this library; see the file COPYING.LIB. If not, write to |
18 | * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
19 | * Boston, MA 02110-1301, USA. |
20 | * |
21 | */ |
22 | |
23 | #ifndef KICONTHEME_H |
24 | #define KICONTHEME_H |
25 | |
26 | #include <kdeui_export.h> |
27 | |
28 | #include <QtCore/QString> |
29 | #include <QtCore/QStringList> |
30 | #include <QtCore/QList> |
31 | |
32 | #include "kiconloader.h" |
33 | |
34 | class QAction; |
35 | class KIconThemeDir; |
36 | class K3Icon; |
37 | |
38 | /** |
39 | * @internal |
40 | * Class to use/access icon themes in KDE. This class is used by the |
41 | * iconloader but can be used by others too. |
42 | * @warning You should not use this class externally. This class is exported because |
43 | * the KCM needs it. |
44 | * @see KIconLoader |
45 | */ |
46 | class KDEUI_EXPORT KIconTheme |
47 | { |
48 | public: |
49 | /** |
50 | * Load an icon theme by name. |
51 | * @param name the name of the theme (e.g. "hicolor" or "keramik") |
52 | * @param appName the name of the application. Can be null. This argument |
53 | * allows applications to have themed application icons. |
54 | */ |
55 | explicit KIconTheme(const QString& name, const QString& appName=QString()); |
56 | ~KIconTheme(); |
57 | |
58 | /** |
59 | * The stylized name of the icon theme. |
60 | * @return the (human-readable) name of the theme |
61 | */ |
62 | QString name() const; |
63 | |
64 | /** |
65 | * The internal name of the icon theme (same as the name argument passed |
66 | * to the constructor). |
67 | * @return the internal name of the theme |
68 | */ |
69 | QString internalName() const; |
70 | |
71 | /** |
72 | * A description for the icon theme. |
73 | * @return a human-readable description of the theme, QString() |
74 | * if there is none |
75 | */ |
76 | QString description() const; |
77 | |
78 | /** |
79 | * Return the name of the "example" icon. This can be used to |
80 | * present the theme to the user. |
81 | * @return the name of the example icon, QString() if there is none |
82 | */ |
83 | QString example() const; |
84 | |
85 | /** |
86 | * Return the name of the screenshot. |
87 | * @return the name of the screenshot, QString() if there is none |
88 | */ |
89 | QString screenshot() const; |
90 | |
91 | /** |
92 | * Returns the toplevel theme directory. |
93 | * @return the directory of the theme |
94 | */ |
95 | QString dir() const; |
96 | |
97 | /** |
98 | * The themes this icon theme falls back on. |
99 | * @return a list of icon themes that are used as fall-backs |
100 | */ |
101 | QStringList inherits() const; |
102 | |
103 | /** |
104 | * The icon theme exists? |
105 | * @return true if the icon theme is valid |
106 | */ |
107 | bool isValid() const; |
108 | |
109 | /** |
110 | * The icon theme should be hidden to the user? |
111 | * @return true if the icon theme is hidden |
112 | */ |
113 | bool isHidden() const; |
114 | |
115 | /** |
116 | * The minimum display depth required for this theme. This can either |
117 | * be 8 or 32. |
118 | * @return the minimum bpp (8 or 32) |
119 | */ |
120 | int depth() const; |
121 | |
122 | /** |
123 | * The default size of this theme for a certain icon group. |
124 | * @param group The icon group. See KIconLoader::Group. |
125 | * @return The default size in pixels for the given icon group. |
126 | */ |
127 | int defaultSize(KIconLoader::Group group) const; |
128 | |
129 | /** |
130 | * Query available sizes for a group. |
131 | * @param group The icon group. See KIconLoader::Group. |
132 | * @return a list of available sized for the given group |
133 | */ |
134 | QList<int> querySizes(KIconLoader::Group group) const; |
135 | |
136 | /** |
137 | * Query available icons for a size and context. |
138 | * @param size the size of the icons |
139 | * @param context the context of the icons |
140 | * @return the list of icon names |
141 | */ |
142 | QStringList queryIcons(int size, KIconLoader::Context context = KIconLoader::Any) const; |
143 | |
144 | /** |
145 | * Query available icons for a context and preferred size. |
146 | * @param size the size of the icons |
147 | * @param context the context of the icons |
148 | * @return the list of icon names |
149 | */ |
150 | QStringList queryIconsByContext(int size, KIconLoader::Context context = KIconLoader::Any) const; |
151 | |
152 | /** |
153 | * Lookup an icon in the theme. |
154 | * @param name The name of the icon, without extension. |
155 | * @param size The desired size of the icon. |
156 | * @param match The matching mode. KIconLoader::MatchExact returns an icon |
157 | * only if matches exactly. KIconLoader::MatchBest returns the best matching |
158 | * icon. |
159 | * @return A K3Icon class that describes the icon. If an icon is found, an invalid |
160 | * K3Icon object otherwise. |
161 | * @see KIconLoader::isValid will return true, and false otherwise. |
162 | */ |
163 | K3Icon iconPath(const QString& name, int size, KIconLoader::MatchType match) const; |
164 | |
165 | /** |
166 | * Returns true if the theme has any icons for the given context. |
167 | */ |
168 | bool hasContext( KIconLoader::Context context ) const; |
169 | |
170 | /** |
171 | * List all icon themes installed on the system, global and local. |
172 | * @return the list of all icon themes |
173 | */ |
174 | static QStringList list(); |
175 | |
176 | /** |
177 | * Returns the current icon theme. |
178 | * @return the name of the current theme |
179 | */ |
180 | static QString current(); |
181 | |
182 | /** |
183 | * Reconfigure the theme. |
184 | */ |
185 | static void reconfigure(); |
186 | |
187 | /** |
188 | * Returns the default icon theme. |
189 | * @return the name of the default theme name |
190 | */ |
191 | static QString defaultThemeName(); |
192 | |
193 | /** |
194 | * Defines the context menus that assignIconsToContextMenus is |
195 | * aware of. |
196 | * |
197 | * For ReadOnlyText the menu is expected to have one entry. |
198 | * |
199 | * TextEditor is expected to have the full complement of |
200 | * undo, redo, cut, copy, paste and clear. |
201 | */ |
202 | enum { , |
203 | }; |
204 | |
205 | /** |
206 | * Assigns standard icons to the various standard text edit context menus. |
207 | */ |
208 | static void (ContextMenus type, QList<QAction*> actions); |
209 | |
210 | private: |
211 | class KIconThemePrivate; |
212 | KIconThemePrivate * const d; |
213 | }; |
214 | |
215 | #endif |
216 | |