MauiKit Controls

ApplicationWindow.qml
1/*
2 * Copyright 2018 Camilo Higuita <milo.h@aol.com>
3 *
4 * This program is free software; you can redistribute it and/or modify
5 * it under the terms of the GNU Library General Public License as
6 * published by the Free Software Foundation; either version 2, or
7 * (at your option) any later version.
8 *
9 * This program is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 * GNU General Public License for more details
13 *
14 * You should have received a copy of the GNU Library General Public
15 * License along with this program; if not, write to the
16 * Free Software Foundation, Inc.,
17 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
18 */
19
20import QtQuick
21import QtCore
22
23import QtQuick.Controls
24
25import org.mauikit.controls as Maui
26
27import "private" as Private
28
29/**
30 * @inherit org::mauikit::controls::Private::BaseWindow
31 * @brief A window that provides some basic features needed for most applications.
32 *
33 * <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>
34 *
35 * 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.
36 * 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.
37 * For a header and footer section use a MauiKit Page, and for the menu-bar alternative, use a MauiKit ToolButtonMenu.
38 *
39 * @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.
40 *
41 * 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..
42 * @see Page
43 * @see AppViews
44 * @see SideBarView
45 * @see TabView
46 * @see PageLayout
47 *
48 * @code
49 * ApplicationWindow
50 * {
51 * id: root
52 *
53 * Page
54 * {
55 * anchors.fill: parent
56 * Maui.Controls.showCSD: true
57 * }
58 * }
59 * @endcode
60 *
61 * @image html ApplicationWindow/empty_dark.png "ApplicationWindow filled with a Page and the CSD controls enabled"
62 *
63 * @section csd Client Side Decorations
64 *
65 * @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.
66 *
67 * The application window can make use of client side decorations (CSD) by setting the attached property `Maui.CSD.enabled: true` in the root element just once,
68 * 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).
69 * @see MauiMan
70 *
71 * @note The alternative is to use the server side decorations (SSD).
72 *
73 * 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.
74 *
75 * 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.
76 *
77 * 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.
78 * @see Controls
79 *
80 * 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.
81 * @see WindowControlsLinux
82 *
83 * @code
84 * ApplicationWindow
85 * {
86 * id: root
87 *
88 * QQC2.Page
89 * {
90 * anchors.fill: parent
91 *
92 * WindowControls
93 * {
94 * anchors.top: parent.top
95 * anchors.right: parent.right
96 * }
97 * }
98 * }
99 * @endcode
100 *
101 * @section functionality Built-in Functionality
102 *
103 * @subsection aboutdialog About Dialog
104 * The Application window has some components already built-in, such as an about dialog, which can be invoked using the function `about()`.
105 * @see about
106 *
107 * 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.
108 *
109 * Some extra information can be added via the MauiApp singleton instance, such as more links.
110 *
111 * @image html ApplicationWindow/aboutdialog.png "About dialog with information provided by the app"
112 *
113 * @subsection toastarea Toast Area - Notifications
114 * 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.
115 * @see notify
116 *
117 * @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.
118 * @see Notify
119 *
120 * @image html ApplicationWindow/toastarea.png "Inline notifications in the toast area"
121 *
122 * @section notes Notes
123 * By default the window geometry is saved and restored automatically.
124 *
125 * 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.
126 * @see MauiApp
127 *
128 * 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.
129 * @see KAboutData
130 *
131 * @code
132 * #include <MauiKit4/Core/mauiapp.h>
133 * #include <KAboutData>
134 *
135 * int main(int argc, char *argv[])
136 * {
137 * QGuiApplication app(argc, argv);
138 *
139 * app.setOrganizationName(QStringLiteral("Maui"));
140 * app.setWindowIcon(QIcon(":/assets/mauidemo.svg"));
141 *
142 * KAboutData about(QStringLiteral("mauidemo"),
143 * i18n("Maui Demo"),
144 * "3.0.0",
145 * i18n("MauiKit Qt6 Demo."),
146 * KAboutLicense::LGPL_V3); //here you can set information about the application, which will be fetched by the about dialog.
147 *
148 * about.addAuthor(i18n("Camilo Higuita"), i18n("Developer"), QStringLiteral("milo.h@aol.com"));
149 * about.setHomepage("https://mauikit.org");
150 * about.setProductName("maui/index");
151 * about.setBugAddress("https://invent.kde.org/maui/index-fm/-/issues");
152 * about.setOrganizationDomain("org.qt6.tst");
153 * about.setProgramLogo(app.windowIcon());
154 * about.addComponent("KIO");
155 *
156 * KAboutData::setApplicationData(about);
157 * 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.
158 *
159 * QQmlApplicationEngine engine;
160 * const QUrl url(u"qrc:/qt/qml/MauiDemo4/main.qml"_qs);
161 * QObject::connect(&engine, &QQmlApplicationEngine::objectCreated,
162 * &app, [url](QObject *obj, const QUrl &objUrl) {
163 * if (!obj && url == objUrl)
164 * QCoreApplication::exit(-1);
165 * }, Qt::QueuedConnection);
166 *
167 * engine.load(url);
168 *
169 * return app.exec();
170 * }
171 * @endcode
172 *
173 * @section styling Styling
174 * 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.
175 * The available options are:
176 * - Style.Light
177 * - Style.Dark
178 * - Style.Adaptive
179 * - Style.Auto
180 * - Style.TrueBlack
181 * - Style.Inverted
182 * @see Style::StyleType
183 *
184 * 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.
185 *
186 * The accent color can also be changed easily to distinguish the app own branding, by using the `Style.accentColor` property once.
187 * @see Style::accentColor
188 *
189 * @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.
190 * @see Style
191 *
192 * @code
193 * ApplicationWindow
194 * {
195 * id: root
196 * Maui.Style.styleType: 1 // 0-light, 1-dark, 2-adaptive, 3-auto etc
197 * Maui.Style.accentColor: "pink"
198 *
199 * Page
200 * {
201 * anchors.fill: parent
202 * Maui.Controls.showCSD: true
203 * }
204 * }
205 * @endcode
206 *
207 * @image html ApplicationWindow/color_styles.png "All the different color styles available"
208 *
209 * You can check out our quick tutorial on creating a simple Maui application here:
210 *
211 * <a href="QuickApp.dox">External file</a>
212 *
213 * @section example Example
214 *
215 * The most basic use case is to use a Page inside of the ApplicationWindow as shown below.
216 * @code
217 * ApplicationWindow
218 * {
219 * id: root
220 *
221 * Page
222 * {
223 * anchors.fill: parent
224 * Maui.Controls.showCSD: true
225 * }
226 * }
227 * @endcode
228 *
229 * <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>
230 */
231
232Private.BaseWindow
233{
234 id: root
235
236 isDialog: false
237
238 Settings
239 {
240 property alias x: root.x
241 property alias y: root.y
242 property alias width: root.width
243 property alias height: root.height
244 }
245
246 Loader
247 {
248 id: dialogLoader
249 }
250
251 Component
252 {
253 id: _aboutDialogComponent
254
255 Private.AboutDialog
256 {
257 onClosed: destroy()
258 }
259 }
260
261 Connections
262 {
263 target: Maui.Platform
264 ignoreUnknownSignals: true
265 function onShareFilesRequest(urls)
266 {
267 dialogLoader.source = "private/ShareDialog.qml"
268 dialogLoader.item.urls = urls
269 dialogLoader.item.open()
270 }
271 }
272
273 Connections
274 {
275 target: Maui.Style
276 ignoreUnknownSignals: true
277 function onStyleTypeChanged()
278 {
279 console.log("THE COLOR STYLE CHANGED FROM ANDROID")
280 if(Maui.Handy.isAndroid)
281 {
282 setAndroidStatusBarColor()
283 }
284 }
285 }
286
287 Component.onCompleted:
288 {
289 Maui.App.rootComponent = root
290 if(Maui.Handy.isAndroid)
291 {
292 setAndroidStatusBarColor()
293 }
294 }
295
296 /**
297 * @brief Invokes the about dialog with information of the application.
298 * This information is taken from `KAboutData` and `MauiApp` singleton instance.
299 * @note This method can be invoked for the main root ApplicationWindow using the `Maui.App.aboutDialog()` attached property method.
300 */
301 function about()
302 {
303 var about = _aboutDialogComponent.createObject(root)
304 about.open()
305 }
306
307 function setAndroidStatusBarColor()
308 {
309 if(Maui.Handy.isAndroid)
310 {
311 const dark = Maui.Style.styleType === Maui.Style.Dark
312 console.log("SET THE ANDROID STSTUS BAR COLOR", dark)
313
314 Maui.Android.statusbarColor(Maui.Theme.backgroundColor, !dark)
315 Maui.Android.navBarColor( Maui.Theme.backgroundColor, !dark)
316 }
317 }
318}
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Nov 8 2024 11:48:43 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.