1 | /* This file is part of the KDE libraries |
2 | Copyright (C) 1999 Waldo Bastian (bastian@kde.org) |
3 | |
4 | This library is free software; you can redistribute it and/or |
5 | modify it under the terms of the GNU Library General Public |
6 | License as published by the Free Software Foundation; version |
7 | 2 of the License. |
8 | |
9 | This library is distributed in the hope that it will be useful, |
10 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
11 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
12 | Library General Public License for more details. |
13 | |
14 | You should have received a copy of the GNU Library General Public License |
15 | along with this library; see the file COPYING.LIB. If not, write to |
16 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
17 | Boston, MA 02110-1301, USA. |
18 | */ |
19 | //----------------------------------------------------------------------------- |
20 | // KDE color collection. |
21 | |
22 | #ifndef KDELIBS_KCOLORCOLLECTION_H |
23 | #define KDELIBS_KCOLORCOLLECTION_H |
24 | |
25 | #include <kdeui_export.h> |
26 | |
27 | #include <QtGui/QColor> |
28 | #include <QtCore/QList> |
29 | #include <QtCore/QString> |
30 | #include <QtCore/QStringList> |
31 | |
32 | /** |
33 | * Class for handling color collections ("palettes"). |
34 | * |
35 | * This class makes it easy to handle color collections, sometimes referred to |
36 | * as "palettes". This class can read and write collections from and to a file. |
37 | * |
38 | * This class uses the "GIMP" palette file format. |
39 | * |
40 | * @author Waldo Bastian (bastian@kde.org) |
41 | **/ |
42 | class KDEUI_EXPORT KColorCollection |
43 | { |
44 | public: |
45 | /** |
46 | * Query which KDE color collections are installed. |
47 | * |
48 | * @return A list with installed color collection names. |
49 | */ |
50 | static QStringList installedCollections(); |
51 | |
52 | /** |
53 | * KColorCollection constructor. Creates a KColorCollection from a file |
54 | * the filename is derived from the name. |
55 | * @param name The name of collection as returned by installedCollections() |
56 | **/ |
57 | explicit KColorCollection(const QString &name=QString()); |
58 | |
59 | /** |
60 | * KColorCollection copy constructor. |
61 | **/ |
62 | KColorCollection(const KColorCollection &); |
63 | |
64 | /** |
65 | * KColorCollection destructor. |
66 | **/ |
67 | ~KColorCollection(); |
68 | |
69 | /** |
70 | * KColorCollection assignment operator |
71 | **/ |
72 | KColorCollection& operator=( const KColorCollection &); |
73 | |
74 | /** |
75 | * Save the collection |
76 | * |
77 | * @return 'true' if successful |
78 | **/ |
79 | bool save(); |
80 | |
81 | /** |
82 | * Get the description of the collection. |
83 | * @return the description of the collection. |
84 | **/ |
85 | QString description() const; |
86 | |
87 | /** |
88 | * Set the description of the collection. |
89 | * @param desc the new description |
90 | **/ |
91 | void setDescription(const QString &desc); |
92 | |
93 | /** |
94 | * Get the name of the collection. |
95 | * @return the name of the collection |
96 | **/ |
97 | QString name() const; |
98 | |
99 | /** |
100 | * Set the name of the collection. |
101 | * @param name the name of the collection |
102 | **/ |
103 | void setName(const QString &name); |
104 | |
105 | /** |
106 | * Used to specify whether a collection may be edited. |
107 | * @see editable() |
108 | * @see setEditable() |
109 | */ |
110 | enum Editable { Yes, ///< Collection may be edited |
111 | No, ///< Collection may not be edited |
112 | Ask ///< Ask user before editing |
113 | }; |
114 | |
115 | /** |
116 | * Returns whether the collection may be edited. |
117 | * @return the state of the collection |
118 | **/ |
119 | Editable editable() const; |
120 | |
121 | /** |
122 | * Change whether the collection may be edited. |
123 | * @param editable the state of the collection |
124 | **/ |
125 | void setEditable(Editable editable); |
126 | |
127 | /** |
128 | * Return the number of colors in the collection. |
129 | * @return the number of colors |
130 | **/ |
131 | int count() const; |
132 | |
133 | /** |
134 | * Find color by index. |
135 | * @param index the index of the desired color |
136 | * @return The @p index -th color of the collection, null if not found. |
137 | **/ |
138 | QColor color(int index) const; |
139 | |
140 | /** |
141 | * Find index by @p color. |
142 | * @param color the color to find |
143 | * @return The index of the color in the collection or -1 if the |
144 | * color is not found. |
145 | **/ |
146 | int findColor(const QColor &color) const; |
147 | |
148 | /** |
149 | * Find color name by @p index. |
150 | * @param index the index of the color |
151 | * @return The name of the @p index -th color. |
152 | * Note that not all collections have named the colors. Null is |
153 | * returned if the color does not exist or has no name. |
154 | **/ |
155 | QString name(int index) const; |
156 | |
157 | /** |
158 | * Find color name by @p color. |
159 | * @return The name of color according to this collection. |
160 | * Note that not all collections have named the colors. |
161 | * Note also that each collection can give the same color |
162 | * a different name. |
163 | **/ |
164 | QString name(const QColor &color) const; |
165 | |
166 | /** |
167 | * Add a color. |
168 | * @param newColor The color to add. |
169 | * @param newColorName The name of the color, null to remove |
170 | * the name. |
171 | * @return The index of the added color. |
172 | **/ |
173 | int addColor(const QColor &newColor, |
174 | const QString &newColorName = QString()); |
175 | |
176 | /** |
177 | * Change a color. |
178 | * @param index Index of the color to change |
179 | * @param newColor The new color. |
180 | * @param newColorName The new color name, null to remove |
181 | * the name. |
182 | * @return The index of the new color or -1 if the color couldn't |
183 | * be changed. |
184 | **/ |
185 | int changeColor(int index, |
186 | const QColor &newColor, |
187 | const QString &newColorName = QString()); |
188 | |
189 | /** |
190 | * Change a color. |
191 | * @param oldColor The original color |
192 | * @param newColor The new color. |
193 | * @param newColorName The new color name, null to remove |
194 | * the name. |
195 | * @return The index of the new color or -1 if the color couldn't |
196 | * be changed. |
197 | **/ |
198 | int changeColor(const QColor &oldColor, |
199 | const QColor &newColor, |
200 | const QString &newColorName = QString()); |
201 | |
202 | private: |
203 | class KColorCollectionPrivate *d; |
204 | }; |
205 | |
206 | |
207 | #endif // KDELIBS_KCOLORCOLLECTION_H |
208 | |
209 | |