1/*
2 * Copyright 2008 by Alessandro Diaferia <alediaferia@gmail.com>
3 * Copyright 2007 by Alexis Ménard <darktears31@gmail.com>
4 * Copyright 2007 Sebastian Kuegler <sebas@kde.org>
5 * Copyright 2006 Aaron Seigo <aseigo@kde.org>
6 *
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Lesser General Public
9 * License as published by the Free Software Foundation; either
10 * version 2.1 of the License, or (at your option) any later version.
11 *
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Lesser General Public License for more details.
16 *
17 * You should have received a copy of the GNU Lesser General Public
18 * License along with this library; if not, write to the Free Software
19 * Foundation, Inc., 51 Franklin St, Fifth Floor,
20 * Boston, MA 02110-1301 USA
21 */
22
23#ifndef PLASMA_DIALOG_H
24#define PLASMA_DIALOG_H
25
26#include <QtGui/QWidget>
27#include <QtGui/QGraphicsSceneEvent>
28#include <QtGui/QGraphicsView>
29
30#include <plasma/plasma_export.h>
31#include <plasma/plasma.h>
32
33namespace Plasma
34{
35
36class DialogPrivate;
37
38/**
39 * @class Dialog plasma/dialog.h <Plasma/Dialog>
40 *
41 * @short A dialog that uses the Plasma style
42 *
43 * Dialog provides a dialog-like widget that can be used to display additional
44 * information.
45 *
46 * Dialog uses the plasma theme, and usually has no window decoration. It's meant
47 * as an interim solution to display widgets as extension to plasma applets, for
48 * example when you click on an applet like the devicenotifier or the clock, the
49 * widget that is then displayed, is a Dialog.
50 */
51class PLASMA_EXPORT Dialog : public QWidget
52{
53 Q_OBJECT
54 public:
55 /**
56 * Use these flags to choose the active resize corners.
57 */
58 enum ResizeCorner {
59 NoCorner = 0,
60 NorthEast = 1,
61 SouthEast = 2,
62 NorthWest = 4,
63 SouthWest = 8,
64 All = NorthEast | SouthEast | NorthWest | SouthWest
65 };
66 Q_DECLARE_FLAGS(ResizeCorners, ResizeCorner)
67
68 /**
69 * @param parent the parent widget, for plasmoids, this is usually 0.
70 * @param f the Qt::WindowFlags, default is to not show a windowborder.
71 */
72 explicit Dialog(QWidget * parent = 0, Qt::WindowFlags f = Qt::Window);
73 virtual ~Dialog();
74
75 /**
76 * Sets a QGraphicsWidget to be shown as the content in this dialog.
77 * The dialog will then set up a QGraphicsView and coordinate geometry with
78 * the widget automatically.
79 *
80 * @param widget the QGraphicsWidget to display in this dialog
81 */
82 void setGraphicsWidget(QGraphicsWidget *widget);
83
84 /**
85 * @return the graphics widget shown in this dialog
86 */
87 QGraphicsWidget *graphicsWidget();
88
89 /**
90 * @param corners the corners the resize handlers should be placed in.
91 */
92 void setResizeHandleCorners(ResizeCorners corners);
93
94 /**
95 * Convenience method to get the enabled resize corners.
96 * @return which resize corners are active.
97 */
98 ResizeCorners resizeCorners() const;
99
100 /**
101 * @return true if currently being resized by the user
102 */
103 bool isUserResizing() const;
104
105 /**
106 * Sets the minimum values that each of four sides of the rect may expand to or from
107 *
108 * @param left the screen coordinate that the left may not go beyond; -1 for no limit
109 * @param top the screen coordinate that the top may not go beyond; -1 for no limit
110 * @param right the screen coordinate that the right may not go beyond; -1 for no limit
111 * @param bottom the screen coordinate that the bottom may not go beyond; -1 for no limit
112 */
113 void setMinimumResizeLimits(int left, int top, int right, int bottom);
114
115 /**
116 * Retrives the minimum resize limits for the dialog
117 *
118 * @param left the screen coordinate that the left may not go beyond; -1 for no limit
119 * @param top the screen coordinate that the top may not go beyond; -1 for no limit
120 * @param right the screen coordinate that the right may not go beyond; -1 for no limit
121 * @param bottom the screen coordinate that the bottom may not go beyond; -1 for no limit
122 */
123 void getMinimumResizeLimits(int *left, int *top, int *right, int *bottom);
124
125 /**
126 * Causes an animated hide; requires compositing to work, otherwise
127 * the dialog will simply hide.
128 * @since 4.3
129 */
130 void animatedHide(Plasma::Direction direction);
131
132 /**
133 * Causes an animated show; requires compositing to work, otherwise
134 * the dialog will simply show.
135 * @since 4.3
136 */
137 void animatedShow(Plasma::Direction direction);
138
139 /**
140 * @return the preferred aspect ratio mode for placement and resizing
141 * @since 4.4
142 */
143 Plasma::AspectRatioMode aspectRatioMode() const;
144
145 /**
146 * Sets the preferred aspect ratio mode for placement and resizing
147 * @since 4.4
148 */
149 void setAspectRatioMode(Plasma::AspectRatioMode mode);
150
151 Q_SIGNALS:
152 /**
153 * Fires when the dialog automatically resizes.
154 */
155 void dialogResized();
156
157 /**
158 * Emit a signal when the dialog become visible/invisible
159 */
160 void dialogVisible(bool status);
161
162 public Q_SLOTS:
163 /**
164 * Adjusts the dialog to the associated QGraphicsWidget's geometry
165 * Should not normally need to be called by users of Dialog as Dialog
166 * does it automatically. Event compression may cause unwanted delays,
167 * however, and so this method may be called to immediately cause a
168 * synchronization.
169 * @since 4.5
170 */
171 void syncToGraphicsWidget();
172
173 protected:
174 /**
175 * Reimplemented from QWidget
176 */
177 void paintEvent(QPaintEvent *e);
178 bool event(QEvent *event);
179 void resizeEvent(QResizeEvent *e);
180 bool eventFilter(QObject *watched, QEvent *event);
181 void hideEvent(QHideEvent *event);
182 void showEvent(QShowEvent *event);
183 void focusInEvent(QFocusEvent *event);
184 void mouseMoveEvent(QMouseEvent *event);
185 void mousePressEvent(QMouseEvent *event);
186 void mouseReleaseEvent(QMouseEvent *event);
187 void keyPressEvent(QKeyEvent *event);
188 void moveEvent(QMoveEvent *event);
189
190 /**
191 * Convenience method to know whether the point is in a control area (e.g. resize area)
192 * or not.
193 * @return true if the point is in the control area.
194 */
195 bool inControlArea(const QPoint &point);
196
197 private:
198 DialogPrivate *const d;
199
200 friend class DialogPrivate;
201 /**
202 * React to theme changes
203 */
204 Q_PRIVATE_SLOT(d, void themeChanged())
205 Q_PRIVATE_SLOT(d, void checkBorders())
206 Q_PRIVATE_SLOT(d, void delayedAdjustSize())
207
208 friend class PopupAppletPrivate;
209};
210
211} // Plasma namespace
212
213Q_DECLARE_OPERATORS_FOR_FLAGS(Plasma::Dialog::ResizeCorners)
214
215#endif
216