comparison layer/ColourDatabase.h @ 1445:ad86aa712d11 single-point

Add getNearbyColourIndex to ColourDatabase; tweak getContrastingColour for bright colours; add comments

     Q_OBJECT
 
 public:
     static ColourDatabase *getInstance();
 
+    /**
+     * Return the number of colours in the database.
+     */
     int getColourCount() const;
+
+    /**
+     * Return the name of the colour at index c.
+     */
     QString getColourName(int c) const;
+
+    /**
+     * Return the colour at index c.
+     */
     QColor getColour(int c) const;
+
+    /**
+     * Return the colour with the given name, if found in the
+     * database. If not found, return Qt::black.
+     */
     QColor getColour(QString name) const;
-    int getColourIndex(QString name) const; // -1 -> not found
-    int getColourIndex(QColor c) const; // returns first index of possibly many
+
+    /**
+     * Return the index of the colour with the given name, if found in
+     * the database. If not found, return -1.
+     */
+    int getColourIndex(QString name) const;
+
+    /**
+     * Return the index of the given colour, if found in the
+     * database. If not found, return -1. Note that it is possible for
+     * a colour to appear more than once in the database: names have
+     * to be unique in the database, but colours don't. This always
+     * returns the first match.
+     */
+    int getColourIndex(QColor c) const;
+
+    /**
+     * Return true if the given colour exists in the database.
+     */
     bool haveColour(QColor c) const;
 
+    /**
+     * Return the index of the colour in the database that is closest
+     * to the given one, by some simplistic measure (Manhattan
+     * distance in RGB space). This always returns some valid index,
+     * unless the database is empty, in which case it returns -1.
+     */
+    int getNearbyColourIndex(QColor c) const;
+
+    /**
+     * Add a colour to the database, with the associated name. Return
+     * the index of the colour in the database. Names are unique
+     * within the database: if another colour exists already with the
+     * given name, its colour value is replaced with the given
+     * one. Colours may appear more than once under different names.
+     */
+    int addColour(QColor c, QString name);
+
+    /** 
+     * Remove the colour with the given name from the database.
+     */
+    void removeColour(QString);
+
+    /**
+     * Return true if the colour at index c is marked as using a dark
+     * background. Such colours are presumably "bright" ones, but all
+     * this reports is whether the colour has been marked with
+     * setUseDarkBackground, not any intrinsic property of the colour.
+     */
     bool useDarkBackground(int c) const;
+    
+    /**
+     * Mark the colour at index c as using a dark
+     * background. Generally this should be called for "bright"
+     * colours.
+     */
     void setUseDarkBackground(int c, bool dark);
 
-    int addColour(QColor, QString); // returns index
-    void removeColour(QString);
-
-    // returned colour is not necessarily in database
+    /**
+     * Return a colour that contrasts with the one at index c,
+     * according to some simplistic algorithm. The returned colour is
+     * not necessarily in the database; pass it to
+     * getNearbyColourIndex if you need one that is.
+     */
     QColor getContrastingColour(int c) const;
 
     // for use in XML export
     void getStringValues(int index,
                          QString &colourName,

                         QString darkbg);
 
     // for use by PropertyContainer getPropertyRangeAndValue methods
     void getColourPropertyRange(int *min, int *max) const;
 
-    QPixmap getExamplePixmap(int index, QSize size) const;
+    /**
+     * Generate a swatch pixmap illustrating the colour at index c.
+     */
+    QPixmap getExamplePixmap(int c, QSize size) const;
     
 signals:
     void colourDatabaseChanged();
 
 protected: