Kirigami2

AbstractApplicationWindow.qml
1 /*
2  * SPDX-FileCopyrightText: 2015 Marco Martin <[email protected]>
3  *
4  * SPDX-License-Identifier: LGPL-2.0-or-later
5  */
6 
7 import QtQuick 2.12
8 import QtQml 2.15
9 import QtQuick.Controls 2.0 as QQC2
10 import QtQuick.Window 2.5
11 import org.kde.kirigami 2.4 as Kirigami
12 import "templates/private" as TP
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  * a top ApplicationHeader, as well as basic support for the
24  * Android back button
25  *
26  * Setting a width and height property on the ApplicationWindow
27  * will set its initial size, but it won't set it as an automatically binding.
28  * to resize programmatically the ApplicationWindow they need to
29  * be assigned again in an imperative fashion
30  *
31  *
32  * Example usage:
33  * @code
34  * import org.kde.kirigami 2.4 as Kirigami
35  *
36  * Kirigami.ApplicationWindow {
37  * [...]
38  * globalDrawer: Kirigami.GlobalDrawer {
39  * actions: [
40  * Kirigami.Action {
41  * text: "View"
42  * icon.name: "view-list-icons"
43  * Kirigami.Action {
44  * text: "action 1"
45  * }
46  * Kirigami.Action {
47  * text: "action 2"
48  * }
49  * Kirigami.Action {
50  * text: "action 3"
51  * }
52  * },
53  * Kirigami.Action {
54  * text: "Sync"
55  * icon.name: "folder-sync"
56  * }
57  * ]
58  * }
59  *
60  * contextDrawer: Kirigami.ContextDrawer {
61  * id: contextDrawer
62  * }
63  *
64  * pageStack: PageStack {
65  * ...
66  * }
67  * [...]
68  * }
69  * @endcode
70  *
71  * @inherit QtQuick.Controls.ApplicationWindow
72  */
73 QQC2.ApplicationWindow {
74  id: root
75 
76 //BEGIN properties
77  /**
78  * @brief This property holds the stack used to allocate the pages and to manage the
79  * transitions between them.
80  *
81  * Put a container here, such as QtQuick.Controls.StackView.
82  */
83  property Item pageStack
84 
85  /**
86  * @brief This property sets whether the standard chrome of the app is visible.
87  *
88  * These are the action button, the drawer handles, and the application header.
89  *
90  * default: ``true``
91  */
92  property bool controlsVisible: true
93 
94  /**
95  * @brief This property holds the drawer for global actions.
96  *
97  * This drawer can be opened by sliding from the left screen edge
98  * or by dragging the ActionButton to the right.
99  *
100  * @note It is recommended to use the GlobalDrawer here.
101  * @property org::kde::kirigami::OverlayDrawer globalDrawer
102  */
103  property OverlayDrawer globalDrawer
104 
105  /**
106  * @brief This property tells whether the application is in "widescreen" mode.
107  *
108  * This is enabled on desktops or horizontal tablets.
109  *
110  * @note Different styles can have their own logic for deciding this.
111  */
112  property bool wideScreen: width >= Kirigami.Units.gridUnit * 60
113 
114  /**
115  * @brief This property holds the drawer for context-dependent actions.
116  *
117  * The drawer that will be opened by sliding from the right screen edge
118  * or by dragging the ActionButton to the left.
119  *
120  * @note It is recommended to use the ContextDrawer class here.
121  *
122  * The contents of the context drawer should depend from what page is
123  * loaded in the main pageStack
124  *
125  * Example usage:
126  * @code
127  * import org.kde.kirigami 2.4 as Kirigami
128  *
129  * Kirigami.ApplicationWindow {
130  * [...]
131  * contextDrawer: Kirigami.ContextDrawer {
132  * id: contextDrawer
133  * }
134  * [...]
135  * }
136  * @endcode
137  *
138  * @code
139  * import org.kde.kirigami 2.4 as Kirigami
140  *
141  * Kirigami.Page {
142  * [...]
143  * contextualActions: [
144  * Kirigami.Action {
145  * icon.name: "edit"
146  * text: "Action text"
147  * onTriggered: {
148  * // do stuff
149  * }
150  * },
151  * Kirigami.Action {
152  * icon.name: "edit"
153  * text: "Action text"
154  * onTriggered: {
155  * // do stuff
156  * }
157  * }
158  * ]
159  * [...]
160  * }
161  * @endcode
162  *
163  * When this page will be the current one, the context drawer will visualize
164  * contextualActions defined as property in that page.
165  * @property org::kde::kirigami::ContextDrawer contextDrawer
166  */
167  property OverlayDrawer contextDrawer
168 
169  /**
170  * @brief This property tells whether the application is in reachable mode for single hand use.
171  *
172  * The whole content of the application is moved down the screen to be
173  * reachable with the thumb. If wideScreen is true, or reachableModeEnabled is false,
174  * this property has no effect.
175  *
176  * default: ``false``
177  */
178  property bool reachableMode: false
179 
180  /**
181  * @brief This property sets whether the application will go into reachable mode on pull down.
182  */
183  property bool reachableModeEnabled: true
184 
185  /**
186  * This property holds a standard action that will quit the application when triggered.
187  * Its properties have the following values:
188  *
189  * @code
190  * Action {
191  * text: "Quit"
192  * icon.name: "application-exit-symbolic";
193  * shortcut: StandardKey.Quit
194  * [...]
195  * @endcode
196  * @since 5.76
197  */
198  readonly property Action quitAction: _quitAction
199 //END properties
200 
201 //BEGIN functions
202  /**
203  * @brief This function shows a little passive notification at the bottom of the app window
204  * lasting for few seconds, with an optional action button.
205  *
206  * @param message The text message to be shown to the user.
207  * @param timeout How long to show the message:
208  * possible values: "short", "long" or the number of milliseconds
209  * @param actionText Text in the action button, if any.
210  * @param callBack A JavaScript function that will be executed when the
211  * user clicks the button.
212  */
213  function showPassiveNotification(message, timeout, actionText, callBack) {
214  notificationsObject.showNotification(message, timeout, actionText, callBack);
215  }
216 
217  /**
218  * @brief This function hides the passive notification at specified index, if any is shown.
219  * @param index Index of the notification to hide. Default is 0 (oldest notification).
220  */
221  function hidePassiveNotification(index = 0) {
222  notificationsObject.hideNotification(index);
223  }
224 
225  /**
226  * @brief This function returns application window's object anywhere in the application.
227  * @returns a pointer to this application window
228  * can be used anywhere in the application.
229  */
230  function applicationWindow() {
231  return root;
232  }
233 //END functions
234 
235  LayoutMirroring.enabled: Qt.application.layoutDirection === Qt.RightToLeft
236  LayoutMirroring.childrenInherit: true
237 
238  color: Kirigami.Theme.backgroundColor
239 
240  TP.PassiveNotificationsManager {
241  id: notificationsObject
242  anchors.bottom: parent.bottom
243  anchors.horizontalCenter: parent.horizontalCenter
244  z: 1
245  }
246 
247  MouseArea {
248  parent: contentItem.parent
249  z: 0
250  anchors.fill: parent
251  onClicked: mouse => {
252  root.reachableMode = false;
253  }
254  visible: root.reachableMode && root.reachableModeEnabled
255  Rectangle {
256  anchors.fill: parent
257  color: Qt.rgba(0, 0, 0, 0.3)
258  opacity: 0.15
259  Kirigami.Icon {
260  anchors.horizontalCenter: parent.horizontalCenter
261  y: x
262  width: Kirigami.Units.iconSizes.large
263  height: width
264  source: "go-up"
265  }
266  }
267  }
268 
269  contentItem.z: 1
270  contentItem.anchors.left: contentItem.parent.left
271  contentItem.anchors.right: contentItem.parent.right
272  contentItem.anchors.topMargin: root.wideScreen && header && controlsVisible ? header.height : 0
273  contentItem.anchors.leftMargin: root.globalDrawer && root.globalDrawer.modal === false && (!root.pageStack || root.pageStack.leftSidebar !== root.globalDrawer) ? root.globalDrawer.width * root.globalDrawer.position : 0
274  contentItem.anchors.rightMargin: root.contextDrawer && root.contextDrawer.modal === false ? root.contextDrawer.width * root.contextDrawer.position : 0
275 
276  Binding {
277  when: menuBar !== undefined
278  target: menuBar
279  property: "x"
280  value: -contentItem.x
281  restoreMode: Binding.RestoreBinding
282  }
283  Binding {
284  when: header !== undefined
285  target: header
286  property: "x"
287  value: -contentItem.x
288  restoreMode: Binding.RestoreBinding
289  }
290  Binding {
291  when: footer !== undefined
292  target: footer
293  property: "x"
294  value: -contentItem.x
295  restoreMode: Binding.RestoreBinding
296  }
297 
298  contentItem.transform: Translate {
299  Behavior on y {
300  NumberAnimation {
301  duration: Kirigami.Units.longDuration
302  easing.type: Easing.InOutQuad
303  }
304  }
305  y: root.reachableMode && root.reachableModeEnabled && !root.wideScreen ? root.height/2 : 0
306  x: root.globalDrawer && root.globalDrawer.modal === true && root.globalDrawer.toString().indexOf("SplitDrawer") === 0 ? root.globalDrawer.contentItem.width * root.globalDrawer.position : 0
307  }
308  //Don't want overscroll in landscape mode
309  onWidthChanged: {
310  if (width > height) {
311  root.reachableMode = false;
312  }
313  }
314  Binding {
315  when: globalDrawer !== undefined && root.visible
316  target: globalDrawer
317  property: "parent"
318  value: overlay
319  restoreMode: Binding.RestoreBinding
320  }
321  Binding {
322  when: contextDrawer !== undefined && root.visible
323  target: contextDrawer
324  property: "parent"
325  value: overlay
326  restoreMode: Binding.RestoreBinding
327  }
328  onPageStackChanged: pageStack.parent = contentItem;
329 
330  width: Kirigami.Settings.isMobile ? Kirigami.Units.gridUnit * 30 : Kirigami.Units.gridUnit * 55
331  height: Kirigami.Settings.isMobile ? Kirigami.Units.gridUnit * 45 : Kirigami.Units.gridUnit * 40
332  visible: true
333 
334  Component.onCompleted: {
335  // Explicitly break the binding as we need this to be set only at startup.
336  // if the bindings are active, after this the window is resized by the
337  // compositor and then the bindings are reevaluated, then the window
338  // size would reset ignoring what the compositor asked.
339  // see BUG 433849
340  root.width = root.width;
341  root.height = root.height;
342  }
343 
344  Action {
345  id: _quitAction
346  text: qsTr("Quit")
347  icon.name: "application-exit";
348  shortcut: StandardKey.Quit
349  onTriggered: source => root.close()
350  }
351  Shortcut {
352  sequence: _quitAction.shortcut
353  context: Qt.ApplicationShortcut
354  onActivated: root.close()
355  }
356 }
Overlay Drawers are used to expose additional UI elements needed for small secondary tasks for which ...
An item that represents an abstract Action.
Definition: Action.qml:14
QString message
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Sun Jan 29 2023 04:11:03 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.