Plasma-framework

dialog.h
1/*
2 SPDX-FileCopyrightText: 2011 Marco Martin <mart@kde.org>
3 SPDX-FileCopyrightText: 2013 Sebastian K├╝gler <sebas@kde.org>
4
5 SPDX-License-Identifier: GPL-2.0-or-later
6*/
7#ifndef DIALOG_PROXY_P
8#define DIALOG_PROXY_P
9
10#include <QPoint>
11#include <QQmlParserStatus>
12#include <QQuickItem>
13#include <QQuickWindow>
14#include <QScopedPointer>
15
16#include <Plasma/Plasma>
17#include <Plasma/Theme>
18
19#include <netwm_def.h>
20
21#include <plasmaquick/plasmaquick_export.h>
22
23//
24// W A R N I N G
25// -------------
26//
27// This file is not part of the public Plasma API. It exists purely as an
28// implementation detail. This header file may change from version to
29// version without notice, or even be removed.
30//
31// We mean it.
32//
33
34class QQuickItem;
35class QScreen;
36
37namespace PlasmaQuick
38{
39class DialogPrivate;
40
41/**
42 * Dialog creates a Plasma themed top level window that can contain any QML component.
43 *
44 * It can be automatically positioned relative to a visual parent
45 * The dialog will resize to the size of the main item
46 *
47 * @code{.qml}
48 * import QtQuick 2.0
49 * import org.kde.plasma.core as PlasmaCore
50 * Item {
51 * PlasmaCore.Dialog {
52 * visible: true
53 * mainItem: Item {
54 * width: 500
55 * height: 500
56 *
57 * Text {
58 * anchors.centerIn: parent
59 * color: "red"
60 * text: "text"
61 * }
62 * }
63 * }
64 * }
65 * @endcode
66 *
67 * <b>Import Statement</b>
68 * @code import org.kde.plasma.core @endcode
69 * @version 2.0
70 */
71class PLASMAQUICK_EXPORT Dialog : public QQuickWindow, public QQmlParserStatus
72{
73 Q_OBJECT
74 Q_INTERFACES(QQmlParserStatus)
75
76 /**
77 * The main QML item that will be displayed in the Dialog
78 */
79 Q_PROPERTY(QQuickItem *mainItem READ mainItem WRITE setMainItem NOTIFY mainItemChanged)
80
81 /**
82 * The main QML item that will be displayed in the Dialog
83 */
84 Q_PROPERTY(QQuickItem *visualParent READ visualParent WRITE setVisualParent NOTIFY visualParentChanged)
85
86 /**
87 * Margins of the dialog around the mainItem.
88 * @see DialogMargins
89 */
90 Q_PROPERTY(QObject *margins READ margins CONSTANT)
91
92 /**
93 * Margins where the dialog background actually starts, excluiding things like shadows or borders
94 * @see DialogMargins
95 * @since 5.77
96 */
97 Q_PROPERTY(QObject *inset READ inset CONSTANT)
98
99 /**
100 * Plasma Location of the dialog window. Useful if this dialog is a popup for a panel
101 */
102 Q_PROPERTY(Plasma::Types::Location location READ location WRITE setLocation NOTIFY locationChanged)
103
104 /**
105 * Type of the window
106 */
107 Q_PROPERTY(WindowType type READ type WRITE setType NOTIFY typeChanged)
108
109 /**
110 * Whether the dialog should be hidden when the dialog loses focus.
111 *
112 * The default value is @c false.
113 **/
114 Q_PROPERTY(bool hideOnWindowDeactivate READ hideOnWindowDeactivate WRITE setHideOnWindowDeactivate NOTIFY hideOnWindowDeactivateChanged)
115
116 /**
117 * Whether the dialog is output only. Default value is @c false. If it is @c true
118 * the dialog does not accept input and all pointer events are not accepted, thus the dialog
119 * is click through.
120 *
121 * This property is currently only supported on the X11 platform. On any other platform the
122 * property has no effect.
123 **/
124 Q_PROPERTY(bool outputOnly READ isOutputOnly WRITE setOutputOnly NOTIFY outputOnlyChanged)
125
126 /**
127 * This property holds the window flags of the window.
128 * The window flags control the window's appearance in the windowing system,
129 * whether it's a dialog, popup, or a regular window, and whether it should
130 * have a title bar, etc.
131 * Regardless to what the user sets, the flags will always have the
132 * FramelessWindowHint flag set
133 */
134 Q_PROPERTY(Qt::WindowFlags flags READ flags WRITE setFramelessFlags NOTIFY flagsChanged)
135
136 /**
137 * This property holds how (and if at all) the dialog should draw its own background
138 * or if it is complete responsibility of the content item to render a background.
139 * Note that in case of NoBackground it loses kwin side shadows and blur
140 */
141 Q_PROPERTY(BackgroundHints backgroundHints READ backgroundHints WRITE setBackgroundHints NOTIFY backgroundHintsChanged)
142
143 Q_PROPERTY(bool visible READ isVisible WRITE setVisible NOTIFY visibleChangedProxy)
144
145 /**
146 * This property holds by how much the applet should be floating even if the location
147 * is set to a certain screen side; if this value is positive, the dialog will draw
148 * all four sides and maintain the required distance from the screen borders.
149 */
150 Q_PROPERTY(int floating READ floating WRITE setFloating NOTIFY floatingChanged)
151
152 /**
153 * This property holds a pointer to the AppletInterface used by an applet. It is
154 * null when the dialog is not used for an applet.
155 */
156 // TODO: plasmoidItem?
157 Q_PROPERTY(QQuickItem *appletInterface READ appletInterface WRITE setAppletInterface NOTIFY appletInterfaceChanged)
158
159 Q_CLASSINFO("DefaultProperty", "mainItem")
160
161public:
162 enum WindowType {
163 Normal = NET::Normal,
164 Dock = NET::Dock,
166 PopupMenu = NET::PopupMenu,
167 Tooltip = NET::Tooltip,
168 Notification = NET::Notification,
169 OnScreenDisplay = NET::OnScreenDisplay,
170 CriticalNotification = NET::CriticalNotification,
172 };
173 Q_ENUM(WindowType)
174
176 NoBackground = 0, /**< Not drawing a background under the applet, the dialog has its own implementation */
177 StandardBackground = 1, /**< The standard background from the theme is drawn */
178 SolidBackground = 2, /**< The solid version of the background is preferred */
179 };
180 Q_ENUM(BackgroundHints)
181
182 explicit Dialog(QQuickItem *parent = nullptr);
183 ~Dialog() override;
184
185 // PROPERTIES ACCESSORS
186 QQuickItem *mainItem() const;
187 void setMainItem(QQuickItem *mainItem);
188
189 QQuickItem *visualParent() const;
190 void setVisualParent(QQuickItem *visualParent);
191
192 Plasma::Types::Location location() const;
193 void setLocation(Plasma::Types::Location location);
194
195 QObject *margins() const;
196 QObject *inset() const;
197
198 void setFramelessFlags(Qt::WindowFlags flags);
199
200 void setType(WindowType type);
201 WindowType type() const;
202
203 bool hideOnWindowDeactivate() const;
204 void setHideOnWindowDeactivate(bool hide);
205
206 void setOutputOnly(bool outputOnly);
207 bool isOutputOnly() const;
208
209 BackgroundHints backgroundHints() const;
210 void setBackgroundHints(BackgroundHints hints);
211
212 bool isVisible() const;
213 void setVisible(bool visible);
214
215 int floating() const;
216 void setFloating(int floating);
217
218 QQuickItem *appletInterface() const;
219 void setAppletInterface(QQuickItem *appletInterface);
220
221 /**
222 * @returns The suggested screen position for the popup
223 * @param item the item the popup has to be positioned relatively to. if null, the popup will be positioned in the center of the window
224 * @param size the size that the popup will have, which influences the final position
225 */
226 virtual QPoint popupPosition(QQuickItem *item, const QSize &size);
227
228Q_SIGNALS:
229 void mainItemChanged();
230 void locationChanged();
231 void visualParentChanged();
232 void typeChanged();
233 void hideOnWindowDeactivateChanged();
234 void outputOnlyChanged();
235 void flagsChanged();
236 void floatingChanged();
237 void backgroundHintsChanged();
238 void visibleChangedProxy(); // redeclaration of QQuickWindow::visibleChanged
239 void appletInterfaceChanged();
240 /**
241 * Emitted when the @see hideOnWindowDeactivate property is @c true and this dialog lost focus to a
242 * window that is neither a parent dialog to nor a child dialog of this dialog.
243 */
245
246protected:
247 /**
248 * set the dialog position. subclasses may change it. ToolTipDialog adjusts the position in an animated way
249 */
250 virtual void adjustGeometry(const QRect &geom);
251
252 // Reimplementations
253 void classBegin() override;
254 void componentComplete() override;
255 void resizeEvent(QResizeEvent *re) override;
256 void focusInEvent(QFocusEvent *ev) override;
257 void focusOutEvent(QFocusEvent *ev) override;
258 void showEvent(QShowEvent *event) override;
259 void hideEvent(QHideEvent *event) override;
260 void moveEvent(QMoveEvent *) override;
261 bool event(QEvent *event) override;
262
263private:
264 friend class DialogPrivate;
266
267 Q_PRIVATE_SLOT(d, void updateTheme())
268 Q_PRIVATE_SLOT(d, void updateVisibility(bool visible))
269
270 Q_PRIVATE_SLOT(d, void updateMinimumWidth())
271 Q_PRIVATE_SLOT(d, void updateMinimumHeight())
272 Q_PRIVATE_SLOT(d, void updateMaximumWidth())
273 Q_PRIVATE_SLOT(d, void updateMaximumHeight())
274 Q_PRIVATE_SLOT(d, void updateLayoutParameters())
275
276 Q_PRIVATE_SLOT(d, void slotMainItemSizeChanged())
277};
278
279}
280
281#endif
Notification
OnScreenDisplay
AppletPopup
CriticalNotification
The AppletPopup class shows a popup for an applet either in the panel or on the desktop.
Definition appletpopup.h:30
Dialog creates a Plasma themed top level window that can contain any QML component.
Definition dialog.h:72
void windowDeactivated()
Emitted when the.
Location
The Location enumeration describes where on screen an element, such as an Applet or its managing cont...
Definition plasma.h:81
The EdgeEventForwarder class This class forwards edge events to be replayed within the given margin T...
Definition action.h:20
Namespace for everything in libplasma.
typedef WindowFlags
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Jun 7 2024 12:00:05 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.