1/* This file is part of the KDE libraries
2 Copyright (C) 1997 Martin Jones (mjones@kde.org)
3
4 This library is free software; you can redistribute it and/or
5 modify it under the terms of the GNU Library General Public
6 License as published by the Free Software Foundation; either
7 version 2 of the License, or (at your option) any later version.
8
9 This library is distributed in the hope that it will be useful,
10 but WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 Library General Public License for more details.
13
14 You should have received a copy of the GNU Library General Public License
15 along with this library; see the file COPYING.LIB. If not, write to
16 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
17 Boston, MA 02110-1301, USA.
18*/
19//----------------------------------------------------------------------
20// KDE color selection dialog.
21
22// layout management added Oct 1997 by Mario Weilguni
23// <mweilguni@sime.com>
24
25#ifndef KCOLORDIALOG_H
26#define KCOLORDIALOG_H
27
28#include <kdialog.h>
29#include <QtGui/QPixmap>
30#include <QtGui/QScrollArea>
31#include <QtGui/QTableWidget>
32#include <kcolorchoosermode.h>
33
34
35/**
36* A table of editable color cells.
37*
38* @author Martin Jones <mjones@kde.org>
39*/
40class KDEUI_EXPORT KColorCells : public QTableWidget
41{
42 Q_OBJECT
43 Q_PROPERTY(bool acceptDrags READ acceptDrags WRITE setAcceptDrags)
44 Q_PROPERTY(bool shading READ shading WRITE setShading)
45
46public:
47 /**
48 * Constructs a new table of color cells, consisting of
49 * @p rows * @p columns colors.
50 *
51 * @param parent The parent of the new widget
52 * @param rows The number of rows in the table
53 * @param columns The number of columns in the table
54 */
55 KColorCells( QWidget *parent, int rows, int columns );
56 ~KColorCells();
57
58 /** Sets the color in the given index in the table */
59 void setColor( int index, const QColor &col );
60 /** Returns the color at a given index in the table */
61 QColor color( int index ) const;
62 /** Returns the total number of color cells in the table */
63 int count() const;
64
65 void setShading(bool shade);
66 bool shading() const;
67
68 void setAcceptDrags(bool acceptDrags);
69 bool acceptDrags() const;
70
71 /** Sets the currently selected cell to @p index */
72 void setSelected(int index);
73 /** Returns the index of the cell which is currently selected */
74 int selectedIndex() const;
75
76Q_SIGNALS:
77 /** Emitted when a color is selected in the table */
78 void colorSelected( int index , const QColor& color );
79 /** Emitted when a color in the table is double-clicked */
80 void colorDoubleClicked( int index , const QColor& color );
81
82protected:
83 // the three methods below are used to ensure equal column widths and row heights
84 // for all cells and to update the widths/heights when the widget is resized
85 virtual int sizeHintForColumn(int column) const;
86 virtual int sizeHintForRow(int column) const;
87 virtual void resizeEvent( QResizeEvent* event );
88
89 virtual void mouseReleaseEvent( QMouseEvent * );
90 virtual void mousePressEvent( QMouseEvent * );
91 virtual void mouseMoveEvent( QMouseEvent * );
92 virtual void dragEnterEvent( QDragEnterEvent * );
93 virtual void dragMoveEvent( QDragMoveEvent * );
94 virtual void dropEvent( QDropEvent *);
95 virtual void mouseDoubleClickEvent( QMouseEvent * );
96
97 int positionToCell(const QPoint &pos, bool ignoreBorders=false) const;
98
99private:
100 class KColorCellsPrivate;
101 friend class KColorCellsPrivate;
102 KColorCellsPrivate *const d;
103
104 Q_DISABLE_COPY(KColorCells)
105};
106
107/**
108 * @short A color displayer.
109 *
110 * The KColorPatch widget is a (usually small) widget showing
111 * a selected color e.g. in the KColorDialog. It
112 * automatically handles drag and drop from and on the widget.
113 *
114 * \image html kcolorpatch.png "KDE Color Patch"
115 */
116class KDEUI_EXPORT KColorPatch : public QFrame
117{
118 Q_OBJECT
119 Q_PROPERTY(QColor color READ color WRITE setColor)
120
121public:
122 KColorPatch( QWidget *parent );
123 virtual ~KColorPatch();
124
125 /**
126 * Get the currently displayed color
127 */
128 QColor color() const;
129
130 /**
131 * Set the color to display and update the display
132 *
133 * @param col color to display
134 */
135 void setColor( const QColor &col );
136
137Q_SIGNALS:
138 /**
139 * This signal is emitted whenever the current color
140 * changes due to a drop event
141 */
142 void colorChanged(const QColor&);
143
144protected:
145 virtual void paintEvent ( QPaintEvent * pe );
146 virtual void mouseMoveEvent( QMouseEvent * );
147 virtual void dragEnterEvent( QDragEnterEvent *);
148 virtual void dropEvent( QDropEvent *);
149
150private:
151 class KColorPatchPrivate;
152 KColorPatchPrivate *const d;
153
154 Q_DISABLE_COPY(KColorPatch)
155};
156
157/**
158 * @short A color selection dialog.
159 *
160 * <b>Features:</b>\n
161 *
162 * @li Color selection from a wide range of palettes.
163 * @li Color selection from a palette of H vs S and V selectors.
164 * @li Direct input of HSV or RGB values.
165 * @li Saving of custom colors
166 *
167 * In most cases, you will want to use the static method KColorDialog::getColor().
168 * This pops up the dialog (with an initial selection provided by you), lets the
169 * user choose a color, and returns.
170 *
171 * Example:
172 *
173 * \code
174 * QColor myColor;
175 * int result = KColorDialog::getColor( myColor );
176 * if ( result == KColorDialog::Accepted )
177 * ...
178 * \endcode
179 *
180 * To react to the color selection as it is being selected, the colorSelected() signal
181 * can be used. This can be used still in a modal way, for example:
182 *
183 * \code
184 * KColorDialog dialog(this);
185 * connect(&dialog, SIGNAL(colorSelected(const QColor &)), this, SLOT(temporarilyChangeColor(const QColor &)));
186 * QColor myColor;
187 * dialog.setColor(myColor);
188 * int result = dialog.exec();
189 *
190 * if ( result == KColorDialog::Accepted )
191 * changeColor( dialog.color() );
192 * else
193 * temporarilyChangeColor(myColor); //change back to original color
194 * \endcode
195 *
196 *
197 * @image html kcolordialog.png "KDE Color Dialog"
198 *
199 * The color dialog is really a collection of several widgets which can
200 * you can also use separately: the quadratic plane in the top left of
201 * the dialog is a KXYSelector. Right next to it is a KHSSelector
202 * for choosing hue/saturation.
203 *
204 * On the right side of the dialog you see a KColorTable showing
205 * a number of colors with a combo box which offers several predefined
206 * palettes or a palette configured by the user. The small field showing
207 * the currently selected color is a KColorPatch.
208 *
209 **/
210class KDEUI_EXPORT KColorDialog : public KDialog
211{
212 Q_OBJECT
213 Q_PROPERTY(bool isAlphaChannelEnabled READ isAlphaChannelEnabled WRITE setAlphaChannelEnabled)
214 Q_PROPERTY(QColor defaultColor READ defaultColor WRITE setDefaultColor)
215 Q_PROPERTY(QColor color READ color WRITE setColor)
216
217 public:
218 /**
219 * Constructs a color selection dialog.
220 */
221 explicit KColorDialog( QWidget *parent = 0L, bool modal = false );
222 /**
223 * Destroys the color selection dialog.
224 */
225 ~KColorDialog();
226
227 /**
228 * Returns the currently selected color.
229 **/
230 QColor color() const;
231
232 /**
233 * Creates a modal color dialog, let the user choose a
234 * color, and returns when the dialog is closed.
235 *
236 * The selected color is returned in the argument @p theColor.
237 *
238 * @param theColor if valid, specifies the color to be initially selected. On
239 * return, holds the selected color.
240 * @returns QDialog::result().
241 */
242 static int getColor( QColor &theColor, QWidget *parent=0L );
243
244 /**
245 * Creates a modal color dialog, lets the user choose a
246 * color, and returns when the dialog is closed.
247 *
248 * The selected color is returned in the argument @p theColor.
249 *
250 * This version takes a @p defaultColor argument, which sets the color
251 * selected by the "default color" checkbox. When this checkbox is checked,
252 * the invalid color (QColor()) is returned into @p theColor.
253 *
254 * @param theColor if valid, specifies the color to be initially selected. On
255 * return, holds the selected color.
256 * @param defaultColor color selected by the "default color" checkbox
257 * @returns QDialog::result().
258 */
259 static int getColor( QColor &theColor, const QColor& defaultColor, QWidget *parent=0L );
260
261 /**
262 * Gets the color from the pixel at point p on the screen.
263 */
264 static QColor grabColor(const QPoint &p);
265
266 /**
267 * Call this to make the dialog show a "Default Color" checkbox.
268 * If this checkbox is selected, the dialog will return an "invalid" color (QColor()).
269 * This can be used to mean "the default text color", for instance,
270 * the one with the KDE text color on screen, but black when printing.
271 */
272 void setDefaultColor( const QColor& defaultCol );
273
274 /**
275 * @return the value passed to setDefaultColor
276 */
277 QColor defaultColor() const;
278
279 /**
280 * When set to true, the user is allowed to change the alpha component of the color.
281 * The default value is false.
282 * @since 4.5
283 */
284 void setAlphaChannelEnabled(bool alpha);
285
286 /**
287 * Returns true when the user can change the alpha channel.
288 * @since 4.5
289 */
290 bool isAlphaChannelEnabled() const;
291
292 public Q_SLOTS:
293 /**
294 * Preselects a color.
295 */
296 void setColor( const QColor &col );
297
298 Q_SIGNALS:
299 /**
300 * Emitted when a color is selected.
301 * Connect to this to monitor the color as it as selected if you are
302 * not running modal.
303 */
304 void colorSelected( const QColor &col );
305
306 private:
307 Q_PRIVATE_SLOT(d, void slotRGBChanged( void ))
308 Q_PRIVATE_SLOT(d, void slotAlphaChanged( void ))
309 Q_PRIVATE_SLOT(d, void slotHSVChanged( void ))
310 Q_PRIVATE_SLOT(d, void slotHtmlChanged( void ))
311 Q_PRIVATE_SLOT(d, void slotHSChanged( int, int ))
312 Q_PRIVATE_SLOT(d, void slotVChanged( int ))
313 Q_PRIVATE_SLOT(d, void slotAChanged( int ))
314 Q_PRIVATE_SLOT(d, void slotColorSelected( const QColor &col ))
315 Q_PRIVATE_SLOT(d, void slotColorSelected( const QColor &col, const QString &name ))
316 Q_PRIVATE_SLOT(d, void slotColorDoubleClicked( const QColor &col, const QString &name ))
317 Q_PRIVATE_SLOT(d, void slotColorPicker())
318 Q_PRIVATE_SLOT(d, void slotAddToCustomColors())
319 Q_PRIVATE_SLOT(d, void slotDefaultColorClicked())
320 Q_PRIVATE_SLOT(d, void slotModeChanged( int id ))
321
322 /**
323 * Write the settings of the dialog to config file.
324 **/
325 Q_PRIVATE_SLOT(d, void slotWriteSettings())
326
327 private:
328 /**
329 * Read the settings for the dialog from config file.
330 **/
331 void readSettings();
332
333 protected:
334 virtual void mouseMoveEvent( QMouseEvent * );
335 virtual void mouseReleaseEvent( QMouseEvent * );
336 virtual void keyPressEvent( QKeyEvent * );
337 virtual bool eventFilter( QObject *obj, QEvent *ev );
338
339 private:
340 class KColorDialogPrivate;
341 KColorDialogPrivate *const d;
342
343 Q_DISABLE_COPY(KColorDialog)
344};
345
346#endif // KCOLORDIALOG_H
347