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

source code of kwidgetsaddons/src/kxyselector.h