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

source code of kwidgetsaddons/src/kxyselector.h