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/**
20 * @class KColorCollection kcolorcollection.h KColorCollection
21 *
22 * Class for handling color collections ("palettes").
23 *
24 * This class makes it easy to handle color collections, sometimes referred to
25 * as "palettes". This class can read and write collections from and to a file.
26 *
27 * This class uses the "GIMP" palette file format.
28 *
29 * @author Waldo Bastian (bastian@kde.org)
30 */
31class KGUIADDONS_EXPORT KColorCollection
32{
33public:
34 /**
35 * Query which KDE color collections are installed.
36 *
37 * @return A list with installed color collection names.
38 */
39 static QStringList installedCollections();
40
41 /**
42 * KColorCollection constructor. Creates a KColorCollection from a file
43 * the filename is derived from the name.
44 * @param name The name of collection as returned by installedCollections()
45 */
46 explicit KColorCollection(const QString &name = QString());
47
48 /**
49 * KColorCollection copy constructor.
50 */
51 KColorCollection(const KColorCollection &);
52
53 /**
54 * KColorCollection destructor.
55 */
56 ~KColorCollection();
57
58 /**
59 * KColorCollection assignment operator
60 */
61 KColorCollection &operator=(const KColorCollection &);
62
63 /**
64 * Save the collection
65 *
66 * @return 'true' if successful
67 */
68 bool save();
69
70 /**
71 * Get the description of the collection.
72 * @return the description of the collection.
73 */
74 QString description() const;
75
76 /**
77 * Set the description of the collection.
78 * @param desc the new description
79 */
80 void setDescription(const QString &desc);
81
82 /**
83 * Get the name of the collection.
84 * @return the name of the collection
85 */
86 QString name() const;
87
88 /**
89 * Set the name of the collection.
90 * @param name the name of the collection
91 */
92 void setName(const QString &name);
93
94 /**
95 * Used to specify whether a collection may be edited.
96 * @see editable()
97 * @see setEditable()
98 */
99 enum Editable {
100 Yes, ///< Collection may be edited
101 No, ///< Collection may not be edited
102 Ask, ///< Ask user before editing
103 };
104
105 /**
106 * Returns whether the collection may be edited.
107 * @return the state of the collection
108 */
109 Editable editable() const;
110
111 /**
112 * Change whether the collection may be edited.
113 * @param editable the state of the collection
114 */
115 void setEditable(Editable editable);
116
117 /**
118 * Return the number of colors in the collection.
119 * @return the number of colors
120 */
121 int count() const;
122
123 /**
124 * Find color by index.
125 * @param index the index of the desired color
126 * @return The @p index -th color of the collection, null if not found.
127 */
128 QColor color(int index) const;
129
130 /**
131 * Find index by @p color.
132 * @param color the color to find
133 * @return The index of the color in the collection or -1 if the
134 * color is not found.
135 */
136 int findColor(const QColor &color) const;
137
138 /**
139 * Find color name by @p index.
140 * @param index the index of the color
141 * @return The name of the @p index -th color.
142 * Note that not all collections have named the colors. Null is
143 * returned if the color does not exist or has no name.
144 */
145 QString name(int index) const;
146
147 /**
148 * Find color name by @p color.
149 * @return The name of color according to this collection.
150 * Note that not all collections have named the colors.
151 * Note also that each collection can give the same color
152 * a different name.
153 */
154 QString name(const QColor &color) const;
155
156 /**
157 * Add a color.
158 * @param newColor The color to add.
159 * @param newColorName The name of the color, null to remove
160 * the name.
161 * @return The index of the added color.
162 */
163 int addColor(const QColor &newColor, const QString &newColorName = QString());
164
165 /**
166 * Change a color.
167 * @param index Index of the color to change
168 * @param newColor The new color.
169 * @param newColorName The new color name, null to remove
170 * the name.
171 * @return The index of the new color or -1 if the color couldn't
172 * be changed.
173 */
174 int changeColor(int index, const QColor &newColor, const QString &newColorName = QString());
175
176 /**
177 * Change a color.
178 * @param oldColor The original color
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(const QColor &oldColor, const QColor &newColor, const QString &newColorName = QString());
186
187private:
188 QSharedDataPointer<class KColorCollectionPrivate> d;
189};
190
191#endif // KDELIBS_KCOLORCOLLECTION_H
192

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