KNewStuff

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

KDE's Doxygen guidelines are available online.