File indexing completed on 2024-05-12 04:21:20

 
 // SYNC: Periodically merge in changes from:
 //
 //           trunk/KDE/kdelibs/kdeui/colors/kcolorcollection.{h,cpp}
 //
 //       which this is a fork of.
 //
 //       Our changes can be merged back into KDE (grep for "Added for KolourPaint" and similar).
 
 /* This file is part of the KDE libraries
     Copyright (C) 1999 Waldo Bastian (bastian@kde.org)
     Copyright (C) 2007 Clarence Dang (dang@kde.org)
 
     This library is free software; you can redistribute it and/or
     modify it under the terms of the GNU Library General Public
     License as published by the Free Software Foundation; version
     2 of the License.
 
     This library is distributed in the hope that it will be useful,
     but WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
     Library General Public License for more details.
 
     You should have received a copy of the GNU Library General Public License
     along with this library; see the file COPYING.LIB.  If not, write to
     the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
     Boston, MA 02110-1301, USA.
 */
 //-----------------------------------------------------------------------------
 // KDE color collection.
 
 #ifndef kpColorCollection_H
 #define kpColorCollection_H
 
 #include <kolourpaint_lgpl_export.h>
 
 #include <QColor>
 #include <QString>
 #include <QStringList>
 #include <QWidget>
 
 class QUrl;
 
 /**
  * Class for handling color collections ("palettes").
  *
  * This class makes it easy to handle color collections, sometimes referred to
  * as "palettes". This class can read and write collections from and to a file.
  *
  * Collections that are managed by KDE have a non-empty name().  Collections
  * stored in regular files have an empty name().
  *
  * This class uses the "GIMP" palette file format.
  *
  * @author Waldo Bastian (bastian@kde.org), Clarence Dang (dang@kde.org)
  **/
 class KOLOURPAINT_LGPL_EXPORT kpColorCollection
 {
 public:
    /**
     * Query which KDE color collections are installed.
     *
     * @return A list with installed color collection names.
     */
    static QStringList installedCollections();
 
    /**
     * kpColorCollection constructor
     *
     * <name> argument removed for KolourPaint.
     * Use openKDE() instead, which also has error handling.
     **/
    explicit kpColorCollection();
 
    /**
     * kpColorCollection copy constructor.
     **/
    kpColorCollection(const kpColorCollection &);
 
    /**
     * kpColorCollection destructor.
     **/
    ~kpColorCollection();
 
    /**
     * kpColorCollection assignment operator
     **/
    kpColorCollection& operator=( const kpColorCollection &);
 
    // On failure, this prints an error dialog and returns false.
    // On success, it sets the name() to an empty string and returns true.
    //
    // Added for KolourPaint.
    bool open(const QUrl &url, QWidget *parent);
 
    // Same as open() but is given the name of a KDE palette, not a filename.
    //
    // @param name The name of collection as returned by installedCollections().
    //             name() is set to this.
    //
    // Added for KolourPaint.
    bool openKDE(const QString &name, QWidget *parent);
 
    // On failure, this prints an error dialog and returns false.
    // If the user cancels any presented overwrite dialog, it also returns false.
    // On success, it returns true.
    //
    // The file can be overwritten without displaying any warning dialog, if
    // <showOverwritePrompt> is set to false.
    //
    // name() is set to an empty string.
    //
    // Added for KolourPaint.
    bool saveAs(const QUrl &url, QWidget *parent) const;
 
    /**
     * Get the description of the collection.
     * @return the description of the collection.
     **/
    QString description() const;
 
    /**
     * Set the description of the collection.
     * @param desc the new description
     **/
    void setDescription(const QString &desc);
 
    /**
     * Get the name of the collection.
     * @return the name of the collection
     **/
    QString name() const;
 
    /**
     * Set the name of the collection.
     * @param name the name of the collection
     **/
    void setName(const QString &name);
 
    /**
     * Used to specify whether a collection may be edited.
     * @see editable()
     * @see setEditable()
     */
    enum Editable { Yes, ///< Collection may be edited
                   No,  ///< Collection may not be edited
            Ask  ///< Ask user before editing
    };
 
    /**
     * Returns whether the collection may be edited.
     * @return the state of the collection
     **/
    Editable editable() const;
 
    /**
     * Change whether the collection may be edited.
     * @param editable the state of the collection
     **/
    void setEditable(Editable editable);
 
    /**
     * Return the number of colors in the collection.
     * @return the number of colors
     **/
    int count() const;
 
    /**
     * Adds invalid colors or removes colors so that there will be @p newCount
     * colors in the color collection.
     *
     * @param target number of colors
     *
     * Added for KolourPaint.
     */
    void resize(int newCount);
 
    /**
     * Find color by index.
     * @param index the index of the desired color
     * @return The @p index -th color of the collection, null if not found.
     **/
    QColor color(int index) const;
 
    /**
     * Find index by @p color.
     * @param color the color to find
     * @return The index of the color in the collection or -1 if the
     * color is not found.
     **/
    int findColor(const QColor &color) const;
 
    /**
     * Find color name by @p index.
     * @param index the index of the color
     * @return The name of the @p index -th color.
     * Note that not all collections have named the colors. Null is
     * returned if the color does not exist or has no name.
     **/
    QString name(int index) const;
 
    /**
     * Find color name by @p color.
     * @return The name of color according to this collection.
     * Note that not all collections have named the colors.
     * Note also that each collection can give the same color
     * a different name.
     **/
    QString name(const QColor &color) const;
 
    /**
     * Add a color.
     * @param newColor The color to add.
     * @param newColorName The name of the color, null to remove
     *                     the name.
     * @return The index of the added color.
     **/
    int addColor(const QColor &newColor,
                 const QString &newColorName = QString());
 
    /**
     * Change a color.
     * @param index Index of the color to change
     * @param newColor The new color.
     * @param newColorName The new color name, null to remove
     *                     the name.
     * @return The index of the new color or -1 if the color couldn't
     * be changed.
     **/
    int changeColor(int index,
                    const QColor &newColor,
                    const QString &newColorName = QString());
 
    /**
     * Change a color.
     * @param oldColor The original color
     * @param newColor The new color.
     * @param newColorName The new color name, null to remove
     *                     the name.
     * @return The index of the new color or -1 if the color couldn't
     * be changed.
     **/
    int changeColor(const QColor &oldColor,
                    const QColor &newColor,
                    const QString &newColorName = QString());
 
 private:
    class kpColorCollectionPrivate *d;
 };
 
 
 #endif // kpColorCollection_H