Kirigami2

AbstractApplicationItem.qml
1/*
2 * SPDX-FileCopyrightText: 2017 Marco Martin <mart@kde.org>
3 *
4 * SPDX-License-Identifier: LGPL-2.0-or-later
5 */
6
7import QtQuick
8import QtQuick.Templates as T
9
10import org.kde.kirigami as Kirigami
11import "templates/private" as TP
12import "templates" as KT
13
14/**
15 * @brief An item that provides the features of AbstractApplicationWindow without the window itself.
16 *
17 * This allows embedding into a larger application.
18 * Unless you need extra flexibility it is recommended to use ApplicationItem instead.
19 *
20 * Example usage:
21 * @code
22 * import org.kde.kirigami as Kirigami
23 *
24 * Kirigami.AbstractApplicationItem {
25 * [...]
26 * globalDrawer: Kirigami.GlobalDrawer {
27 * actions: [
28 * Kirigami.Action {
29 * text: "View"
30 * icon.name: "view-list-icons"
31 * Kirigami.Action {
32 * text: "action 1"
33 * }
34 * Kirigami.Action {
35 * text: "action 2"
36 * }
37 * Kirigami.Action {
38 * text: "action 3"
39 * }
40 * },
41 * Kirigami.Action {
42 * text: "Sync"
43 * icon.name: "folder-sync"
44 * }
45 * ]
46 * }
47 *
48 * contextDrawer: Kirigami.ContextDrawer {
49 * id: contextDrawer
50 * }
51 *
52 * pageStack: Kirigami.PageRow {
53 * ...
54 * }
55 * [...]
56 * }
57 * @endcode
58 *
59 * @inherit QtQuick.Item
60 */
61Item {
62 id: root
63
64//BEGIN properties
65 /**
66 * @brief This property holds the stack used to allocate the pages and to manage the
67 * transitions between them.
68 *
69 * Put a container here, such as QtQuick.Controls.StackView.
70 */
71 property Item pageStack
72
73 /**
74 * @brief This property holds the font for this item.
75 *
76 * default: ``Kirigami.Theme.defaultFont``
77 */
78 property font font: Kirigami.Theme.defaultFont
80 /**
81 * @brief This property holds the locale for this item.
82 */
83 property Locale locale
84
85 /**
86 * @brief This property holds an item that can be used as a menuBar for the application.
87 */
88 property T.MenuBar menuBar
89
90 /**
91 * @brief This property holds an item that can be used as a title for the application.
92 *
93 * Scrolling the main page will make it taller or shorter (through the point of going away).
94 *
95 * It's a behavior similar to the typical mobile web browser addressbar.
96 *
97 * The minimum, preferred and maximum heights of the item can be controlled with
98 *
99 * * ``Layout.minimumHeight``: default is 0, i.e. hidden
100 * * ``Layout.preferredHeight``: default is Kirigami.Units.gridUnit * 1.6
101 * * ``Layout.maximumHeight``: default is Kirigami.Units.gridUnit * 3
102 *
103 * To achieve a titlebar that stays completely fixed, just set the 3 sizes as the same.
104 *
105 * @property kirigami::templates::AbstractApplicationHeader header
106 */
107 property KT.AbstractApplicationHeader header
108
109 /**
110 * @brief This property holds an item that can be used as a footer for the application.
111 */
112 property Item footer
113
114 /**
115 * @brief This property sets whether the standard chrome of the app is visible.
116 *
117 * These are the action button, the drawer handles and the application header.
118 *
119 * default: ``true``
120 */
121 property bool controlsVisible: true
122
123 /**
124 * @brief This property holds the drawer for global actions.
125 *
126 * Thos drawer can be opened by sliding from the left screen edge
127 * or by dragging the ActionButton to the right.
128 *
129 * @note It is recommended to use the GlobalDrawer here.
130 * @property org::kde::kirigami::OverlayDrawer globalDrawer
131 */
132 property OverlayDrawer globalDrawer
133
134 /**
135 * @brief This property tells us whether the application is in "widescreen" mode.
136 *
137 * This is enabled on desktops or horizontal tablets.
138 *
139 * @note Different styles can have their own logic for deciding this.
140 */
141 property bool wideScreen: width >= Kirigami.Units.gridUnit * 60
142
143 /**
144 * @brief This property holds the drawer for context-dependent actions.
145 *
146 * The drawer that will be opened by sliding from the right screen edge
147 * or by dragging the ActionButton to the left.
148 *
149 * @note It is recommended to use the ContextDrawer type here.
150 *
151 * The contents of the context drawer should depend from what page is
152 * loaded in the main pageStack
153 *
154 * Example usage:
155 *
156 * @code
157 * import org.kde.kirigami as Kirigami
158 *
159 * Kirigami.ApplicationWindow {
160 * contextDrawer: Kirigami.ContextDrawer {
161 * enabled: true
162 * actions: [
163 * Kirigami.Action {
164 * icon.name: "edit"
165 * text: "Action text"
166 * onTriggered: {
167 * // do stuff
168 * }
169 * },
170 * Kirigami.Action {
171 * icon.name: "edit"
172 * text: "Action text"
173 * onTriggered: {
174 * // do stuff
175 * }
176 * }
177 * ]
178 * }
179 * }
180 * @endcode
181 *
182 * @property org::kde::kirigami::ContextDrawer contextDrawer
183 */
184 property OverlayDrawer contextDrawer
185
186 /**
187 * @brief This property holds the list of all children of this item.
188 * @internal
189 * @property list<Object> __data
190 */
191 default property alias __data: contentItemRoot.data
192
193 /**
194 * @brief This property holds the Item of the main part of the Application UI.
195 */
196 readonly property Item contentItem: Item {
197 id: contentItemRoot
198 parent: root
199 anchors {
200 fill: parent
201 topMargin: controlsVisible ? (root.header ? root.header.height : 0) + (root.menuBar ? root.menuBar.height : 0) : 0
202 bottomMargin: controlsVisible && root.footer ? root.footer.height : 0
203 leftMargin: root.globalDrawer && root.globalDrawer.modal === false ? root.globalDrawer.contentItem.width * root.globalDrawer.position : 0
204 rightMargin: root.contextDrawer && root.contextDrawer.modal === false ? root.contextDrawer.contentItem.width * root.contextDrawer.position : 0
205 }
207
208 /**
209 * @brief This property holds the color for the background.
210 *
211 * default: ``Kirigami.Theme.backgroundColor``
212 */
213 property color color: Kirigami.Theme.backgroundColor
214
215 /**
216 * @brief This property holds the background of the Application UI.
217 */
218 property Item background
219
220 property alias overlay: overlayRoot
221//END properties
222
223//BEGIN functions
224 /**
225 * @brief This function shows a little passive notification at the bottom of the app window
226 * lasting for few seconds, with an optional action button.
227 *
228 * @param message The text message to be shown to the user.
229 * @param timeout How long to show the message:
230 * possible values: "short", "long" or the number of milliseconds
231 * @param actionText Text in the action button, if any.
232 * @param callBack A JavaScript function that will be executed when the
233 * user clicks the button.
234 */
235 function showPassiveNotification(message, timeout, actionText, callBack) {
236 notificationsObject.showNotification(message, timeout, actionText, callBack);
237 }
238
239 /**
240 * @brief This function hides the passive notification at specified index, if any is shown.
241 * @param index Index of the notification to hide. Default is 0 (oldest notification).
242 */
243 function hidePassiveNotification(index = 0) {
244 notificationsObject.hideNotification(index);
245 }
246
247 /**
248 * @brief This property gets application windows object anywhere in the application.
249 * @returns a pointer to this item.
250 */
251 function applicationWindow() {
252 return root;
253 }
254//END functions
255
256//BEGIN signals handlers
257 onMenuBarChanged: {
258 if (menuBar) {
259 menuBar.parent = root.contentItem
260 if (menuBar instanceof T.ToolBar) {
261 menuBar.position = T.ToolBar.Footer
262 } else if (menuBar instanceof T.DialogButtonBox) {
263 menuBar.position = T.DialogButtonBox.Footer
264 }
265 menuBar.width = Qt.binding(() => root.contentItem.width)
266 // FIXME: (root.header.height ?? 0) when we can depend from 5.15
267 menuBar.y = Qt.binding(() => -menuBar.height - (root.header.height ? root.header.height : 0))
268 }
269 }
270
271 onHeaderChanged: {
272 if (header) {
273 header.parent = root.contentItem
274 if (header instanceof T.ToolBar) {
275 header.position = T.ToolBar.Header
276 } else if (header instanceof T.DialogButtonBox) {
277 header.position = T.DialogButtonBox.Header
278 }
279 header.width = Qt.binding(() => root.contentItem.width)
280 header.y = Qt.binding(() => -header.height)
281 }
282 }
283
284 onFooterChanged: {
285 if (footer) {
286 footer.parent = root.contentItem
287 if (footer instanceof T.ToolBar) {
288 footer.position = T.ToolBar.Footer
289 } else if (footer instanceof T.DialogButtonBox) {
290 footer.position = T.DialogButtonBox.Footer
291 }
292 footer.width = Qt.binding(() => root.contentItem.width)
293 footer.y = Qt.binding(() => root.contentItem.height)
294 }
295 }
296
297 onBackgroundChanged: {
298 if (background) {
299 background.parent = root.contentItem
300 background.anchors.fill = background.parent
301 }
302 }
303
304 onPageStackChanged: pageStack.parent = root.contentItem;
305//END signals handlers
306
307 LayoutMirroring.enabled: Qt.application.layoutDirection === Qt.RightToLeft
308 LayoutMirroring.childrenInherit: true
309
310 TP.PassiveNotificationsManager {
311 id: notificationsObject
312 anchors.bottom: parent.bottom
313 anchors.horizontalCenter: parent.horizontalCenter
314 z: 1
315 }
316
317 Item {
318 anchors.fill: parent
319 parent: root.parent || root
320 z: 999999
321
322 Item {
323 id: overlayRoot
324 z: -1
325 anchors.fill: parent
326 }
327 }
328
329 // Don't use root.overlay property here. For one, we know that in a window
330 // it will always be the same as T.Overlay.overlay; secondly Drawers
331 // don't care about being contained/parented to anything else anyway.
332 onGlobalDrawerChanged: {
333 if (globalDrawer) {
334 globalDrawer.parent = Qt.binding(() => visible ? T.Overlay.overlay : null);
335 }
336 }
337 onContextDrawerChanged: {
338 if (contextDrawer) {
339 contextDrawer.parent = Qt.binding(() => visible ? T.Overlay.overlay : null);
340 }
341 }
342
343 Window.onWindowChanged: {
344 if (globalDrawer) {
345 globalDrawer.visible = globalDrawer.drawerOpen;
346 }
347 if (contextDrawer) {
348 contextDrawer.visible = contextDrawer.drawerOpen;
349 }
350 }
351
352 implicitWidth: Kirigami.Settings.isMobile ? Kirigami.Units.gridUnit * 30 : Kirigami.Units.gridUnit * 55
353 implicitHeight: Kirigami.Settings.isMobile ? Kirigami.Units.gridUnit * 45 : Kirigami.Units.gridUnit * 40
354 visible: true
355}
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Dec 6 2024 12:09:31 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.