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