Kirigami-addons

ConfigurationView.qml
1// SPDX-FileCopyrightText: 2024 Carl Schwan <carl@carlschwan.eu>
2// SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
3
4import QtQuick
5import QtQml
6import org.kde.kirigami as Kirigami
7import org.kde.kirigamiaddons.settings.private as Private
8
9/**
10 * This is an abstract view to display the configuration of an application.
11 *
12 * The various configuration modules can be defined by providing ConfigurationModule
13 * to the modules property.
14 *
15 * On desktop, this will display the modules in a list view and displaying
16 * the actual page next to it. On mobile, only the list of modules will be
17 * initially displayed.
18 *
19 * @code
20 * import QtQuick.Controls as Controls
21 * import org.kde.kirigamiaddons.settings as KirigamiSettings
22 *
23 * Controls.Button {
24 * id: button
25 *
26 * KirigamiSettings.ConfigurationView {
27 * id: configuration
28 *
29 * window: button.Controls.ApplicationWindow.window as Kirigami.ApplicationWindow
30 *
31 * modules: [
32 * KirigamiSettings.ConfigurationModule {
33 * moduleId: "appearance"
34 * text: i18nc("@action:button", "Appearance")
35 * icon.name: "preferences-desktop-theme-global"
36 * page: () => Qt.createComponent("org.kde.tokodon", "AppearancePage")
37 * },
38 * ...
39 * KirigamiSettings.ConfigurationModule {
40 * moduleId: "about"
41 * text: i18nc("@action:button", "About Tokodon")
42 * icon.name: "help-about"
43 * page: () => Qt.createComponent("org.kde.kirigamiaddons.formcard", "AboutPage")
44 * category: i18nc("@title:group", "About")
45 * },
46 * KirigamiSettings.ConfigurationModule {
47 * moduleId: "aboutkde"
48 * text: i18nc("@action:button", "About KDE")
49 * icon.name: "kde"
50 * page: () => Qt.createComponent("org.kde.kirigamiaddons.formcard", "AboutKDE")
51 * category: i18nc("@title:group", "About")
52 * }
53 * ]
54 * }
55 *
56 * icon.name: 'settings-configure-symbolic'
57 * text: i18nc("@action:button", "Settings")
58 *
59 * onClicked: configuration.open()
60 * }
61 * @endcode
62 *
63 * This will result in the following dialog on desktop.
64 *
65 * @image html settingsdialogdesktop.png
66 *
67 * On the following page on mobile.
68 *
69 * @image html settingsdialogmobile.png
70 *
71 * @since KirigamiAddons 1.3.0
72 */
73QtObject {
74 id: root
75
76 /**
77 * @brief This property holds the title of the config view.
78 *
79 * By default this is "Settings"
80 */
81 property string title: i18ndc("kirigami-addons6", "@title:window", "Settings")
83 /**
84 * @brief This property holds the list of pages for the settings.
85 */
86 property list<ConfigurationModule> modules
87
88 /**
89 * @brief This property holds the parent window.
90 *
91 * This needs to be set before calling open.
92 */
93 property Kirigami.ApplicationWindow window
94
95 /**
96 * Open the configuration window.
97 * @params defaultModule The moduleId of the default configuration that should be preselected when opening the configuration view. By default is not specified, this will choose the first module.
98 */
99 function open(defaultModule = ''): void {
100 if (Kirigami.Settings.isMobile) {
101 const component = Qt.createComponent('org.kde.kirigamiaddons.settings.private', 'ConfigMobilePage');
102 if (component.status === Component.Failed) {
103 console.error(component.errorString());
104 return;
105 }
106 root.window.pageStack.layers.push(component, {
107 defaultModule: defaultModule,
108 modules: root.modules,
109 title: root.title,
110 window: root.window,
111 })
112 } else {
113 const component = Qt.createComponent('org.kde.kirigamiaddons.settings.private', 'ConfigWindow');
114 if (component.status === Component.Failed) {
115 console.error(component.errorString());
116 return;
117 }
118 component.createObject(null, {
119 defaultModule: defaultModule,
120 modules: root.modules,
121 width: Kirigami.Units.gridUnit * 50,
122 height: Kirigami.Units.gridUnit * 30,
123 minimumWidth: Kirigami.Units.gridUnit * 50,
124 minimumHeight: Kirigami.Units.gridUnit * 30,
125 title: root.title,
126 });
127 }
128 }
129}
130
QWidget * window() const const
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Dec 6 2024 12:05:53 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.