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
34class QAction;
35class KIconThemeDir;
36class 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 */
46class KDEUI_EXPORT KIconTheme
47{
48public:
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 ContextMenus { TextEditor,
203 ReadOnlyText };
204
205 /**
206 * Assigns standard icons to the various standard text edit context menus.
207 */
208 static void assignIconsToContextMenu(ContextMenus type, QList<QAction*> actions);
209
210private:
211 class KIconThemePrivate;
212 KIconThemePrivate * const d;
213};
214
215#endif
216