KNewStuff

Action.qml
1/*
2 SPDX-FileCopyrightText: 2021 Dan Leinir Turthra Jensen <admin@leinir.dk>
3 SPDX-FileCopyrightText: 2023 ivan tkachenko <me@ratijas.tk>
4
5 SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
6*/
7
8/**
9 * @brief An action which when triggered will open a NewStuff.Dialog or a NewStuff.Page, depending on settings
10 *
11 * This component is equivalent to the old Button component, but functions in more modern applications
12 *
13 * The following is a simple example of how to use this Action to show wallpapers from the KDE Store, on a
14 * system where Plasma has been installed (and consequently the wallpaper knsrc file is available). This also
15 * shows how to make the action push a page to a pageStack rather than opening a dialog:
16 *
17\code{.qml}
18import org.kde.newstuff as NewStuff
19
20NewStuff.Action {
21 configFile: "wallpaper.knsrc"
22 text: i18n("&Get New Wallpapers…")
23 pageStack: applicationWindow().pageStack
24 onEntryEvent: function(entry, event) {
25 if (event === NewStuff.Entry.StatusChangedEvent) {
26 // A entry was installed, updated or removed
27 } else if (event === NewStuff.Entry.AdoptedEvent) {
28 // The "AdoptionCommand" from the knsrc file was run for the given entry.
29 // This should not require refreshing the data for the model
30 }
31 }
32}
33\endcode
34 *
35 * @see NewStuff.Button
36 * @since 5.81
37 */
38
39import QtQuick
40import org.kde.kirigami as Kirigami
41import org.kde.newstuff as NewStuff
42
43Kirigami.Action {
44 id: component
45
46 /*
47 * The configuration file is not aliased, because then we end up initialising the
48 * Engine immediately the Action is instantiated, which we want to avoid (as that
49 * is effectively a phone-home scenario, and causes internet traffic in situations
50 * where it would not seem likely that there should be any).
51 * If we want, in the future, to add some status display to the Action (such as "there
52 * are updates to be had" or somesuch, then we can do this, but until that choice is
53 * made, let's not)
54 */
55 /**
56 * The configuration file to use for the Page created by this action
57 */
58 property string configFile
59
60 /**
61 * The default view mode of the page spawned by this action. This should be
62 * set using the NewStuff.Page.ViewMode enum
63 * @see NewStuff.Page.ViewMode
64 */
65 property int viewMode: NewStuff.Page.ViewMode.Preview
66
67 /**
68 * If this is set, the action will push a NewStuff.Page onto this page stack
69 * (and request it is made visible if triggered again). If you do not set this
70 * property, the action will spawn a NewStuff.Dialog instead.
71 * @note If you are building a KCM, set this to your ```kcm``` object.
72 */
73 property QtObject pageStack: null
74
75 /**
76 * The engine which handles the content in this Action
77 * This will be null until the action has been triggered the first time
78 */
79 readonly property QtObject engine: component._private.engine
80
81 /**
82 * This forwards the entry changed event from the QtQuick engine
83 * @see Engine::entryEvent
84 */
85 signal entryEvent(var entry, int event)
86
87 /**
88 * If this is true (default is false), the action will be shown when the Kiosk settings are such
89 * that Get Hot New Stuff is disallowed (and any other time enabled is set to false).
90 * Usually you would want to leave this alone, but occasionally you may have a reason to
91 * leave a action in place that the user is unable to enable.
92 */
93 property bool visibleWhenDisabled: false
94
95 /**
96 * The parent window for the dialog created by invoking the action
97 *
98 * @since 6.1
99 */
100 property Window transientParent
101
102 /**
103 * Show the page/dialog (same as activating the action), if allowed by the Kiosk settings
104 */
105 function showHotNewStuff() {
106 component._private.showHotNewStuff();
107 }
108
109 onTriggered: showHotNewStuff()
110
111 icon.name: "get-hot-new-stuff"
112 visible: enabled || visibleWhenDisabled
113 enabled: NewStuff.Settings.allowedByKiosk
114 onEnabledChanged: {
115 // If the user resets this when kiosk has disallowed ghns, force enabled back to false
116 if (enabled && !NewStuff.Settings.allowedByKiosk) {
117 enabled = false;
118 }
119 }
120
122 property QtObject engine: pageItem ? pageItem.engine : null
123 // Probably wants to be deleted and cleared if the "mode" changes at runtime...
124 property QtObject pageItem
125
126 property string providerId
127 property string entryId
128
129 readonly property Connections showSpecificEntryConnection: Connections {
130 target: component.engine
131
132 function onInitialized() {
133 pageItem.showEntryDetails(providerId, component._private.entryId);
134 }
135 }
136
137 readonly property Connections engineConnections: Connections {
138 target: component.engine
139
140 function onEntryEvent(entry, event) {
141 component.entryEvent(entry, event);
142 }
143 }
144
145 function showHotNewStuff() {
146 if (NewStuff.Settings.allowedByKiosk) {
147 if (component.pageStack !== null) {
148 if (component._private.pageItem // If we already have a page created...
149 && (component.pageStack.columnView !== undefined // first make sure that this pagestack is a Kirigami-style one (otherwise just assume we're ok)
150 && component.pageStack.columnView.contains(component._private.pageItem))) // and then check if the page is still in the stack before attempting to...
151 {
152 // ...set the already existing page as the current page
153 component.pageStack.currentItem = component._private.pageItem;
154 } else {
155 component._private.pageItem = newStuffPage.createObject(component);
156 component.pageStack.push(component._private.pageItem);
157 }
158 } else {
159 newStuffDialog.open();
160 }
161 } else {
162 // make some noise, because silently doing nothing is a bit annoying
163 }
164 }
165
166 property Component newStuffPage: Component {
167 NewStuff.Page {
168 configFile: component.configFile
169 viewMode: component.viewMode
170 }
171 }
172
173 property Item newStuffDialog: Loader {
174 // Use this function to open the dialog. It seems roundabout, but this ensures
175 // that the dialog is not constructed until we want it to be shown the first time,
176 // since it will initialise itself on the first load (which causes it to phone
177 // home) and we don't want that until the user explicitly asks for it.
178 function open() {
179 if (item) {
180 item.open();
181 } else {
182 active = true;
183 }
184 }
185
186 onLoaded: {
187 component._private.pageItem = item;
188 item.open();
189 }
190
191 active: false
192 asynchronous: true
193
194 sourceComponent: NewStuff.Dialog {
195 transientParent: component.transientParent
196 configFile: component.configFile
197 viewMode: component.viewMode
198 }
199 }
200 }
201}
QAction * open(const QObject *recvr, const char *slot, QObject *parent)
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri May 24 2024 11:54:38 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.