Kirigami2

AbstractApplicationWindow.qml
1/*
2 * SPDX-FileCopyrightText: 2015 Marco Martin <mart@kde.org>
3 *
4 * SPDX-License-Identifier: LGPL-2.0-or-later
5 */
6
7import QtQuick
8import QtQuick.Controls as QQC2
9import QtQuick.Templates as T
10import org.kde.kirigami as Kirigami
11import "templates/private" as TP
12
13/**
14 * A window that provides some basic features needed for all apps
15 * Use this class only if you need a custom content for your application,
16 * different from the Page Row behavior recommended by the HIG and provided
17 * by ApplicationWindow.
18 * It is recommended to use ApplicationWindow instead
19 * @see ApplicationWindow
20 *
21 * It's usually used as a root QML component for the application.
22 * It provides support for a central page stack, side drawers, and
23 * basic support for the Android back button.
24 *
25 * Setting a width and height property on the ApplicationWindow
26 * will set its initial size, but it won't set it as an automatically binding.
27 * to resize programmatically the ApplicationWindow they need to
28 * be assigned again in an imperative fashion
29 *
30 *
31 * Example usage:
32 * @code
33 * import org.kde.kirigami as Kirigami
34 *
35 * Kirigami.ApplicationWindow {
36 * [...]
37 * globalDrawer: Kirigami.GlobalDrawer {
38 * actions: [
39 * Kirigami.Action {
40 * text: "View"
41 * icon.name: "view-list-icons"
42 * Kirigami.Action {
43 * text: "action 1"
44 * }
45 * Kirigami.Action {
46 * text: "action 2"
47 * }
48 * Kirigami.Action {
49 * text: "action 3"
50 * }
51 * },
52 * Kirigami.Action {
53 * text: "Sync"
54 * icon.name: "folder-sync"
55 * }
56 * ]
57 * }
58 *
59 * contextDrawer: Kirigami.ContextDrawer {
60 * id: contextDrawer
61 * }
62 *
63 * pageStack: PageStack {
64 * ...
65 * }
66 * [...]
67 * }
68 * @endcode
69 *
70 * @inherit QtQuick.Controls.ApplicationWindow
71 */
72QQC2.ApplicationWindow {
73 id: root
74
75//BEGIN properties
76 /**
77 * @brief This property holds the stack used to allocate the pages and to manage the
78 * transitions between them.
79 *
80 * Put a container here, such as QtQuick.Controls.StackView.
81 */
82 property Item pageStack
83
84 /**
85 * @brief This property sets whether the standard chrome of the app is visible.
86 *
87 * These are the action button, the drawer handles, and the application header.
88 *
89 * default: ``true``
90 */
91 property bool controlsVisible: true
92
93 /**
94 * @brief This property holds the drawer for global actions.
95 *
96 * This drawer can be opened by sliding from the left screen edge
97 * or by dragging the ActionButton to the right.
98 *
99 * @note It is recommended to use the GlobalDrawer here.
100 * @property org::kde::kirigami::OverlayDrawer globalDrawer
101 */
102 property OverlayDrawer globalDrawer
103
104 /**
105 * @brief This property tells whether the application is in "widescreen" mode.
106 *
107 * This is enabled on desktops or horizontal tablets.
108 *
109 * @note Different styles can have their own logic for deciding this.
110 */
111 property bool wideScreen: width >= Kirigami.Units.gridUnit * 60
112
113 /**
114 * @brief This property holds the drawer for context-dependent actions.
115 *
116 * The drawer that will be opened by sliding from the right screen edge
117 * or by dragging the ActionButton to the left.
118 *
119 * @note It is recommended to use the ContextDrawer type here.
120 *
121 * The contents of the context drawer should depend from what page is
122 * loaded in the main pageStack
123 *
124 * Example usage:
125 *
126 * @code
127 * import org.kde.kirigami as Kirigami
128 *
129 * Kirigami.ApplicationWindow {
130 * contextDrawer: Kirigami.ContextDrawer {
131 * enabled: true
132 * actions: [
133 * Kirigami.Action {
134 * icon.name: "edit"
135 * text: "Action text"
136 * onTriggered: {
137 * // do stuff
138 * }
139 * },
140 * Kirigami.Action {
141 * icon.name: "edit"
142 * text: "Action text"
143 * onTriggered: {
144 * // do stuff
145 * }
146 * }
147 * ]
148 * }
149 * }
150 * @endcode
152 * @property org::kde::kirigami::ContextDrawer contextDrawer
153 */
154 property OverlayDrawer contextDrawer
155
156 /**
157 * Effectively the same as T.Overlay.overlay
158 */
159 readonly property Item overlay: T.Overlay.overlay
160
161 /**
162 * This property holds a standard action that will quit the application when triggered.
163 * Its properties have the following values:
164 *
165 * @code
166 * Action {
167 * text: "Quit"
168 * icon.name: "application-exit-symbolic"
169 * shortcut: StandardKey.Quit
170 * // ...
171 * }
172 * @endcode
173 * @since 5.76
174 */
175 readonly property Kirigami.Action quitAction: Kirigami.Action {
176 text: qsTr("Quit")
177 icon.name: "application-exit";
178 shortcut: StandardKey.Quit
179 onTriggered: source => root.close();
180 }
181//END properties
183//BEGIN functions
184 /**
185 * @brief This function shows a little passive notification at the bottom of the app window
186 * lasting for few seconds, with an optional action button.
188 * @param message The text message to be shown to the user.
189 * @param timeout How long to show the message:
190 * possible values: "short", "long" or the number of milliseconds
191 * @param actionText Text in the action button, if any.
192 * @param callBack A JavaScript function that will be executed when the
193 * user clicks the button.
194 */
195 function showPassiveNotification(message, timeout, actionText, callBack) {
196 notificationsObject.showNotification(message, timeout, actionText, callBack);
197 }
198
199 /**
200 * @brief This function hides the passive notification at specified index, if any is shown.
201 * @param index Index of the notification to hide. Default is 0 (oldest notification).
202 */
203 function hidePassiveNotification(index = 0) {
204 notificationsObject.hideNotification(index);
205 }
206
207 /**
208 * @brief This function returns application window's object anywhere in the application.
209 * @returns a pointer to this application window
210 * can be used anywhere in the application.
211 */
212 function applicationWindow() {
213 return root;
214 }
215//END functions
216
217 LayoutMirroring.enabled: Qt.application.layoutDirection === Qt.RightToLeft
218 LayoutMirroring.childrenInherit: true
219
220 color: Kirigami.Theme.backgroundColor
221
222 TP.PassiveNotificationsManager {
223 id: notificationsObject
224 anchors.bottom: parent.bottom
225 anchors.horizontalCenter: parent.horizontalCenter
226 z: 1
227 }
228
229 contentItem.z: 1
230 contentItem.anchors.left: contentItem.parent.left
231 contentItem.anchors.right: contentItem.parent.right
232 contentItem.anchors.topMargin: root.wideScreen && header && controlsVisible ? header.height : 0
233 contentItem.anchors.leftMargin: root.globalDrawer && root.globalDrawer.modal === false && (!root.pageStack || root.pageStack.leftSidebar !== root.globalDrawer) ? root.globalDrawer.width * root.globalDrawer.position : 0
234 contentItem.anchors.rightMargin: root.contextDrawer && root.contextDrawer.modal === false ? root.contextDrawer.width * root.contextDrawer.position : 0
235
236 Binding {
237 target: root.menuBar
238 property: "x"
239 value: -contentItem.x
240 }
241 Binding {
242 target: root.header
243 property: "x"
244 value: -contentItem.x
245 }
246 Binding {
247 target: root.footer
248 property: "x"
249 value: -contentItem.x
250 }
251
252 // Don't use root.overlay property here. For one, we know that in a window
253 // it will always be the same as T.Overlay.overlay; secondly Drawers
254 // don't care about being contained/parented to anything else anyway.
255 onGlobalDrawerChanged: {
256 if (globalDrawer) {
257 globalDrawer.parent = Qt.binding(() => T.Overlay.overlay);
258 }
259 }
260 onContextDrawerChanged: {
261 if (contextDrawer) {
262 contextDrawer.parent = Qt.binding(() => T.Overlay.overlay);
263 }
264 }
265 onPageStackChanged: {
266 if (pageStack) {
267 // contentItem is declared as CONSTANT, so binding isn't needed.
268 pageStack.parent = contentItem;
269 }
270 }
271
272 width: Kirigami.Settings.isMobile ? Kirigami.Units.gridUnit * 30 : Kirigami.Units.gridUnit * 55
273 height: Kirigami.Settings.isMobile ? Kirigami.Units.gridUnit * 45 : Kirigami.Units.gridUnit * 40
274 visible: true
275
276 Component.onCompleted: {
277 // Explicitly break the binding as we need this to be set only at startup.
278 // if the bindings are active, after this the window is resized by the
279 // compositor and then the bindings are reevaluated, then the window
280 // size would reset ignoring what the compositor asked.
281 // see BUG 433849
282 root.width = root.width;
283 root.height = root.height;
284 }
285
286 // This is needed because discover in mobile mode does not
287 // close with the global drawer open.
288 Shortcut {
289 sequence: root.quitAction.shortcut
290 enabled: root.quitAction.enabled
291 context: Qt.ApplicationShortcut
292 onActivated: root.close();
293 }
294}
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Jun 7 2024 11:59:11 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.