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