1/* This file is part of the KDE libraries
2 SPDX-FileCopyrightText: 1999 Waldo Bastian <bastian@kde.org>
3
4 SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
5*/
6
7// KDE color collection.
8
9#ifndef KDELIBS_KCOLORCOLLECTION_H
10#define KDELIBS_KCOLORCOLLECTION_H
11
12#include <kguiaddons_export.h>
13
14#include <QColor>
15#include <QSharedDataPointer>
16#include <QString>
17#include <QStringList>
18
19#if KGUIADDONS_ENABLE_DEPRECATED_SINCE(6, 3)
20/*!
21 * \class KColorCollection
22 * \inmodule KGuiAddons
23 *
24 * Class for handling color collections ("palettes").
25 *
26 * This class makes it easy to handle color collections, sometimes referred to
27 * as "palettes". This class can read and write collections from and to a file.
28 *
29 * This class uses the "GIMP" palette file format.
30 *
31 * Unused and backing data no longer available
32 *
33 * \deprecated [6.3]
34 */
35class KGUIADDONS_EXPORT KGUIADDONS_DEPRECATED_VERSION(6, 3, "unused") KColorCollection
36{
37public:
38 /*!
39 * Query which KDE color collections are installed.
40 *
41 * Returns a list with installed color collection names.
42 */
43 static QStringList installedCollections();
44
45 /*!
46 * KColorCollection constructor. Creates a KColorCollection from a file
47 * the filename is derived from the name.
48 *
49 * \a name The name of collection as returned by installedCollections()
50 */
51 explicit KColorCollection(const QString &name = QString());
52
53 /*!
54 * KColorCollection copy constructor.
55 */
56 KColorCollection(const KColorCollection &);
57
58 /*!
59 * KColorCollection destructor.
60 */
61 ~KColorCollection();
62
63 /*!
64 * KColorCollection assignment operator
65 */
66 KColorCollection &operator=(const KColorCollection &);
67
68 /*!
69 * Save the collection
70 *
71 * Returns \c true if successful
72 */
73 bool save();
74
75 /*!
76 * Get the description of the collection.
77 *
78 * Returns the description of the collection.
79 */
80 QString description() const;
81
82 /*!
83 * Set the description of the collection.
84 *
85 * \a desc the new description
86 */
87 void setDescription(const QString &desc);
88
89 /*!
90 * Get the name of the collection.
91 *
92 * Returns the name of the collection
93 */
94 QString name() const;
95
96 /*!
97 * Set the name of the collection.
98 *
99 * \a name the name of the collection
100 */
101 void setName(const QString &name);
102
103 /*!
104 * Used to specify whether a collection may be edited.
105 * \sa editable()
106 * \sa setEditable()
107 *
108 * \value Yes Collection may be edited
109 * \value No Collection may not be edited
110 * \value Ask Ask user before editing
111 *
112 */
113 enum Editable {
114 Yes,
115 No,
116 Ask,
117 };
118
119 /*!
120 * Returns whether the collection may be edited.
121 * Returns the state of the collection
122 */
123 Editable editable() const;
124
125 /*!
126 * Change whether the collection may be edited.
127 *
128 * \a editable the state of the collection
129 */
130 void setEditable(Editable editable);
131
132 /*!
133 * Return the number of colors in the collection.
134 * Returns the number of colors
135 */
136 int count() const;
137
138 /*!
139 * Find color by index.
140 *
141 * \a index the index of the desired color
142 *
143 * Returns The \a index -th color of the collection, null if not found.
144 */
145 QColor color(int index) const;
146
147 /*!
148 * Find index by \a color.
149 *
150 * \a color the color to find
151 *
152 * Returns The index of the color in the collection or -1 if the
153 * color is not found.
154 */
155 int findColor(const QColor &color) const;
156
157 /*!
158 * Find color name by \a index.
159 *
160 * \a index the index of the color
161 *
162 * Returns The name of the \a index -th color.
163 *
164 * Note that not all collections have named the colors. Null is
165 * returned if the color does not exist or has no name.
166 */
167 QString name(int index) const;
168
169 /*!
170 * Find color name by \a color.
171 *
172 * Returns The name of color according to this collection.
173 *
174 * Note that not all collections have named the colors.
175 *
176 * Note also that each collection can give the same color
177 * a different name.
178 */
179 QString name(const QColor &color) const;
180
181 /*!
182 * Add a color.
183 *
184 * \a newColor The color to add.
185 *
186 * \a newColorName The name of the color, null to remove
187 * the name.
188 *
189 * Returns The index of the added color.
190 */
191 int addColor(const QColor &newColor, const QString &newColorName = QString());
192
193 /*!
194 * Change a color.
195 *
196 * \a index Index of the color to change
197 *
198 * \a newColor The new color.
199 *
200 * \a newColorName The new color name, null to remove
201 * the name.
202 *
203 * Returns the index of the new color or -1 if the color couldn't
204 * be changed.
205 */
206 int changeColor(int index, const QColor &newColor, const QString &newColorName = QString());
207
208 /*!
209 * Change a color.
210 *
211 * \a oldColor The original color
212 *
213 * \a newColor The new color.
214 *
215 * \a newColorName The new color name, null to remove
216 * the name.
217 *
218 * Returns the index of the new color or -1 if the color couldn't
219 * be changed.
220 */
221 int changeColor(const QColor &oldColor, const QColor &newColor, const QString &newColorName = QString());
222
223private:
224 QSharedDataPointer<class KColorCollectionPrivate> d;
225};
226#endif
227
228#endif // KDELIBS_KCOLORCOLLECTION_H
229

source code of kguiaddons/src/colors/kcolorcollection.h