Krita

AngleSelector.h
1/*
2 * SPDX-FileCopyrightText: 2020 Deif Lou <ginoba@gmail.com>
3 *
4 * SPDX-License-Identifier: GPL-2.0-or-later
5 */
6#ifndef LIBKIS_ANGLESELECTOR_H
7#define LIBKIS_ANGLESELECTOR_H
8
9#include "KisAngleSelector.h"
10
11#include "kritalibkis_export.h"
12#include "libkis.h"
13
14/**
15 * @brief A wrapper around KisAngleSelector, a widget with several options to
16 * select an angle. The widget itself is accessed with the widget() function.
17 *
18 * This widget is a combination of a @ref KisAngleGauge and a spin box,
19 * along with some flipping options
20 */
21class KRITALIBKIS_EXPORT AngleSelector : public QObject
22{
23 Q_OBJECT
24 Q_DISABLE_COPY(AngleSelector)
25
26public:
27 explicit AngleSelector();
28 ~AngleSelector() override;
29
30public Q_SLOTS:
31
32 /**
33 * @brief Get the internal KisAngleSelector as a QWidget, so it may be
34 * added to a UI
35 *
36 * @return the internal KisAngleSelector as a QWidget
37 */
38 QWidget* widget() const;
39
40 /**
41 * @brief Sets the current angle
42 * @param newAngle the new angle
43 * @see angle() const
44 */
45 void setAngle(qreal newAngle);
46 /**
47 * @brief Sets the current angle to the reset angle
48 * @see resetAngle() const
49 * @see setResetAngle(qreal) const
50 */
51 void reset();
52
53 /**
54 * @brief Gets the current angle
55 * @return The current angle
56 * @see setAngle(qreal)
57 */
58 qreal angle() const;
59 /**
60 * @brief Gets the angle to which multiples the selected angle will snap
61 *
62 * The default snap angle is 15 degrees so the selected angle will snap
63 * to its multiples (0, 15, 30, 45, etc.)
64 * @return The angle to which multiples the selected angle will snap
65 * @see setSnapAngle(qreal)
66 */
67 qreal snapAngle() const;
68 /**
69 * @brief Gets the angle that is used to reset the current angle
70 *
71 * This angle is used when the user double clicks on the widget
72 * @return The angle that is used to reset the current angle
73 * @see setResetAngle(qreal)
74 */
75 qreal resetAngle() const;
76 /**
77 * @brief Gets the number of decimals (precision) used by the angle
78 *
79 * If you want to simulate integer angles, set it to 0. The default is 2.
80 * @return The number of decimals being used
81 * @see setDecimals(int)
82 */
83 int decimals() const;
84 /**
85 * @brief Gets the maximum value for the angle
86 *
87 * The default is 360
88 * @return The maximum value for the angle
89 * @see setMaximum(qreal)
90 * @see setRange(qreal, qreal)
91 */
92 qreal maximum() const;
93 /**
94 * @brief Gets the minimum value for the angle
95 *
96 * The default is 0
97 * @return The minimum value for the angle
98 * @see setMinimum(qreal)
99 * @see setRange(qreal, qreal)
100 */
101 qreal minimum() const;
102 /**
103 * @brief Gets the prefix shown in the spin box
104 * @return The prefix shown in the spin box
105 * @see setPrefix(const QString&)
106 */
107 QString prefix() const;
108 /**
109 * @brief Gets if the angle should wrap pass the minimum or maximum angles
110 * @return True if the angle should wrap pass the minimum or maximum angles,
111 * false otherwise
112 * @see setWrapping(bool)
113 */
114 bool wrapping() const;
115 /**
116 * @brief Gets the mode in which the flip options should be shown
117 *
118 * The default is Buttons
119 * @return The mode in which the flip options should be shown.
120 * @see setFlipOptionsMode(QString)
121 */
122 QString flipOptionsMode() const;
123 /**
124 * @brief Gets the common height of the widgets inside this angle selector
125 * @return The height of the internal widgets (angle gauge, spin box, etc.).
126 * Returns 0 if each widget has its default height.
127 * @see setWidgetsHeight(int)
128 */
129 int widgetsHeight() const;
130 /**
131 * @brief Gets the direction in which the angle increases in the angle gauge
132 * @return The direction in which the angle increases
133 * @see setIncreasingDirection(QString)
134 */
135 QString increasingDirection() const;
136 /**
137 * @brief Gets if the spin box is flat (no border or background)
138 * @return True if the spin box is flat, false otherwise
139 * @see useFlatSpinBox(bool)
140 */
141 bool isUsingFlatSpinBox() const;
142
143 /**
144 * @brief Sets the angle to which multiples the selected angle will snap
145 * @param newSnapAngle the new angle to which multiples the selected angle will snap
146 * @see snapAngle() const
147 */
148 void setSnapAngle(qreal newSnapAngle);
149 /**
150 * @brief Sets the angle that is used to reset the current angle
151 * @param newResetAngle the new angle that is used to reset the current angle
152 * @see resetAngle() const
153 */
154 void setResetAngle(qreal newResetAngle);
155 /**
156 * @brief Sets the number of decimals (precision) used by the angle
157 * @param newNumberOfDecimals the new number of decimals used by the angle
158 * @see decimals() const
159 */
160 void setDecimals(int newNumberOfDecimals);
161 /**
162 * @brief Sets the maximum value for the angle
163 * @param newMaximum the new maximum value for the angle
164 * @see maximum() const
165 * @see setRange(qreal, qreal)
166 */
167 void setMaximum(qreal newMaximum);
168 /**
169 * @brief Sets the minimum value for the angle
170 * @param newMinimum the new minimum value for the angle
171 * @see minimum() const
172 * @see setRange(qreal, qreal)
173 */
174 void setMinimum(qreal newMinimum);
175 /**
176 * @brief Sets the minimum and maximum values for the angle
177 * @param newMinimum the new minimum value for the angle
178 * @param newMaximum the new maximum value for the angle
179 * @see minimum() const
180 * @see maximum() const
181 * @see setMinimum(qreal)
182 * @see setMaximum(qreal)
183 */
184 void setRange(qreal newMinimum, qreal newMaximum);
185 /**
186 * @brief Sets the prefix shown in the spin box
187 * @param newPrefix the new prefix for the spin box
188 * @see prefix() const
189 */
190 void setPrefix(const QString &newPrefix);
191 /**
192 * @brief Sets if the angle should wrap pass the minimum or maximum angles
193 * @param newWrapping true if the angle should wrap pass the minimum or
194 * maximum angles, false otherwise
195 * @see wrapping() const
196 */
197 void setWrapping(bool newWrapping);
198 /**
199 * @brief Sets the mode in which the flip options should be shown
200 * @param newMode the new mode in which the flip options should be shown
201 * Valid arguments:
202 * <ul>
203 * <li>NoFlipOptions - There are no flip options available</li>
204 * <li>MenuButton - The flip options are shown as a menu accessible via a options button</li>
205 * <li>Buttons - The flip options are shown as individual buttons</li>
206 * <li>ContextMenu - The flip options are shown only as a context menu when right-clicking the gauge widget</li>
207 * <ul>
208 *
209 * @see flipOptionsMode() const
210 */
211 void setFlipOptionsMode(QString newMode);
212 /**
213 * @brief Sets the common height of the widgets inside this angle selector.
214 * Use 0 to reset widgets to default height.
215 * @param newHeight the new height of the internal widgets (angle gauge, spin box, etc.)
216 * @see widgetsHeight() const
217 */
218 void setWidgetsHeight(int newHeight);
219 /**
220 * @brief Sets the increasing direction in the angle gauge
221 * @param newIncreasingDirection The new increasing direction
222 * Valid arguments: CounterClockwise or Clockwise.
223 * @see increasingDirection() const
224 */
225 void setIncreasingDirection(QString newIncreasingDirection);
226 /**
227 * @brief Sets if the spin box should be flat
228 * @param newUseFlatSpinBox True if the spin box should be flat,
229 * false otherwise
230 * @see isUsingFlatSpinBox() const
231 */
232 void useFlatSpinBox(bool newUseFlatSpinBox);
233
234 /**
235 * @brief Gets the closest coterminal angle to the provided angle
236 * that is in the range provided
237 *
238 * A coterminal angle to the provided angle is one that differs
239 * in size by an integer multiple of a turn (360 degrees)
240 * @param angle The reference angle for which the function will try to
241 * find a coterminal angle
242 * @param minimum The range's lower bound
243 * @param maximum The range's upper bound
244 * @param[out] ok This parameter will be set to true if a coterminal
245 * angle exists in the provided range, or to false otherwise
246 * @return The closest coterminal angle in the provided range if one exists,
247 * or the closest value in the range (the minimum or maximum) otherwise.
248 * If the reference angle is already in the range then it is returned
249 */
250 static qreal closestCoterminalAngleInRange(qreal angle, qreal minimum, qreal maximum, bool *ok = nullptr);
251 /**
252 * @brief Gets the closest coterminal angle to the provided angle
253 * that is in the range established
254 *
255 * A coterminal angle to the provided angle is one that differs
256 * in size by an integer multiple of a turn (360 degrees)
257 * @param angle The reference angle for which the function will try to
258 * find a coterminal angle
259 * @param[out] ok This parameter will be set to true if a coterminal
260 * angle exists in the specified range, or to false otherwise
261 * @return The closest coterminal angle in the specified range if one exists,
262 * or the closest value in the range (the minimum or maximum) otherwise.
263 * If the reference angle is already in the range then it is returned
264 */
265 qreal closestCoterminalAngleInRange(qreal angle, bool *ok = nullptr) const;
266 /**
267 * @brief Flips an angle horizontally, vertically, or both
268 *
269 * This function will always try to get the closest angle to the
270 * provided one that satisfies the flipping requirements
271 * @param angle The angle to be flipped
272 * @param orientations Flags indicating in which directions the angle should
273 * be flipped
274 * @return The flipped angle
275 */
276 static qreal flipAngle(qreal angle, Qt::Orientations orientations);
277 /**
278 * @brief Flips an angle horizontally, vertically, or both
279 *
280 * This function will always try to get the closest angle to the
281 * provided one that satisfies the flipping requirements
282 * @param angle The angle to be flipped
283 * @param minimum The lower bound of the valid range
284 * @param maximum The upper bound of the valid range
285 * @param orientations Flags indicating in which directions the angle should
286 * be flipped
287 * @param[out] ok This parameter will be set to true if the flipped
288 * angle is in the provided range, or to false otherwise
289 * @return The flipped angle if it lies in the provided range or the
290 * closest value in the range (the minimum or maximum) otherwise
291 */
292 static qreal flipAngle(qreal angle, qreal minimum, qreal maximum, Qt::Orientations orientations, bool *ok = nullptr);
293 /**
294 * @brief Flips the angle horizontally, vertically, or both
295 *
296 * This function will always try to set the closest angle to the
297 * stablished one that satisfies the flipping requirements
298 * @param orientations Flags indicating in which directions the angle should
299 * be flipped
300 */
301 void flip(Qt::Orientations orientations);
302
303Q_SIGNALS:
304 void angleChanged(qreal angle);
305
306private:
307 struct Private;
308 Private *const d;
309
310};
311
312#endif // LIBKIS_ANGLESELECTOR_H
AngleSelector
A wrapper around KisAngleSelector, a widget with several options to select an angle.
Definition AngleSelector.h:22
QObject::Q_SIGNALS
Q_SIGNALSQ_SIGNALS
QObject::Q_SLOTS
Q_SLOTSQ_SLOTS
Qt::Orientations
typedef Orientations
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri May 3 2024 11:51:43 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.