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 **/
42class KDEUI_EXPORT KColorCollection
43{
44public:
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
202private:
203 class KColorCollectionPrivate *d;
204};
205
206
207#endif // KDELIBS_KCOLORCOLLECTION_H
208
209