Warning, /maui/mauikit/src/controls.6/ApplicationWindow.qml is written in an unsupported language. File is not indexed.
0001 /* 0002 * Copyright 2018 Camilo Higuita <milo.h@aol.com> 0003 * 0004 * This program is free software; you can redistribute it and/or modify 0005 * it under the terms of the GNU Library General Public License as 0006 * published by the Free Software Foundation; either version 2, or 0007 * (at your option) any later version. 0008 * 0009 * This program is distributed in the hope that it will be useful, 0010 * but WITHOUT ANY WARRANTY; without even the implied warranty of 0011 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 0012 * GNU General Public License for more details 0013 * 0014 * You should have received a copy of the GNU Library General Public 0015 * License along with this program; if not, write to the 0016 * Free Software Foundation, Inc., 0017 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 0018 */ 0019 0020 import QtQuick 0021 import QtCore 0022 0023 import QtQuick.Controls 0024 0025 import org.mauikit.controls 1.3 as Maui 0026 0027 import "private" as Private 0028 0029 /** 0030 * @inherit org::mauikit::controls::Private::BaseWindow 0031 * @brief A window that provides some basic features needed for most applications. 0032 * 0033 * <a href="https://doc.qt.io/qt-6/qml-qtquick-window.html">This controls inherits from QQC2 Window, to checkout its inherited properties refer to the Qt Docs.</a> 0034 * 0035 * The ApplicationWindow is the best component to start creating a new MauiKit application. It's usually used as the root QML component for the application. 0036 * It is different from the QQC2 alternative, as this one does not include a header or footer section, and does not have either a menu-bar. 0037 * For a header and footer section use a MauiKit Page, and for the menu-bar alternative, use a MauiKit ToolButtonMenu. 0038 * 0039 * @warning By default the window is completely empty (and transparent since it doesn't have any container's background) - and if used with CSD (Client Side Decorations) enabled, not window controls are visible. See the example below on how to fill the application window. 0040 * 0041 * Commonly, this is paired with another child container control, such as a Page, an AppViews or a SideBarView, to name a few MauiKit controls; or with any other QQC2 element, such as a StackView, SwipeView, etc.. 0042 * @see Page 0043 * @see AppViews 0044 * @see SideBarView 0045 * @see TabView 0046 * @see PageLayout 0047 * 0048 * @code 0049 * ApplicationWindow 0050 * { 0051 * id: root 0052 * 0053 * Page 0054 * { 0055 * anchors.fill: parent 0056 * Maui.Controls.showCSD: true 0057 * } 0058 * } 0059 * @endcode 0060 * 0061 * @image html ApplicationWindow/empty_dark.png "ApplicationWindow filled with a Page and the CSD controls enabled" 0062 * 0063 * @section csd Client Side Decorations 0064 * 0065 * @note Client-side decorations refers to an application window that takes care of drawing its own window borders, shadows, and the window control buttons - and also provides the resizing and moving/dragging functionality. 0066 * 0067 * The application window can make use of client side decorations (CSD) by setting the attached property `Maui.App.controls.enabledCSD: true` in the root element just once, 0068 * or globally by making use of MauiMan configuration options - that said, even if the system is configured to use CSD globally, you can override this property in your application, to force to use CSD (or not). 0069 * @see MauiMan 0070 * 0071 * @note The alternative is to use the server side decorations (SSD). 0072 * 0073 * When using CSD, the ApplicationWindow will take care of drawing the window borders, the shadow and masking its content to support the border rounded corners. 0074 * 0075 * The radius of the corners is configured via MauiMan. To know more about how to configure it from a user level take a look at MauiMan documentation. This property can not be overridden by the application itself. 0076 * 0077 * If used with a Page, you can easily enable the CSD window buttons using the attached property `Maui.Controls.showCSD`, this will make the window-control-buttons visible. A few other MauiKit controls support this property, such as the TabView, ToolBar, AppViews, AltBrowser and TabView, and any other control that inherits from Page. 0078 * @see Controls 0079 * 0080 * If a custom control is to be used instead, and CSD is still enabled, you can place the window control buttons manually, by using the WindowControls component. 0081 * @see WindowControlsLinux 0082 * 0083 * @code 0084 * ApplicationWindow 0085 * { 0086 * id: root 0087 * 0088 * QQC2.Page 0089 * { 0090 * anchors.fill: parent 0091 * 0092 * WindowControls 0093 * { 0094 * anchors.top: parent.top 0095 * anchors.right: parent.right 0096 * } 0097 * } 0098 * } 0099 * @endcode 0100 * 0101 * @section functionality Built-in Functionality 0102 * 0103 * @subsection aboutdialog About Dialog 0104 * The Application window has some components already built-in, such as an about dialog, which can be invoked using the function `about()`. 0105 * @see about 0106 * 0107 * The information presented in the dialog is taken from the data set with KAboutData at the application entry point. There is an example on how to set the information in the code snippet below. 0108 * 0109 * Some extra information can be added via the MauiApp singleton instance, such as more links. 0110 * 0111 * @image html ApplicationWindow/aboutdialog.png "About dialog with information provided by the app" 0112 * 0113 * @subsection toastarea Toast Area - Notifications 0114 * The ApplicationWindow also includes an overlay layer for displaying inline notifications, which can be dispatched by using the function `notify()`. The notifications sent can be interactive. 0115 * @see notify 0116 * 0117 * @note If you want to use the system notifications instead, take a look at the Notify object class, and the docs on how to configure the needed steps to set it up. 0118 * @see Notify 0119 * 0120 * @image html ApplicationWindow/toastarea.png "Inline notifications in the toast area" 0121 * 0122 * @section notes Notes 0123 * By default the window geometry is saved and restored automatically. 0124 * 0125 * In order for the style and other functionality to work correctly the `MauiApp` singleton instance must have been initialize before the ApplicationWindow is created. This is usually done on the main entry point of the application. 0126 * @see MauiApp 0127 * 0128 * It is important to notice that some of the application information needs to be provided beforehand as well, using the `KAboutData` methods, this way the built-in about dialog can pick up all the relevant information. 0129 * @see KAboutData 0130 * 0131 * @code 0132 * #include <MauiKit4/Core/mauiapp.h> 0133 * #include <KAboutData> 0134 * 0135 * int main(int argc, char *argv[]) 0136 * { 0137 * QGuiApplication app(argc, argv); 0138 * 0139 * app.setOrganizationName(QStringLiteral("Maui")); 0140 * app.setWindowIcon(QIcon(":/assets/mauidemo.svg")); 0141 * 0142 * KAboutData about(QStringLiteral("mauidemo"), 0143 * i18n("Maui Demo"), 0144 * "3.0.0", 0145 * i18n("MauiKit Qt6 Demo."), 0146 * KAboutLicense::LGPL_V3); //here you can set information about the application, which will be fetched by the about dialog. 0147 * 0148 * about.addAuthor(i18n("Camilo Higuita"), i18n("Developer"), QStringLiteral("milo.h@aol.com")); 0149 * about.setHomepage("https://mauikit.org"); 0150 * about.setProductName("maui/index"); 0151 * about.setBugAddress("https://invent.kde.org/maui/index-fm/-/issues"); 0152 * about.setOrganizationDomain("org.qt6.tst"); 0153 * about.setProgramLogo(app.windowIcon()); 0154 * about.addComponent("KIO"); 0155 * 0156 * KAboutData::setApplicationData(about); 0157 * MauiApp::instance()->setIconName("qrc:/assets/mauidemo.svg"); // this not only sets the path to the icon file asset, but also takes care of initializing the MauiApp singleton instance. 0158 * 0159 * QQmlApplicationEngine engine; 0160 * const QUrl url(u"qrc:/qt/qml/MauiDemo4/main.qml"_qs); 0161 * QObject::connect(&engine, &QQmlApplicationEngine::objectCreated, 0162 * &app, [url](QObject *obj, const QUrl &objUrl) { 0163 * if (!obj && url == objUrl) 0164 * QCoreApplication::exit(-1); 0165 * }, Qt::QueuedConnection); 0166 * 0167 * engine.load(url); 0168 * 0169 * return app.exec(); 0170 * } 0171 * @endcode 0172 * 0173 * @section styling Styling 0174 * The ApplicationWindow style - as other MauiKit controls - can be tweaked, for example its color scheme: from dark to light variant, but also true-black, high-contrast, and an adaptive style which picks colors from an image source, such as a wallpaper. 0175 * The available options are: 0176 * - Style.Light 0177 * - Style.Dark 0178 * - Style.Adaptive 0179 * - Style.Auto 0180 * - Style.TrueBlack 0181 * - Style.Inverted 0182 * @see Style::StyleType 0183 * 0184 * All these can be individually changed by the application or set to `undefined` to rest it back to follow the global system preference from MauiMan. 0185 * 0186 * The accent color can also be changed easily to distinguish the app own branding, by using the `Style.accentColor` property once. 0187 * @see Style::accentColor 0188 * 0189 * @warning When mixing Kirigami components with MauiKit controls, it is best to set the style type to the `Maui.Style.Auto` option (which value is 3), for it to correctly pick up the same color-scheme Kirigami uses - since Kirigami uses another methods for setting the color palette. The option can be set using `Maui.Style.styleType: Maui.Style.Auto`. With this set Maui will pickup the colors from the Plasma color scheme. 0190 * @see Style 0191 * 0192 * @code 0193 * ApplicationWindow 0194 * { 0195 * id: root 0196 * Maui.Style.styleType: 1 // 0-light, 1-dark, 2-adaptive, 3-auto etc 0197 * Maui.Style.accentColor: "pink" 0198 * 0199 * Page 0200 * { 0201 * anchors.fill: parent 0202 * Maui.Controls.showCSD: true 0203 * } 0204 * } 0205 * @endcode 0206 * 0207 * @image html ApplicationWindow/color_styles.png "All the different color styles available" 0208 * 0209 * You can check out our quick tutorial on creating a simple Maui application here: 0210 * 0211 * <a href="QuickApp.dox">External file</a> 0212 * 0213 * @section example Example 0214 * 0215 * The most basic use case is to use a Page inside of the ApplicationWindow as shown below. 0216 * @code 0217 * ApplicationWindow 0218 * { 0219 * id: root 0220 * 0221 * Page 0222 * { 0223 * anchors.fill: parent 0224 * Maui.Controls.showCSD: true 0225 * } 0226 * } 0227 * @endcode 0228 * 0229 * <a href="https://invent.kde.org/maui/mauikit/-/blob/qt6-2/examples/ApplicationWindow.qml">You can find a more complete example at this link.</a> 0230 */ 0231 0232 Private.BaseWindow 0233 { 0234 id: root 0235 0236 isDialog: false 0237 Settings 0238 { 0239 property alias x: root.x 0240 property alias y: root.y 0241 property alias width: root.width 0242 property alias height: root.height 0243 } 0244 0245 Loader 0246 { 0247 id: dialogLoader 0248 } 0249 0250 Component 0251 { 0252 id: _aboutDialogComponent 0253 0254 Private.AboutDialog 0255 { 0256 onClosed: destroy() 0257 } 0258 } 0259 0260 Connections 0261 { 0262 target: Maui.Platform 0263 ignoreUnknownSignals: true 0264 function onShareFilesRequest(urls) 0265 { 0266 dialogLoader.source = "private/ShareDialog.qml" 0267 dialogLoader.item.urls = urls 0268 dialogLoader.item.open() 0269 } 0270 } 0271 0272 0273 0274 /** 0275 * @brief Invokes the about dialog with information of the application. 0276 * This information is taken from `KAboutData` and `MauiApp` singleton instance. 0277 */ 0278 function about() 0279 { 0280 var about = _aboutDialogComponent.createObject(root) 0281 about.open() 0282 } 0283 }