1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 2004 Antonio Larrosa <larrosa@kde.org>
4
5 SPDX-License-Identifier: LGPL-2.0-or-later
6*/
7
8#ifndef KPIXMAPREGIONSELECTORWIDGET_H
9#define KPIXMAPREGIONSELECTORWIDGET_H
10
11#include <kwidgetsaddons_export.h>
12
13#include <QPixmap>
14#include <QWidget>
15#include <memory>
16
17class QMenu;
18
19/*!
20 * \class KPixmapRegionSelectorWidget
21 * \inmodule KWidgetsAddons
22 *
23 * \brief KPixmapRegionSelectorWidget is a widget that shows a picture and provides the
24 * user with a friendly way to select a rectangular subregion of the pixmap.
25 *
26 * \image kpixmapregionselectorwidget.png "KPixmapRegionSelectorWidget"
27 */
28class KWIDGETSADDONS_EXPORT KPixmapRegionSelectorWidget : public QWidget
29{
30 Q_OBJECT
31 /*!
32 * \property KPixmapRegionSelectorWidget::pixmap
33 */
34 Q_PROPERTY(QPixmap pixmap READ pixmap WRITE setPixmap)
35
36public:
37 /*!
38 * This enum provides a rotation direction.
39 * \sa KPixmapRegionSelectorWidget::rotate()
40 *
41 * \value Rotate90 Rotate 90 degrees to the right.
42 * \value Rotate180 Rotate 180 degrees.
43 * \value Rotate270 Rotate 90 degrees to the left.
44 */
45 enum RotateDirection {
46 Rotate90,
47 Rotate180,
48 Rotate270
49 };
50
51 /*!
52 * Constructor for a KPixmapRegionSelectorWidget.
53 */
54 explicit KPixmapRegionSelectorWidget(QWidget *parent = nullptr);
55
56 ~KPixmapRegionSelectorWidget() override;
57
58 /*!
59 * Sets the pixmap which will be shown for the user to select a region from.
60 *
61 * \a pixmap The pixmap. Must be non-null.
62 */
63 void setPixmap(const QPixmap &pixmap);
64
65 /*!
66 * Returns the original whole pixmap that we're using in this widget as the
67 * pixmap the user is selecting a region from.
68 */
69 QPixmap pixmap() const;
70
71 /*!
72 * Sets the selected region to be \a rect (in zoomed pixmap coordinates)
73 */
74 void setSelectedRegion(const QRect &rect);
75
76 /*!
77 * Returns the selected region ( in zoomed pixmap coordinates )
78 */
79 QRect selectedRegion() const;
80
81 /*!
82 * Returns the selected region ( in unzoomed, original pixmap coordinates )
83 */
84 QRect unzoomedSelectedRegion() const;
85
86 /*!
87 * Resets the selection to use the whole image
88 */
89 void resetSelection();
90
91 /*!
92 * Returns a QImage object with just the region the user selected from the
93 * image
94 */
95 QImage selectedImage() const;
96
97 /*!
98 * Sets the aspect ration that the selected subimage should have. The way to
99 * select it, is specifying an example valid \a width and \a height.
100 * \sa setFreeSelectionAspectRatio()
101 */
102 void setSelectionAspectRatio(int width, int height);
103
104 /*!
105 * Allows the user to do a selection which has any aspect ratio. This is
106 * the default.
107 * \sa setSelectionAspectRatio()
108 */
109 void setFreeSelectionAspectRatio();
110
111 /*!
112 * Sets the maximum size for the widget. If the image is larger than this
113 * (either horizontally or vertically), it's scaled to adjust to the maximum
114 * size (preserving the aspect ratio)
115 */
116 void setMaximumWidgetSize(int width, int height);
117
118 /*!
119 * Rotates the image as specified by the \a direction parameter, also tries
120 * to rotate the selected region so that it doesn't change, as long as the
121 * forced aspect ratio setting is respected, in other case, the selected region
122 * is reset.
123 */
124 void rotate(RotateDirection direction);
125
126public Q_SLOTS:
127 /*!
128 * Rotates the current image 90º clockwise
129 */
130 void rotateClockwise();
131 /*!
132 * Rotates the current image 90º counterclockwise
133 */
134 void rotateCounterclockwise();
135
136Q_SIGNALS:
137 /*!
138 *
139 */
140 void pixmapRotated();
141
142protected:
143 /*!
144 * Creates a QMenu with the menu that appears when clicking with the right button on the label
145 */
146 virtual QMenu *createPopupMenu();
147
148 bool eventFilter(QObject *obj, QEvent *ev) override;
149
150private:
151 friend class KPixmapRegionSelectorWidgetPrivate;
152 std::unique_ptr<class KPixmapRegionSelectorWidgetPrivate> const d;
153
154 Q_DISABLE_COPY(KPixmapRegionSelectorWidget)
155};
156
157#endif
158

source code of kwidgetsaddons/src/kpixmapregionselectorwidget.h