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#ifndef KXYSELECTOR_H
21#define KXYSELECTOR_H
22
23#include <kdeui_export.h>
24
25#include <QtGui/QWidget>
26#include <QtGui/QPixmap>
27
28/**
29 * KXYSelector is the base class for other widgets which
30 * provides the ability to choose from a two-dimensional
31 * range of values. The currently chosen value is indicated
32 * by a cross. An example is the KHSSelector which
33 * allows to choose from a range of colors, and which is
34 * used in KColorDialog.
35 *
36 * A custom drawing routine for the widget surface has
37 * to be provided by the subclass.
38 */
39class KDEUI_EXPORT KXYSelector : public QWidget
40{
41 Q_OBJECT
42 Q_PROPERTY( int xValue READ xValue WRITE setXValue )
43 Q_PROPERTY( int yValue READ yValue WRITE setYValue )
44
45public:
46 /**
47 * Constructs a two-dimensional selector widget which
48 * has a value range of [0..100] in both directions.
49 */
50 explicit KXYSelector( QWidget *parent=0 );
51 /**
52 * Destructs the widget.
53 */
54 ~KXYSelector();
55
56 /**
57 * Sets the current values in horizontal and
58 * vertical direction.
59 * @param xPos the horizontal value
60 * @param yPos the vertical value
61 */
62 void setValues( int xPos, int yPos );
63
64 /**
65 * Sets the current horizontal value
66 * @param xPos the horizontal value
67 */
68 void setXValue( int xPos );
69
70 /**
71 * Sets the current vertical value
72 * @param yPos the vertical value
73 */
74 void setYValue( int yPos );
75
76 /**
77 * Sets the range of possible values.
78 */
79 void setRange( int minX, int minY, int maxX, int maxY );
80
81 /**
82 * Sets the color used to draw the marker
83 * @param col the color
84 */
85 void setMarkerColor( const QColor &col );
86
87 /**
88 * @return the current value in horizontal direction.
89 */
90 int xValue() const;
91 /**
92 * @return the current value in vertical direction.
93 */
94 int yValue() const;
95
96 /**
97 * @return the rectangle on which subclasses should draw.
98 */
99 QRect contentsRect() const;
100
101 /**
102 * Reimplemented to give the widget a minimum size
103 */
104 virtual QSize minimumSizeHint() const;
105
106Q_SIGNALS:
107 /**
108 * This signal is emitted whenever the user chooses a value,
109 * e.g. by clicking with the mouse on the widget.
110 */
111 void valueChanged( int x, int y );
112
113protected:
114 /**
115 * Override this function to draw the contents of the widget.
116 * The default implementation does nothing.
117 *
118 * Draw within contentsRect() only.
119 */
120 virtual void drawContents( QPainter * );
121
122 /**
123 * Override this function to draw the marker which
124 * indicates the currently selected value pair.
125 */
126 virtual void drawMarker( QPainter *p, int xp, int yp );
127
128 virtual void paintEvent( QPaintEvent *e );
129 virtual void mousePressEvent( QMouseEvent *e );
130 virtual void mouseMoveEvent( QMouseEvent *e );
131 virtual void wheelEvent( QWheelEvent * );
132
133 /**
134 * Converts a pixel position to its corresponding values.
135 */
136 void valuesFromPosition( int x, int y, int& xVal, int& yVal ) const;
137
138private:
139 void setPosition( int xp, int yp );
140
141private:
142 class Private;
143 friend class Private;
144 Private * const d;
145
146 Q_DISABLE_COPY(KXYSelector)
147};
148
149#endif /* KXYSELECTOR_H */
150