1/* This file is part of the KDE libraries
2 Copyright (C) 2004 Antonio Larrosa <larrosa@kde.org
3
4 This library is free software; you can redistribute it and/or
5 modify it under the terms of the GNU Library General Public
6 License as published by the Free Software Foundation; either
7 version 2 of the License, or (at your option) any later version.
8
9 This library is distributed in the hope that it will be useful,
10 but WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 Library General Public License for more details.
13
14 You should have received a copy of the GNU Library General Public License
15 along with this library; see the file COPYING.LIB. If not, write to
16 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
17 Boston, MA 02110-1301, USA.
18*/
19
20#ifndef KPIXMAPREGIONSELECTORDIALOG_H
21#define KPIXMAPREGIONSELECTORDIALOG_H
22
23#include <kdialog.h>
24
25class KPixmapRegionSelectorWidget;
26
27class QImage;
28
29/**
30 * A dialog that uses a KPixmapRegionSelectorWidget to allow the user
31 * to select a region of an image. If you want to use special features
32 * like forcing the selected area to have a fixed aspect ratio, you can use
33 * @see pixmapRegionSelectorWidget() to get the pointer to the
34 * KPixmapRegionSelectorWidget object and set the desired options there.
35 *
36 * There are some convenience methods that allow to easily show a dialog
37 * for the user to select a region of an image, and just care about the selected
38 * image.
39 *
40 * \image html kpixmapregionselectordialog.png "KDE Pixmap Region Selector Dialog"
41 *
42 * @author Antonio Larrosa <larrosa@kde.org>
43 */
44class KDEUI_EXPORT KPixmapRegionSelectorDialog : public KDialog
45{
46Q_OBJECT
47public:
48 /**
49 * The constructor of an empty KPixmapRegionSelectorDialog, you have to call
50 * later the setPixmap method of the KPixmapRegionSelectorWidget widget of
51 * the new object.
52 */
53 explicit KPixmapRegionSelectorDialog( QWidget *parent = 0 );
54
55 /**
56 * The destructor of the dialog
57 */
58 ~KPixmapRegionSelectorDialog();
59
60 /**
61 * @returns the KPixmapRegionSelectorWidget widget so that additional
62 * parameters can be set by using it.
63 */
64 KPixmapRegionSelectorWidget *pixmapRegionSelectorWidget() const;
65
66 /**
67 * Creates a modal dialog, lets the user to select a region of the @p pixmap
68 * and returns when the dialog is closed.
69 *
70 * @returns the selected rectangle, or an invalid rectangle if the user
71 * pressed the Cancel button.
72 */
73 static QRect getSelectedRegion( const QPixmap &pixmap, QWidget *parent = 0L );
74
75 /**
76 * Creates a modal dialog, lets the user to select a region of the @p pixmap
77 * with the same aspect ratio than @p aspectRatioWidth x @p aspectRatioHeight
78 * and returns when the dialog is closed.
79 *
80 * @returns the selected rectangle, or an invalid rectangle if the user
81 * pressed the Cancel button.
82 */
83 static QRect getSelectedRegion( const QPixmap &pixmap, int aspectRatioWidth,
84 int aspectRatioHeight, QWidget *parent = 0L );
85
86 /**
87 * Creates a modal dialog, lets the user to select a region of the @p pixmap
88 * and returns when the dialog is closed.
89 *
90 * @returns the selected image, or an invalid image if the user
91 * pressed the Cancel button.
92 */
93 static QImage getSelectedImage( const QPixmap &pixmap, QWidget *parent = 0L );
94
95 /**
96 * Creates a modal dialog, lets the user to select a region of the @p pixmap
97 * with the same aspect ratio than @p aspectRatioWidth x @p aspectRatioHeight
98 * and returns when the dialog is closed.
99 *
100 * @returns the selected image, or an invalid image if the user
101 * pressed the Cancel button.
102 */
103 static QImage getSelectedImage( const QPixmap &pixmap, int aspectRatioWidth,
104 int aspectRatioHeight, QWidget *parent = 0L );
105
106 /**
107 * @since 4.4.3
108 * Adjusts the size of the KPixmapRegionSelectorWidget to not overflow the screen size
109 */
110 void adjustRegionSelectorWidgetSizeToFitScreen();
111
112private:
113 class Private;
114 Private* const d;
115
116 Q_PRIVATE_SLOT( d, void _k_adjustPixmapSize() )
117
118 Q_DISABLE_COPY( KPixmapRegionSelectorDialog )
119};
120
121
122#endif
123