Warning, /frameworks/kirigami/src/controls/AbstractApplicationWindow.qml is written in an unsupported language. File is not indexed.

0001 /*
0002  *  SPDX-FileCopyrightText: 2015 Marco Martin <mart@kde.org>
0003  *
0004  *  SPDX-License-Identifier: LGPL-2.0-or-later
0005  */
0006 
0007 import QtQuick
0008 import QtQuick.Controls as QQC2
0009 import QtQuick.Templates as T
0010 import org.kde.kirigami as Kirigami
0011 import "templates/private" as TP
0012 
0013 /**
0014  * A window that provides some basic features needed for all apps
0015  * Use this class only if you need a custom content for your application,
0016  * different from the Page Row behavior recommended by the HIG and provided
0017  * by ApplicationWindow.
0018  * It is recommended to use ApplicationWindow instead
0019  * @see ApplicationWindow
0020  *
0021  * It's usually used as a root QML component for the application.
0022  * It provides support for a central page stack, side drawers, and
0023  * basic support for the Android back button.
0024  *
0025  * Setting a width and height property on the ApplicationWindow
0026  * will set its initial size, but it won't set it as an automatically binding.
0027  * to resize programmatically the ApplicationWindow they need to
0028  * be assigned again in an imperative fashion
0029  *
0030  *
0031  * Example usage:
0032  * @code
0033  * import org.kde.kirigami 2.4 as Kirigami
0034  *
0035  * Kirigami.ApplicationWindow {
0036  *  [...]
0037  *     globalDrawer: Kirigami.GlobalDrawer {
0038  *         actions: [
0039  *            Kirigami.Action {
0040  *                text: "View"
0041  *                icon.name: "view-list-icons"
0042  *                Kirigami.Action {
0043  *                        text: "action 1"
0044  *                }
0045  *                Kirigami.Action {
0046  *                        text: "action 2"
0047  *                }
0048  *                Kirigami.Action {
0049  *                        text: "action 3"
0050  *                }
0051  *            },
0052  *            Kirigami.Action {
0053  *                text: "Sync"
0054  *                icon.name: "folder-sync"
0055  *            }
0056  *         ]
0057  *     }
0058  *
0059  *     contextDrawer: Kirigami.ContextDrawer {
0060  *         id: contextDrawer
0061  *     }
0062  *
0063  *     pageStack: PageStack {
0064  *         ...
0065  *     }
0066  *  [...]
0067  * }
0068  * @endcode
0069  *
0070  * @inherit QtQuick.Controls.ApplicationWindow
0071  */
0072 QQC2.ApplicationWindow {
0073     id: root
0074 
0075 //BEGIN properties
0076     /**
0077      * @brief This property holds the stack used to allocate the pages and to manage the
0078      * transitions between them.
0079      *
0080      * Put a container here, such as QtQuick.Controls.StackView.
0081      */
0082     property Item pageStack
0083 
0084     /**
0085      * @brief This property sets whether the standard chrome of the app is visible.
0086      *
0087      * These are the action button, the drawer handles, and the application header.
0088      *
0089      * default: ``true``
0090      */
0091     property bool controlsVisible: true
0092 
0093     /**
0094      * @brief This property holds the drawer for global actions.
0095      *
0096      * This drawer can be opened by sliding from the left screen edge
0097      * or by dragging the ActionButton to the right.
0098      *
0099      * @note It is recommended to use the GlobalDrawer here.
0100      * @property org::kde::kirigami::OverlayDrawer globalDrawer
0101      */
0102     property OverlayDrawer globalDrawer
0103 
0104     /**
0105      * @brief This property tells whether the application is in "widescreen" mode.
0106      *
0107      * This is enabled on desktops or horizontal tablets.
0108      *
0109      * @note Different styles can have their own logic for deciding this.
0110      */
0111     property bool wideScreen: width >= Kirigami.Units.gridUnit * 60
0112 
0113     /**
0114      * @brief This property holds the drawer for context-dependent actions.
0115      *
0116      * The drawer that will be opened by sliding from the right screen edge
0117      * or by dragging the ActionButton to the left.
0118      *
0119      * @note It is recommended to use the ContextDrawer type here.
0120      *
0121      * The contents of the context drawer should depend from what page is
0122      * loaded in the main pageStack
0123      *
0124      * Example usage:
0125      *
0126      * @code
0127      * import org.kde.kirigami as Kirigami
0128      *
0129      * Kirigami.ApplicationWindow {
0130      *     contextDrawer: Kirigami.ContextDrawer {
0131      *         enabled: true
0132      *         actions: [
0133      *             Kirigami.Action {
0134      *                 icon.name: "edit"
0135      *                 text: "Action text"
0136      *                 onTriggered: {
0137      *                     // do stuff
0138      *                 }
0139      *             },
0140      *             Kirigami.Action {
0141      *                 icon.name: "edit"
0142      *                 text: "Action text"
0143      *                 onTriggered: {
0144      *                     // do stuff
0145      *                 }
0146      *             }
0147      *         ]
0148      *     }
0149      * }
0150      * @endcode
0151      *
0152      * @property org::kde::kirigami::ContextDrawer contextDrawer
0153      */
0154     property OverlayDrawer contextDrawer
0155 
0156     /**
0157      * Effectively the same as T.Overlay.overlay
0158      */
0159     readonly property Item overlay: T.Overlay.overlay
0160 
0161     /**
0162      * This property holds a standard action that will quit the application when triggered.
0163      * Its properties have the following values:
0164      *
0165      * @code
0166      * Action {
0167      *     text: "Quit"
0168      *     icon.name: "application-exit-symbolic"
0169      *     shortcut: StandardKey.Quit
0170      *     // ...
0171      * }
0172      * @endcode
0173      * @since 5.76
0174      */
0175     readonly property Kirigami.Action quitAction: Kirigami.Action {
0176         text: qsTr("Quit")
0177         icon.name: "application-exit";
0178         shortcut: StandardKey.Quit
0179         onTriggered: source => root.close();
0180     }
0181 //END properties
0182 
0183 //BEGIN functions
0184     /**
0185      * @brief This function shows a little passive notification at the bottom of the app window
0186      * lasting for few seconds, with an optional action button.
0187      *
0188      * @param message The text message to be shown to the user.
0189      * @param timeout How long to show the message:
0190      *            possible values: "short", "long" or the number of milliseconds
0191      * @param actionText Text in the action button, if any.
0192      * @param callBack A JavaScript function that will be executed when the
0193      *            user clicks the button.
0194      */
0195     function showPassiveNotification(message, timeout, actionText, callBack) {
0196         notificationsObject.showNotification(message, timeout, actionText, callBack);
0197     }
0198 
0199    /**
0200     * @brief This function hides the passive notification at specified index, if any is shown.
0201     * @param index Index of the notification to hide. Default is 0 (oldest notification).
0202     */
0203     function hidePassiveNotification(index = 0) {
0204         notificationsObject.hideNotification(index);
0205     }
0206 
0207     /**
0208      * @brief This function returns application window's object anywhere in the application.
0209      * @returns a pointer to this application window
0210      * can be used anywhere in the application.
0211      */
0212     function applicationWindow() {
0213         return root;
0214     }
0215 //END functions
0216 
0217     LayoutMirroring.enabled: Qt.application.layoutDirection === Qt.RightToLeft
0218     LayoutMirroring.childrenInherit: true
0219 
0220     color: Kirigami.Theme.backgroundColor
0221 
0222     TP.PassiveNotificationsManager {
0223         id: notificationsObject
0224         anchors.bottom: parent.bottom
0225         anchors.horizontalCenter: parent.horizontalCenter
0226         z: 1
0227     }
0228 
0229     contentItem.z: 1
0230     contentItem.anchors.left: contentItem.parent.left
0231     contentItem.anchors.right: contentItem.parent.right
0232     contentItem.anchors.topMargin: root.wideScreen && header && controlsVisible ? header.height : 0
0233     contentItem.anchors.leftMargin: root.globalDrawer && root.globalDrawer.modal === false && (!root.pageStack || root.pageStack.leftSidebar !== root.globalDrawer) ? root.globalDrawer.width * root.globalDrawer.position : 0
0234     contentItem.anchors.rightMargin: root.contextDrawer && root.contextDrawer.modal === false ? root.contextDrawer.width * root.contextDrawer.position : 0
0235 
0236     Binding {
0237         target: root.menuBar
0238         property: "x"
0239         value: -contentItem.x
0240     }
0241     Binding {
0242         target: root.header
0243         property: "x"
0244         value: -contentItem.x
0245     }
0246     Binding {
0247         target: root.footer
0248         property: "x"
0249         value: -contentItem.x
0250     }
0251 
0252     // Don't use root.overlay property here. For one, we know that in a window
0253     // it will always be the same as T.Overlay.overlay; secondly Drawers
0254     // don't care about being contained/parented to anything else anyway.
0255     onGlobalDrawerChanged: {
0256         if (globalDrawer) {
0257             globalDrawer.parent = Qt.binding(() => T.Overlay.overlay);
0258         }
0259     }
0260     onContextDrawerChanged: {
0261         if (contextDrawer) {
0262             contextDrawer.parent = Qt.binding(() => T.Overlay.overlay);
0263         }
0264     }
0265     onPageStackChanged: {
0266         if (pageStack) {
0267             // contentItem is declared as CONSTANT, so binding isn't needed.
0268             pageStack.parent = contentItem;
0269         }
0270     }
0271 
0272     width: Kirigami.Settings.isMobile ? Kirigami.Units.gridUnit * 30 : Kirigami.Units.gridUnit * 55
0273     height: Kirigami.Settings.isMobile ? Kirigami.Units.gridUnit * 45 : Kirigami.Units.gridUnit * 40
0274     visible: true
0275 
0276     Component.onCompleted: {
0277         // Explicitly break the binding as we need this to be set only at startup.
0278         // if the bindings are active, after this the window is resized by the
0279         // compositor and then the bindings are reevaluated, then the window
0280         // size would reset ignoring what the compositor asked.
0281         // see BUG 433849
0282         root.width = root.width;
0283         root.height = root.height;
0284     }
0285 
0286     // This is needed because discover in mobile mode does not
0287     // close with the global drawer open.
0288     Shortcut {
0289         sequence: root.quitAction.shortcut
0290         enabled: root.quitAction.enabled
0291         context: Qt.ApplicationShortcut
0292         onActivated: root.close();
0293     }
0294 }