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 | */ |
35 | class KGUIADDONS_EXPORT KGUIADDONS_DEPRECATED_VERSION(6, 3, "unused" ) KColorCollection |
36 | { |
37 | public: |
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 | |
223 | private: |
224 | QSharedDataPointer<class KColorCollectionPrivate> d; |
225 | }; |
226 | #endif |
227 | |
228 | #endif // KDELIBS_KCOLORCOLLECTION_H |
229 | |