File indexing completed on 2024-03-24 15:27:38

0001 /* This file is part of the KDE libraries
0002     Copyright (C) 1997 Martin Jones (mjones@kde.org)
0003 
0004     This library is free software; you can redistribute it and/or
0005     modify it under the terms of the GNU Library General Public
0006     License as published by the Free Software Foundation; either
0007     version 2 of the License, or (at your option) any later version.
0008 
0009     This library is distributed in the hope that it will be useful,
0010     but WITHOUT ANY WARRANTY; without even the implied warranty of
0011     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0012     Library General Public License for more details.
0013 
0014     You should have received a copy of the GNU Library General Public License
0015     along with this library; see the file COPYING.LIB.  If not, write to
0016     the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
0017     Boston, MA 02110-1301, USA.
0018 */
0019 //----------------------------------------------------------------------
0020 // KDE color selection dialog.
0021 
0022 // layout management added Oct 1997 by Mario Weilguni
0023 // <mweilguni@sime.com>
0024 
0025 #ifndef KCOLORDIALOG_H
0026 #define KCOLORDIALOG_H
0027 
0028 #include <kdialog.h>
0029 #include <QPixmap>
0030 #include <QScrollArea>
0031 #include <QTableWidget>
0032 #include <kcolorchoosermode.h>
0033 
0034 #include <kdelibs4support_export.h>
0035 
0036 /**
0037 * A table of editable color cells.
0038 *
0039 * @author Martin Jones <mjones@kde.org>
0040 */
0041 class KDELIBS4SUPPORT_DEPRECATED_EXPORT KColorCells : public QTableWidget
0042 {
0043     Q_OBJECT
0044     Q_PROPERTY(bool acceptDrags READ acceptDrags WRITE setAcceptDrags)
0045     Q_PROPERTY(bool shading READ shading WRITE setShading)
0046 
0047 public:
0048     /**
0049      * Constructs a new table of color cells, consisting of
0050      * @p rows * @p columns colors.
0051      *
0052      * @param parent The parent of the new widget
0053      * @param rows The number of rows in the table
0054      * @param columns The number of columns in the table
0055      */
0056     KColorCells(QWidget *parent, int rows, int columns);
0057     ~KColorCells() override;
0058 
0059     /** Sets the color in the given index in the table */
0060     void setColor(int index, const QColor &col);
0061     /** Returns the color at a given index in the table */
0062     QColor color(int index) const;
0063     /** Returns the total number of color cells in the table */
0064     int count() const;
0065 
0066     void setShading(bool shade);
0067     bool shading() const;
0068 
0069     void setAcceptDrags(bool acceptDrags);
0070     bool acceptDrags() const;
0071 
0072     /** Sets the currently selected cell to @p index */
0073     void setSelected(int index);
0074     /** Returns the index of the cell which is currently selected */
0075     int  selectedIndex() const;
0076 
0077 Q_SIGNALS:
0078     /** Emitted when a color is selected in the table */
0079     void colorSelected(int index, const QColor &color);
0080     /** Emitted when a color in the table is double-clicked */
0081     void colorDoubleClicked(int index, const QColor &color);
0082 
0083 protected:
0084     // the three methods below are used to ensure equal column widths and row heights
0085     // for all cells and to update the widths/heights when the widget is resized
0086     int sizeHintForColumn(int column) const override;
0087     int sizeHintForRow(int column) const override;
0088     void resizeEvent(QResizeEvent *event) override;
0089 
0090     void mouseReleaseEvent(QMouseEvent *) override;
0091     void mousePressEvent(QMouseEvent *) override;
0092     void mouseMoveEvent(QMouseEvent *) override;
0093     void dragEnterEvent(QDragEnterEvent *) override;
0094     void dragMoveEvent(QDragMoveEvent *) override;
0095     void dropEvent(QDropEvent *) override;
0096     void mouseDoubleClickEvent(QMouseEvent *) override;
0097 
0098     int positionToCell(const QPoint &pos, bool ignoreBorders = false) const;
0099 
0100 private:
0101     class KColorCellsPrivate;
0102     friend class KColorCellsPrivate;
0103     KColorCellsPrivate *const d;
0104 
0105     Q_DISABLE_COPY(KColorCells)
0106 };
0107 
0108 /**
0109  * @short A color displayer.
0110  *
0111  * The KColorPatch widget is a (usually small) widget showing
0112  * a selected color e.g. in the KColorDialog. It
0113  * automatically handles drag and drop from and on the widget.
0114  *
0115  * \image html kcolorpatch.png "KDE Color Patch"
0116  */
0117 class KDELIBS4SUPPORT_DEPRECATED_EXPORT KColorPatch : public QFrame
0118 {
0119     Q_OBJECT
0120     Q_PROPERTY(QColor color READ color WRITE setColor)
0121 
0122 public:
0123     KColorPatch(QWidget *parent);
0124     ~KColorPatch() override;
0125 
0126     /**
0127      * Get the currently displayed color
0128      */
0129     QColor color() const;
0130 
0131     /**
0132      * Set the color to display and update the display
0133      *
0134      * @param col color to display
0135      */
0136     void setColor(const QColor &col);
0137 
0138 Q_SIGNALS:
0139     /**
0140      * This signal is emitted whenever the current color
0141      * changes due to a drop event
0142      */
0143     void colorChanged(const QColor &);
0144 
0145 protected:
0146     void paintEvent(QPaintEvent *pe) override;
0147     void mouseMoveEvent(QMouseEvent *) override;
0148     void dragEnterEvent(QDragEnterEvent *) override;
0149     void dropEvent(QDropEvent *) override;
0150 
0151 private:
0152     class KColorPatchPrivate;
0153     KColorPatchPrivate *const d;
0154 
0155     Q_DISABLE_COPY(KColorPatch)
0156 };
0157 
0158 /**
0159  * @short A color selection dialog.
0160  *
0161  * <b>Features:</b>\n
0162  *
0163  * @li Color selection from a wide range of palettes.
0164  * @li Color selection from a palette of H vs S and V selectors.
0165  * @li Direct input of HSV or RGB values.
0166  * @li Saving of custom colors
0167  *
0168  * In most cases, you will want to use the static method KColorDialog::getColor().
0169  * This pops up the dialog (with an initial selection provided by you), lets the
0170  * user choose a color, and returns.
0171  *
0172  * Example:
0173  *
0174  * \code
0175  *  QColor myColor;
0176  *  int result = KColorDialog::getColor( myColor );
0177  *         if ( result == KColorDialog::Accepted )
0178  *            ...
0179  * \endcode
0180  *
0181  * To react to the color selection as it is being selected, the colorSelected() signal
0182  * can be used.  This can be used still in a modal way, for example:
0183  *
0184  * \code
0185  *  KColorDialog dialog(this);
0186  *  connect(&dialog, SIGNAL(colorSelected(const QColor &)), this, SLOT(temporarilyChangeColor(const QColor &)));
0187  *  QColor myColor;
0188  *  dialog.setColor(myColor);
0189  *  int result = dialog.exec();
0190  *
0191  *  if ( result == KColorDialog::Accepted )
0192  *    changeColor( dialog.color() );
0193  *  else
0194  *    temporarilyChangeColor(myColor); //change back to original color
0195  * \endcode
0196  *
0197  *
0198  * @image html kcolordialog.png "KDE Color Dialog"
0199  *
0200  * The color dialog is really a collection of several widgets which can
0201  * you can also use separately: the quadratic plane in the top left of
0202  * the dialog is a KXYSelector. Right next to it is a KHSSelector
0203  * for choosing hue/saturation.
0204  *
0205  * On the right side of the dialog you see a KColorTable showing
0206  * a number of colors with a combo box which offers several predefined
0207  * palettes or a palette configured by the user. The small field showing
0208  * the currently selected color is a KColorPatch.
0209  *
0210  **/
0211 class KDELIBS4SUPPORT_DEPRECATED_EXPORT KColorDialog : public KDialog
0212 {
0213     Q_OBJECT
0214     Q_PROPERTY(bool isAlphaChannelEnabled READ isAlphaChannelEnabled WRITE setAlphaChannelEnabled)
0215     Q_PROPERTY(QColor defaultColor READ defaultColor WRITE setDefaultColor)
0216     Q_PROPERTY(QColor color READ color WRITE setColor)
0217 
0218 public:
0219     /**
0220      * Constructs a color selection dialog.
0221      */
0222     KDELIBS4SUPPORT_DEPRECATED explicit KColorDialog(QWidget *parent = nullptr, bool modal = false);
0223     /**
0224      * Destroys the color selection dialog.
0225      */
0226     ~KColorDialog() override;
0227 
0228     /**
0229      * Returns the currently selected color.
0230      **/
0231     QColor color() const;
0232 
0233     /**
0234      * Creates a modal color dialog, let the user choose a
0235      * color, and returns when the dialog is closed.
0236      *
0237      * The selected color is returned in the argument @p theColor.
0238      *
0239      * @param theColor if valid, specifies the color to be initially selected. On
0240      *                 return, holds the selected color.
0241      * @returns QDialog::result().
0242      */
0243     static int getColor(QColor &theColor, QWidget *parent = nullptr);
0244 
0245     /**
0246      * Creates a modal color dialog, lets the user choose a
0247      * color, and returns when the dialog is closed.
0248      *
0249      * The selected color is returned in the argument @p theColor.
0250      *
0251      * This version takes a @p defaultColor argument, which sets the color
0252      * selected by the "default color" checkbox. When this checkbox is checked,
0253      * the invalid color (QColor()) is returned into @p theColor.
0254      *
0255      * @param theColor if valid, specifies the color to be initially selected. On
0256      *                 return, holds the selected color.
0257      * @param defaultColor color selected by the "default color" checkbox
0258      * @returns QDialog::result().
0259      */
0260     static int getColor(QColor &theColor, const QColor &defaultColor, QWidget *parent = nullptr);
0261 
0262     /**
0263      * Gets the color from the pixel at point p on the screen.
0264      */
0265     static QColor grabColor(const QPoint &p);
0266 
0267     /**
0268      * Call this to make the dialog show a "Default Color" checkbox.
0269      * If this checkbox is selected, the dialog will return an "invalid" color (QColor()).
0270      * This can be used to mean "the default text color", for instance,
0271      * the one with the KDE text color on screen, but black when printing.
0272      */
0273     void setDefaultColor(const QColor &defaultCol);
0274 
0275     /**
0276      * @return the value passed to setDefaultColor
0277      */
0278     QColor defaultColor() const;
0279 
0280     /**
0281      * When set to true, the user is allowed to change the alpha component of the color.
0282      * The default value is false.
0283      * @since 4.5
0284      */
0285     void setAlphaChannelEnabled(bool alpha);
0286 
0287     /**
0288      * Returns true when the user can change the alpha channel.
0289      * @since 4.5
0290      */
0291     bool isAlphaChannelEnabled() const;
0292 
0293 public Q_SLOTS:
0294     /**
0295      * Preselects a color.
0296      */
0297     void setColor(const QColor &col);
0298 
0299 Q_SIGNALS:
0300     /**
0301      * Emitted when a color is selected.
0302      * Connect to this to monitor the color as it as selected if you are
0303      * not running modal.
0304      */
0305     void colorSelected(const QColor &col);
0306 
0307 private:
0308     Q_PRIVATE_SLOT(d, void slotRGBChanged(void))
0309     Q_PRIVATE_SLOT(d, void slotAlphaChanged(void))
0310     Q_PRIVATE_SLOT(d, void slotHSVChanged(void))
0311     Q_PRIVATE_SLOT(d, void slotHtmlChanged(void))
0312     Q_PRIVATE_SLOT(d, void slotHSChanged(int, int))
0313     Q_PRIVATE_SLOT(d, void slotVChanged(int))
0314     Q_PRIVATE_SLOT(d, void slotAChanged(int))
0315     Q_PRIVATE_SLOT(d, void slotColorSelected(const QColor &col))
0316     Q_PRIVATE_SLOT(d, void slotColorSelected(const QColor &col, const QString &name))
0317     Q_PRIVATE_SLOT(d, void slotColorDoubleClicked(const QColor &col, const QString &name))
0318     Q_PRIVATE_SLOT(d, void slotColorPicker())
0319     Q_PRIVATE_SLOT(d, void slotAddToCustomColors())
0320     Q_PRIVATE_SLOT(d, void slotDefaultColorClicked())
0321     Q_PRIVATE_SLOT(d, void slotModeChanged(int id))
0322 
0323     /**
0324      * Write the settings of the dialog to config file.
0325      **/
0326     Q_PRIVATE_SLOT(d, void slotWriteSettings())
0327 
0328 private:
0329     /**
0330      * Read the settings for the dialog from config file.
0331      **/
0332     void readSettings();
0333 
0334 protected:
0335     void mouseMoveEvent(QMouseEvent *) override;
0336     void mouseReleaseEvent(QMouseEvent *) override;
0337     void keyPressEvent(QKeyEvent *) override;
0338     bool eventFilter(QObject *obj, QEvent *ev) override;
0339 
0340 private:
0341     class KColorDialogPrivate;
0342     KColorDialogPrivate *const d;
0343 
0344     Q_DISABLE_COPY(KColorDialog)
0345 };
0346 
0347 #endif      // KCOLORDIALOG_H