File indexing completed on 2024-11-10 12:20:26
0001 /* This file is part of the KDE libraries 0002 SPDX-FileCopyrightText: 1999 Waldo Bastian <bastian@kde.org> 0003 0004 SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL 0005 */ 0006 0007 // KDE color collection. 0008 0009 #ifndef KDELIBS_KCOLORCOLLECTION_H 0010 #define KDELIBS_KCOLORCOLLECTION_H 0011 0012 #include <kguiaddons_export.h> 0013 0014 #include <QColor> 0015 #include <QSharedDataPointer> 0016 #include <QString> 0017 #include <QStringList> 0018 0019 /** 0020 * @class KColorCollection kcolorcollection.h KColorCollection 0021 * 0022 * Class for handling color collections ("palettes"). 0023 * 0024 * This class makes it easy to handle color collections, sometimes referred to 0025 * as "palettes". This class can read and write collections from and to a file. 0026 * 0027 * This class uses the "GIMP" palette file format. 0028 * 0029 * @author Waldo Bastian (bastian@kde.org) 0030 */ 0031 class KGUIADDONS_EXPORT KColorCollection 0032 { 0033 public: 0034 /** 0035 * Query which KDE color collections are installed. 0036 * 0037 * @return A list with installed color collection names. 0038 */ 0039 static QStringList installedCollections(); 0040 0041 /** 0042 * KColorCollection constructor. Creates a KColorCollection from a file 0043 * the filename is derived from the name. 0044 * @param name The name of collection as returned by installedCollections() 0045 */ 0046 explicit KColorCollection(const QString &name = QString()); 0047 0048 /** 0049 * KColorCollection copy constructor. 0050 */ 0051 KColorCollection(const KColorCollection &); 0052 0053 /** 0054 * KColorCollection destructor. 0055 */ 0056 ~KColorCollection(); 0057 0058 /** 0059 * KColorCollection assignment operator 0060 */ 0061 KColorCollection &operator=(const KColorCollection &); 0062 0063 /** 0064 * Save the collection 0065 * 0066 * @return 'true' if successful 0067 */ 0068 bool save(); 0069 0070 /** 0071 * Get the description of the collection. 0072 * @return the description of the collection. 0073 */ 0074 QString description() const; 0075 0076 /** 0077 * Set the description of the collection. 0078 * @param desc the new description 0079 */ 0080 void setDescription(const QString &desc); 0081 0082 /** 0083 * Get the name of the collection. 0084 * @return the name of the collection 0085 */ 0086 QString name() const; 0087 0088 /** 0089 * Set the name of the collection. 0090 * @param name the name of the collection 0091 */ 0092 void setName(const QString &name); 0093 0094 /** 0095 * Used to specify whether a collection may be edited. 0096 * @see editable() 0097 * @see setEditable() 0098 */ 0099 enum Editable { 0100 Yes, ///< Collection may be edited 0101 No, ///< Collection may not be edited 0102 Ask, ///< Ask user before editing 0103 }; 0104 0105 /** 0106 * Returns whether the collection may be edited. 0107 * @return the state of the collection 0108 */ 0109 Editable editable() const; 0110 0111 /** 0112 * Change whether the collection may be edited. 0113 * @param editable the state of the collection 0114 */ 0115 void setEditable(Editable editable); 0116 0117 /** 0118 * Return the number of colors in the collection. 0119 * @return the number of colors 0120 */ 0121 int count() const; 0122 0123 /** 0124 * Find color by index. 0125 * @param index the index of the desired color 0126 * @return The @p index -th color of the collection, null if not found. 0127 */ 0128 QColor color(int index) const; 0129 0130 /** 0131 * Find index by @p color. 0132 * @param color the color to find 0133 * @return The index of the color in the collection or -1 if the 0134 * color is not found. 0135 */ 0136 int findColor(const QColor &color) const; 0137 0138 /** 0139 * Find color name by @p index. 0140 * @param index the index of the color 0141 * @return The name of the @p index -th color. 0142 * Note that not all collections have named the colors. Null is 0143 * returned if the color does not exist or has no name. 0144 */ 0145 QString name(int index) const; 0146 0147 /** 0148 * Find color name by @p color. 0149 * @return The name of color according to this collection. 0150 * Note that not all collections have named the colors. 0151 * Note also that each collection can give the same color 0152 * a different name. 0153 */ 0154 QString name(const QColor &color) const; 0155 0156 /** 0157 * Add a color. 0158 * @param newColor The color to add. 0159 * @param newColorName The name of the color, null to remove 0160 * the name. 0161 * @return The index of the added color. 0162 */ 0163 int addColor(const QColor &newColor, const QString &newColorName = QString()); 0164 0165 /** 0166 * Change a color. 0167 * @param index Index of the color to change 0168 * @param newColor The new color. 0169 * @param newColorName The new color name, null to remove 0170 * the name. 0171 * @return The index of the new color or -1 if the color couldn't 0172 * be changed. 0173 */ 0174 int changeColor(int index, const QColor &newColor, const QString &newColorName = QString()); 0175 0176 /** 0177 * Change a color. 0178 * @param oldColor The original color 0179 * @param newColor The new color. 0180 * @param newColorName The new color name, null to remove 0181 * the name. 0182 * @return The index of the new color or -1 if the color couldn't 0183 * be changed. 0184 */ 0185 int changeColor(const QColor &oldColor, const QColor &newColor, const QString &newColorName = QString()); 0186 0187 private: 0188 QSharedDataPointer<class KColorCollectionPrivate> d; 0189 }; 0190 0191 #endif // KDELIBS_KCOLORCOLLECTION_H