src/controls/AbstractApplicationItem.qml

0001 /*
0002  *  SPDX-FileCopyrightText: 2017 Marco Martin <mart@kde.org>
0003  *
0004  *  SPDX-License-Identifier: LGPL-2.0-or-later
0005  */
0006
0007 import QtQuick
0008 import QtQuick.Templates as T
0009
0010 import org.kde.kirigami as Kirigami
0011 import "templates/private" as TP
0012 import "templates" as KT
0013
0014 /**
0015  * @brief An item that provides the features of AbstractApplicationWindow without the window itself.
0016  *
0017  * This allows embedding into a larger application.
0018  * Unless you need extra flexibility it is recommended to use ApplicationItem instead.
0019  *
0020  * Example usage:
0021  * @code
0022  * import org.kde.kirigami 2.4 as Kirigami
0023  *
0024  * Kirigami.AbstractApplicationItem {
0025  *  [...]
0026  *     globalDrawer: Kirigami.GlobalDrawer {
0027  *         actions: [
0028  *            Kirigami.Action {
0029  *                text: "View"
0030  *                icon.name: "view-list-icons"
0031  *                Kirigami.Action {
0032  *                        text: "action 1"
0033  *                }
0034  *                Kirigami.Action {
0035  *                        text: "action 2"
0036  *                }
0037  *                Kirigami.Action {
0038  *                        text: "action 3"
0039  *                }
0040  *            },
0041  *            Kirigami.Action {
0042  *                text: "Sync"
0043  *                icon.name: "folder-sync"
0044  *            }
0045  *         ]
0046  *     }
0047  *
0048  *     contextDrawer: Kirigami.ContextDrawer {
0049  *         id: contextDrawer
0050  *     }
0051  *
0052  *     pageStack: Kirigami.PageRow {
0053  *         ...
0054  *     }
0055  *  [...]
0056  * }
0057  * @endcode
0058  *
0059  * @inherit QtQuick.Item
0060  */
0061 Item {
0062     id: root
0063
0064 //BEGIN properties
0065     /**
0066      * @brief This property holds the stack used to allocate the pages and to manage the
0067      * transitions between them.
0068      *
0069      * Put a container here, such as QtQuick.Controls.StackView.
0070      */
0071     property Item pageStack
0072
0073     /**
0074      * @brief This property holds the font for this item.
0075      *
0076      * default: ``Kirigami.Theme.defaultFont``
0077      */
0078     property font font: Kirigami.Theme.defaultFont
0079
0080     /**
0081      * @brief This property holds the locale for this item.
0082      */
0083     property Locale locale
0084
0085     /**
0086      * @brief This property holds an item that can be used as a menuBar for the application.
0087      */
0088     property T.MenuBar menuBar
0089
0090     /**
0091     * @brief This property holds an item that can be used as a title for the application.
0092     *
0093     * Scrolling the main page will make it taller or shorter (through the point of going away).
0094     *
0095     * It's a behavior similar to the typical mobile web browser addressbar.
0096     *
0097     * The minimum, preferred and maximum heights of the item can be controlled with
0098     *
0099     * * ``Layout.minimumHeight``: default is 0, i.e. hidden
0100     * * ``Layout.preferredHeight``: default is Kirigami.Units.gridUnit * 1.6
0101     * * ``Layout.maximumHeight``: default is Kirigami.Units.gridUnit * 3
0102     *
0103     * To achieve a titlebar that stays completely fixed, just set the 3 sizes as the same.
0104     *
0105     * @property kirigami::templates::AbstractApplicationHeader header
0106     */
0107     property KT.AbstractApplicationHeader header
0108
0109     /**
0110      * @brief This property holds an item that can be used as a footer for the application.
0111      */
0112     property Item footer
0113
0114     /**
0115      * @brief This property sets whether the standard chrome of the app is visible.
0116      *
0117      * These are the action button, the drawer handles and the application header.
0118      *
0119      * default: ``true``
0120      */
0121     property bool controlsVisible: true
0122
0123     /**
0124      * @brief This property holds the drawer for global actions.
0125      *
0126      * Thos drawer can be opened by sliding from the left screen edge
0127      * or by dragging the ActionButton to the right.
0128      *
0129      * @note It is recommended to use the GlobalDrawer here.
0130      * @property org::kde::kirigami::OverlayDrawer globalDrawer
0131      */
0132     property OverlayDrawer globalDrawer
0133
0134     /**
0135      * @brief This property tells us whether the application is in "widescreen" mode.
0136      *
0137      * This is enabled on desktops or horizontal tablets.
0138      *
0139      * @note Different styles can have their own logic for deciding this.
0140      */
0141     property bool wideScreen: width >= Kirigami.Units.gridUnit * 60
0142
0143     /**
0144      * @brief This property holds the drawer for context-dependent actions.
0145      *
0146      * The drawer that will be opened by sliding from the right screen edge
0147      * or by dragging the ActionButton to the left.
0148      *
0149      * @note It is recommended to use the ContextDrawer type here.
0150      *
0151      * The contents of the context drawer should depend from what page is
0152      * loaded in the main pageStack
0153      *
0154      * Example usage:
0155      *
0156      * @code
0157      * import org.kde.kirigami as Kirigami
0158      *
0159      * Kirigami.ApplicationWindow {
0160      *     contextDrawer: Kirigami.ContextDrawer {
0161      *         enabled: true
0162      *         actions: [
0163      *             Kirigami.Action {
0164      *                 icon.name: "edit"
0165      *                 text: "Action text"
0166      *                 onTriggered: {
0167      *                     // do stuff
0168      *                 }
0169      *             },
0170      *             Kirigami.Action {
0171      *                 icon.name: "edit"
0172      *                 text: "Action text"
0173      *                 onTriggered: {
0174      *                     // do stuff
0175      *                 }
0176      *             }
0177      *         ]
0178      *     }
0179      * }
0180      * @endcode
0181      *
0182      * @property org::kde::kirigami::ContextDrawer contextDrawer
0183      */
0184     property OverlayDrawer contextDrawer
0185
0186     /**
0187      * @brief This property holds the list of all children of this item.
0188      * @internal
0189      * @property list<Object> __data
0190      */
0191     default property alias __data: contentItemRoot.data
0192
0193     /**
0194      * @brief This property holds the Item of the main part of the Application UI.
0195      */
0196     readonly property Item contentItem: Item {
0197         id: contentItemRoot
0198         parent: root
0199         anchors {
0200             fill: parent
0201             topMargin: controlsVisible ? (root.header ? root.header.height : 0) + (root.menuBar ? root.menuBar.height : 0) : 0
0202             bottomMargin: controlsVisible && root.footer ? root.footer.height : 0
0203             leftMargin: root.globalDrawer && root.globalDrawer.modal === false ? root.globalDrawer.contentItem.width * root.globalDrawer.position : 0
0204             rightMargin: root.contextDrawer && root.contextDrawer.modal === false ? root.contextDrawer.contentItem.width * root.contextDrawer.position : 0
0205         }
0206     }
0207
0208     /**
0209      * @brief This property holds the color for the background.
0210      *
0211      * default: ``Kirigami.Theme.backgroundColor``
0212      */
0213     property color color: Kirigami.Theme.backgroundColor
0214
0215     /**
0216      * @brief This property holds the background of the Application UI.
0217      */
0218     property Item background
0219
0220     property alias overlay: overlayRoot
0221 //END properties
0222
0223 //BEGIN functions
0224     /**
0225      * @brief This function shows a little passive notification at the bottom of the app window
0226      * lasting for few seconds, with an optional action button.
0227      *
0228      * @param message The text message to be shown to the user.
0229      * @param timeout How long to show the message:
0230      *            possible values: "short", "long" or the number of milliseconds
0231      * @param actionText Text in the action button, if any.
0232      * @param callBack A JavaScript function that will be executed when the
0233      *            user clicks the button.
0234      */
0235     function showPassiveNotification(message, timeout, actionText, callBack) {
0236         notificationsObject.showNotification(message, timeout, actionText, callBack);
0237     }
0238
0239     /**
0240      * @brief This function hides the passive notification at specified index, if any is shown.
0241      * @param index Index of the notification to hide. Default is 0 (oldest notification).
0242     */
0243     function hidePassiveNotification(index = 0) {
0244         notificationsObject.hideNotification(index);
0245     }
0246
0247     /**
0248      * @brief This property gets application windows object anywhere in the application.
0249      * @returns a pointer to this item.
0250      */
0251     function applicationWindow() {
0252         return root;
0253     }
0254 //END functions
0255
0256 //BEGIN signals handlers
0257     onMenuBarChanged: {
0258         if (menuBar) {
0259             menuBar.parent = root.contentItem
0260             if (menuBar instanceof T.ToolBar) {
0261                 menuBar.position = T.ToolBar.Footer
0262             } else if (menuBar instanceof T.DialogButtonBox) {
0263                 menuBar.position = T.DialogButtonBox.Footer
0264             }
0265             menuBar.width = Qt.binding(() => root.contentItem.width)
0266             // FIXME: (root.header.height ?? 0) when we can depend from 5.15
0267             menuBar.y = Qt.binding(() => -menuBar.height - (root.header.height ? root.header.height : 0))
0268         }
0269     }
0270
0271     onHeaderChanged: {
0272         if (header) {
0273             header.parent = root.contentItem
0274             if (header instanceof T.ToolBar) {
0275                 header.position = T.ToolBar.Header
0276             } else if (header instanceof T.DialogButtonBox) {
0277                 header.position = T.DialogButtonBox.Header
0278             }
0279             header.width = Qt.binding(() => root.contentItem.width)
0280             header.y = Qt.binding(() => -header.height)
0281         }
0282     }
0283
0284     onFooterChanged: {
0285         if (footer) {
0286             footer.parent = root.contentItem
0287             if (footer instanceof T.ToolBar) {
0288                 footer.position = T.ToolBar.Footer
0289             } else if (footer instanceof T.DialogButtonBox) {
0290                 footer.position = T.DialogButtonBox.Footer
0291             }
0292             footer.width = Qt.binding(() => root.contentItem.width)
0293             footer.y = Qt.binding(() => root.contentItem.height)
0294         }
0295     }
0296
0297     onBackgroundChanged: {
0298         if (background) {
0299             background.parent = root.contentItem
0300             background.anchors.fill = background.parent
0301         }
0302     }
0303
0304     onPageStackChanged: pageStack.parent = root.contentItem;
0305 //END signals handlers
0306
0307     LayoutMirroring.enabled: Qt.application.layoutDirection === Qt.RightToLeft
0308     LayoutMirroring.childrenInherit: true
0309
0310     TP.PassiveNotificationsManager {
0311         id: notificationsObject
0312         anchors.bottom: parent.bottom
0313         anchors.horizontalCenter: parent.horizontalCenter
0314         z: 1
0315     }
0316
0317     Item {
0318         anchors.fill: parent
0319         parent: root.parent || root
0320         z: 999999
0321
0322         Item {
0323             id: overlayRoot
0324             z: -1
0325             anchors.fill: parent
0326         }
0327     }
0328
0329     // Don't use root.overlay property here. For one, we know that in a window
0330     // it will always be the same as T.Overlay.overlay; secondly Drawers
0331     // don't care about being contained/parented to anything else anyway.
0332     onGlobalDrawerChanged: {
0333         if (globalDrawer) {
0334             globalDrawer.parent = Qt.binding(() => visible ? T.Overlay.overlay : null);
0335         }
0336     }
0337     onContextDrawerChanged: {
0338         if (contextDrawer) {
0339             contextDrawer.parent = Qt.binding(() => visible ? T.Overlay.overlay : null);
0340         }
0341     }
0342
0343     Window.onWindowChanged: {
0344         if (globalDrawer) {
0345             globalDrawer.visible = globalDrawer.drawerOpen;
0346         }
0347         if (contextDrawer) {
0348             contextDrawer.visible = contextDrawer.drawerOpen;
0349         }
0350     }
0351
0352     implicitWidth: Kirigami.Settings.isMobile ? Kirigami.Units.gridUnit * 30 : Kirigami.Units.gridUnit * 55
0353     implicitHeight: Kirigami.Settings.isMobile ? Kirigami.Units.gridUnit * 45 : Kirigami.Units.gridUnit * 40
0354     visible: true
0355 }