Kirigami2

AbstractApplicationItem.qml
1 /*
2  * SPDX-FileCopyrightText: 2017 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.14
9 import QtQuick.Templates 2.12 as T
10 import QtQuick.Window 2.12
11 import org.kde.kirigami 2.14 as Kirigami
12 import "templates/private" as TP
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 2.4 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  */
61 Item {
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 exists for compatibility with Applicationwindow.
75  *
76  * default: ``Window.activeFocusItem``
77  */
78  readonly property Item activeFocusItem: Window.activeFocusItem
79 
80  /**
81  * @brief This property holds the font for this item.
82  *
83  * default: ``Kirigami.Theme.defaultFont``
84  */
85  property font font: Kirigami.Theme.defaultFont
86 
87  /**
88  * @brief This property holds the palette for this item.
89  *
90  * default: ``Kirigami.Theme.palette``
91  */
92  property var palette: Kirigami.Theme.palette
93 
94  /**
95  * @brief This property holds the locale for this item.
96  */
97  property Locale locale
98 
99  /**
100  * @brief This property holds an item that can be used as a menuBar for the application.
101  * @warning This will be restricted to QQC2.MenuBar in KF6.
102  */
103  property Item menuBar // TODO KF6 restrict type to QQC2.MenuBar
104 
105  /**
106  * @brief This property holds an item that can be used as a title for the application.
107  *
108  * Scrolling the main page will make it taller or shorter (through the point of going away).
109  *
110  * It's a behavior similar to the typical mobile web browser addressbar.
111  *
112  * The minimum, preferred and maximum heights of the item can be controlled with
113  *
114  * * ``Layout.minimumHeight``: default is 0, i.e. hidden
115  * * ``Layout.preferredHeight``: default is Kirigami.Units.gridUnit * 1.6
116  * * ``Layout.maximumHeight``: default is Kirigami.Units.gridUnit * 3
117  *
118  * To achieve a titlebar that stays completely fixed, just set the 3 sizes as the same.
119  *
120  * @warning This will be restricted to Kirigami.ApplicationHeader in KF6.
121  * @property org::kde:kirigami::ApplicationHeader header
122  */
123  property Item header // TODO KF6 restrict the type to Kirigami.ApplicationHeader
124 
125  /**
126  * @brief This property holds an item that can be used as a footer for the application.
127  */
128  property Item footer
129 
130  /**
131  * @brief This property sets whether the standard chrome of the app is visible.
132  *
133  * These are the action button, the drawer handles and the application header.
134  *
135  * default: ``true``
136  */
137  property bool controlsVisible: true
138 
139  /**
140  * @brief This property holds the drawer for global actions.
141  *
142  * Thos drawer can be opened by sliding from the left screen edge
143  * or by dragging the ActionButton to the right.
144  *
145  * @note It is recommended to use the GlobalDrawer here.
146  * @property org::kde::kirigami::OverlayDrawer globalDrawer
147  */
148  property OverlayDrawer globalDrawer
149 
150  /**
151  * @brief This property tells us whether the application is in "widescreen" mode.
152  *
153  * This is enabled on desktops or horizontal tablets.
154  *
155  * @note Different styles can have their own logic for deciding this.
156  */
157  property bool wideScreen: width >= Kirigami.Units.gridUnit * 60
158 
159  /**
160  * @brief This property holds the drawer for context-dependent actions.
161  *
162  * The drawer that will be opened by sliding from the right screen edge
163  * or by dragging the ActionButton to the left.
164  *
165  * @note It is recommended to use the ContextDrawer class here.
166  *
167  * The contents of the context drawer should depend from what page is
168  * loaded in the main pageStack
169  *
170  * Example usage:
171  * @code
172  * import org.kde.kirigami 2.4 as Kirigami
173  *
174  * Kirigami.ApplicationItem {
175  * [...]
176  * contextDrawer: Kirigami.ContextDrawer {
177  * id: contextDrawer
178  * }
179  * [...]
180  * }
181  * @endcode
182  *
183  * @code
184  * import org.kde.kirigami 2.4 as Kirigami
185  *
186  * Kirigami.Page {
187  * [...]
188  * contextualActions: [
189  * Kirigami.Action {
190  * icon.name: "edit"
191  * text: "Action text"
192  * onTriggered: {
193  * // do stuff
194  * }
195  * },
196  * Kirigami.Action {
197  * icon.name: "edit"
198  * text: "Action text"
199  * onTriggered: {
200  * // do stuff
201  * }
202  * }
203  * ]
204  * [...]
205  * }
206  * @endcode
207  *
208  * When this page will be the current one, the context drawer will visualize
209  * contextualActions defined as property in that page.
210  *
211  * @property org::kde::kirigami::ContextDrawer contextDrawer
212  */
213  property OverlayDrawer contextDrawer
214 
215  /**
216  * @brief This tells us whether the application is in reachable mode for single hand use.
217  *
218  * The whole content of the application is moved down the screen to be
219  * reachable with the thumb. If wideScreen is true, or reachableModeEnabled is false,
220  * this property has no effect.
221  *
222  * default: ``false``
223  */
224  property bool reachableMode: false
225 
226  /**
227  * @brief This property sets whether the application will go into reachable mode on pull down.
228  *
229  * default: ``true``
230  */
231  property bool reachableModeEnabled: true
232 
233  /**
234  * @brief This property holds the list of all children of this item.
235  * @internal
236  * @property list<Object> __data
237  */
238  default property alias __data: contentItemRoot.data
239 
240  /**
241  * @brief This property holds the Item of the main part of the Application UI.
242  */
243  readonly property Item contentItem: Item {
244  id: contentItemRoot
245  parent: root
246  anchors {
247  fill: parent
248  topMargin: controlsVisible ? (root.header ? root.header.height : 0) + (root.menuBar ? root.menuBar.height : 0) : 0
249  bottomMargin: controlsVisible && root.footer ? root.footer.height : 0
250  leftMargin: root.globalDrawer && root.globalDrawer.modal === false ? root.globalDrawer.contentItem.width * root.globalDrawer.position : 0
251  rightMargin: root.contextDrawer && root.contextDrawer.modal === false ? root.contextDrawer.contentItem.width * root.contextDrawer.position : 0
252  }
253 
254  transform: Translate {
255  Behavior on y {
256  NumberAnimation {
257  duration: Kirigami.Units.longDuration
258  easing.type: Easing.InOutQuad
259  }
260  }
261  y: root.reachableMode && root.reachableModeEnabled && !root.wideScreen ? root.height/2 : 0
262  x: root.globalDrawer && root.globalDrawer.modal === true && root.globalDrawer.toString().indexOf("SplitDrawer") === 0 ? root.globalDrawer.contentItem.width * root.globalDrawer.position : 0
263  }
264  }
265 
266  /**
267  * @brief This property holds the color for the background.
268  *
269  * default: ``Kirigami.Theme.backgroundColor``
270  */
271  property color color: Kirigami.Theme.backgroundColor
272 
273  /**
274  * @brief This property holds the background of the Application UI.
275  */
276  property Item background
277 
278  property alias overlay: overlayRoot
279 //END properties
280 
281 //BEGIN functions
282  /**
283  * @brief This function shows a little passive notification at the bottom of the app window
284  * lasting for few seconds, with an optional action button.
285  *
286  * @param message The text message to be shown to the user.
287  * @param timeout How long to show the message:
288  * possible values: "short", "long" or the number of milliseconds
289  * @param actionText Text in the action button, if any.
290  * @param callBack A JavaScript function that will be executed when the
291  * user clicks the button.
292  */
293  function showPassiveNotification(message, timeout, actionText, callBack) {
294  notificationsObject.showNotification(message, timeout, actionText, callBack);
295  }
296 
297  /**
298  * @brief This function hides the passive notification at specified index, if any is shown.
299  * @param index Index of the notification to hide. Default is 0 (oldest notification).
300  */
301  function hidePassiveNotification(index = 0) {
302  notificationsObject.hideNotification(index);
303  }
304 
305  /**
306  * @brief This property gets application windows object anywhere in the application.
307  * @returns a pointer to this item.
308  */
309  function applicationWindow() {
310  return root;
311  }
312 //END functions
313 
314 //BEGIN signals handlers
315  onMenuBarChanged: {
316  menuBar.parent = root.contentItem
317  if (menuBar.z === undefined) {
318  menuBar.z = 1;
319  }
320  if (menuBar instanceof T.ToolBar) {
321  menuBar.position = T.ToolBar.Footer
322  } else if (menuBar instanceof T.TabBar) {
323  menuBar.position = T.TabBar.Footer
324  } else if (menuBar instanceof T.DialogButtonBox) {
325  menuBar.position = T.DialogButtonBox.Footer
326  }
327  menuBar.width = Qt.binding(() => root.contentItem.width)
328  // FIXME: (root.header.height ?? 0) when we can depend from 5.15
329  menuBar.y = Qt.binding(() => -menuBar.height - (root.header.height ? root.header.height : 0))
330  }
331 
332  onHeaderChanged: {
333  header.parent = root.contentItem
334  if (header.z === undefined) {
335  header.z = 1;
336  }
337  if (header instanceof T.ToolBar) {
338  header.position = T.ToolBar.Header
339  } else if (header instanceof T.TabBar) {
340  header.position = T.TabBar.Header
341  } else if (header instanceof T.DialogButtonBox) {
342  header.position = T.DialogButtonBox.Header
343  }
344  header.width = Qt.binding(() => root.contentItem.width)
345  header.y = Qt.binding(() => -header.height)
346  }
347 
348  onFooterChanged: {
349  footer.parent = root.contentItem
350  if (footer.z === undefined) {
351  footer.z = 1;
352  }
353  if (footer instanceof T.ToolBar) {
354  footer.position = T.ToolBar.Footer
355  } else if (footer instanceof T.TabBar) {
356  footer.position = T.TabBar.Footer
357  } else if (footer instanceof T.DialogButtonBox) {
358  footer.position = T.DialogButtonBox.Footer
359  }
360  footer.width = Qt.binding(() => root.contentItem.width)
361  footer.y = Qt.binding(() => root.contentItem.height)
362  }
363 
364  onBackgroundChanged: {
365  background.parent = root.contentItem
366  if (background.z === undefined) {
367  background.z = -1;
368  }
369  background.anchors.fill = background.parent
370  }
371 
372  // NOTE: Don't want overscroll in landscape mode
373  onWidthChanged: {
374  if (width > height) {
375  root.reachableMode = false;
376  }
377  }
378 
379  onPageStackChanged: pageStack.parent = root.contentItem;
380 //END signals handlers
381 
382  LayoutMirroring.enabled: Qt.application.layoutDirection === Qt.RightToLeft
383  LayoutMirroring.childrenInherit: true
384 
385  TP.PassiveNotificationsManager {
386  id: notificationsObject
387  anchors.bottom: parent.bottom
388  anchors.horizontalCenter: parent.horizontalCenter
389  z: 1
390  }
391 
392  Item {
393  anchors.fill: parent
394  parent: root.parent || root
395  z: 999999
396  Rectangle {
397  z: -1
398  anchors.fill: parent
399  color: "black"
400  visible: contextDrawer && contextDrawer.modal
401  parent: contextDrawer ? contextDrawer.background.parent.parent : overlayRoot
402  opacity: contextDrawer ? contextDrawer.position * 0.6 : 0
403  }
404  Rectangle {
405  z: -1
406  anchors.fill: parent
407  color: "black"
408  visible: globalDrawer && globalDrawer.modal
409  parent: globalDrawer ? globalDrawer.background.parent.parent : overlayRoot
410  opacity: globalDrawer ? globalDrawer.position * 0.6 : 0
411  }
412  Item {
413  id: overlayRoot
414  z: -1
415  anchors.fill: parent
416  }
417  Window.onWindowChanged: {
418  if (globalDrawer) {
419  globalDrawer.visible = globalDrawer.drawerOpen;
420  }
421  if (contextDrawer) {
422  contextDrawer.visible = contextDrawer.drawerOpen;
423  }
424  }
425  }
426 
427  MouseArea {
428  parent: root
429  z: -1
430  anchors.fill: parent
431  onClicked: mouse => {
432  root.reachableMode = false;
433  }
434  visible: root.reachableMode && root.reachableModeEnabled
435  Rectangle {
436  anchors.fill: parent
437  color: Qt.rgba(0, 0, 0, 0.3)
438  opacity: 0.15
439  Kirigami.Icon {
440  anchors.horizontalCenter: parent.horizontalCenter
441  y: x
442  width: Kirigami.Units.iconSizes.large
443  height: width
444  source: "go-up"
445  }
446  }
447  }
448 
449  Binding {
450  when: globalDrawer !== undefined && root.visible
451  target: globalDrawer
452  property: "parent"
453  value: overlay
454  restoreMode: Binding.RestoreBinding
455  }
456  Binding {
457  when: contextDrawer !== undefined && root.visible
458  target: contextDrawer
459  property: "parent"
460  value: overlay
461  restoreMode: Binding.RestoreBinding
462  }
463 
464  implicitWidth: Kirigami.Units.gridUnit * 30
465  implicitHeight: Kirigami.Units.gridUnit * 45
466  visible: true
467 }
int indexOf(QChar ch, int from, Qt::CaseSensitivity cs) const const
Overlay Drawers are used to expose additional UI elements needed for small secondary tasks for which ...
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.