Warning, /frameworks/knewstuff/README.md is written in an unsupported language. File is not indexed.
0001 # KNewStuff 0002 0003 Framework for downloading and sharing additional application data 0004 0005 ## Introduction 0006 0007 The KNewStuff library implements collaborative data sharing for 0008 applications. It uses libattica to support the Open Collaboration Services 0009 specification. 0010 0011 0012 ## Usage 0013 0014 There are three parts to KNewStuff: 0015 0016 * *KNewStuffCore* - The core functionality, which takes care of the actual work 0017 (downloading data and interacting with the remote services). Importantly, this 0018 library has no dependencies past Tier 1, and so while the entire framework is 0019 to be considered Tier 3, the KNewStuffCore library can be considered Tier 2 0020 for integration purposes. 0021 * *KNewStuff* - A Qt Widget based UI library, designed for ease of implementation of 0022 various UI patterns found through KDE applications (such as the Get New Stuff buttons, 0023 as well as generic download and upload dialogues) 0024 * *KNewStuffQuick* - A set of Qt Quick based components designed to provide similar 0025 pattern support as KNewStuff, except for Qt Quick based applications, and specifically 0026 in Kirigami based applications. 0027 0028 If you are using CMake, you need to find the modules, which can be done by doing one of 0029 the following in your CMakeLists.txt: 0030 0031 Either use the more modern (and compact) component based method (only actually add the 0032 component you need, since both NewStuff and NewStuffQuick depend on NewStuffCore): 0033 0034 find_package(KF5 COMPONENTS NewStuffCore NewStuff NewStuffQuick) 0035 0036 Or use the old-fashioned syntax 0037 0038 find_package(KF5NewStuffCore CONFIG) # for the KNewStuffCore library only 0039 find_package(KF5NewStuff CONFIG) # for the KNewStuff UI library, will pull in KNewStuffCore for you 0040 find_package(KF5NewStuffQuick CONFIG) # for the KNewStuffQuick UI library, will pull in KNewStuffCore for you 0041 0042 Also remember to link to the library you are using (either KF5::NewStuff or 0043 KF5::NewStuffCore), and for the Qt Quick NewStuffQuick module, add the following 0044 to the QML files where you wish to use the components: 0045 0046 import org.kde.newstuff 1.0 0047 0048 Finally, because KNewStuffQuick is not a link time requirement, it would be good form 0049 to mark it as a runtime requirement (and describing why you need them), which is done 0050 by adding the following in your CMakeLists.txt sometime after the find statement: 0051 0052 set_package_properties(KF5NewStuffQuick PROPERTIES 0053 DESCRIPTION "Qt Quick components used for interacting with remote data services" 0054 URL "https://api.kde.org/frameworks/knewstuff/html/index.html" 0055 PURPOSE "Required to Get Hot New Stuff for my application" 0056 TYPE RUNTIME) 0057 0058 When installing your knsrc configuration file, you should install it into the location 0059 where KNewStuffCore expects it to be found. Do this by using the CMake variable 0060 `KDE_INSTALL_KNSRCDIR` as provided by the KNewStuffCore module, since 5.57.0. 0061 To support older versions you can use the CMake variable `KDE_INSTALL_CONFDIR` from 0062 [Extra-CMake-Modules' KDEInstallDirs](https://api.kde.org/ecm/kde-module/KDEInstallDirs.html). 0063 You can also handle this yourself, which means you will need to feed `Engine::init()` 0064 the full path to the knsrc file. 0065 0066 ## Which module should you use? 0067 0068 When building applications designed to fit in with other classic, widget based 0069 applications, the application authors should use KNS3::DownloadDialog for 0070 downloading application content. For uploading KNS3::UploadDialog is used. 0071 0072 When building Qt Quick (and in particular Kirigami) based applications, you can 0073 use the NewStuffList item from the org.kde.newstuff import to achieve a similar 0074 functionality to KNS3::DownloadDialog. You can also use the ItemsModel directly, 0075 if this is not featureful enough. Uploading is currently not exposed in KNewStuffQuick. 0076 0077 If neither of these options are powerful enough for your needs, you can access 0078 the functionality directly through the classes in the KNSCore namespace. 0079 0080 If you are looking for some tutorials, Techbase has a couple of those here: 0081 [Get Hot New Stuff tutorials](https://techbase.kde.org/Development/Tutorials#Get_Hot_New_Stuff). 0082 0083 ## Configuration Files 0084 0085 The Engine (and consequently all the various abstracted options like Page and Dialog) is configured by a KNewStuff 0086 Resource and Configuration, or .knsrc file for short, containing the details of how the engine should be set up. 0087 0088 Your application should install a file into the systemwide configuration location defined by the KNSCore CMake module, 0089 which provides the variable `KDE_INSTALL_KNSRCDIR`, which will put the file into something equivalent to 0090 `/usr/share/knsrcfiles/appname.knsrc` (that is, the systemwide data directory, the subdirectory knsrcfiles, and then 0091 appname, which can technically be anything but which should commonly be your application's binary name for consistency 0092 purposes). 0093 0094 As an example, the file might look like this for wallpapers found on the KDE Store: 0095 0096 [KNewStuff3] 0097 Name=Wallpapers 0098 ProvidersUrl=https://autoconfig.kde.org/ocs/providers.xml 0099 Categories=KDE Wallpaper 1920x1200,KDE Wallpaper 1600x1200 0100 XdgTargetDir=wallpapers 0101 Uncompress=archive 0102 0103 ### Name 0104 0105 This sets a human-readable name that KNewStuff can use to tell the user what type of content this knsrc file 0106 provides access to. It will usually be considerably different in nature to the appname of the file itself. 0107 For example, the book store in [Peruse](https://peruse.kde.org) (an electronic reading app by KDE) has the knsrc 0108 filename `peruse.knsrc` for ease of packaging and distribution, whereas this entry in that file is `Name=Books`. 0109 0110 If there is no name set for the file, the UI might end up looking slightly weird (as this results in exposing 0111 the knsrc filename to the end user, which likely will not be what you are intending). 0112 0113 ### ProvidersUrl 0114 0115 To use a local providers file instead of a remote one, you can set `UseLocalProvidersFile=true` instead of 0116 ProvidersUrl. An example of where this would be useful is if you wish to use an 0117 [OPDS feed](https://wiki.mobileread.com/wiki/OPDS). These are likely to not have a providers file, and if you 0118 lack a server on which to host one of your own, being able to simply put it beside the knsrc file becomes useful. 0119 This will make the engine attempt to load a file located next to your knsrc file, with the same name as that 0120 file, with .providers appended. For example, if your configuration file is called `appname.knsrc`, then your 0121 providers file should be named `appname.providers`. 0122 0123 ### Categories 0124 0125 The comma-separated list in the entry Categories defines which subsections of the service should be used to fetch content, 0126 and is further shown in a dropdown list on NewStuff.Page and in KNS3::Dialog. They exist in a three-layer format, where the 0127 usual human-readable ID in the knsrc file corresponds to a UID in the service, which has a number of pieces of metadata 0128 (such as translated human-readable titles). See also KNSCore::Engine::categoriesMetadata(). 0129 0130 To see which categories are available on a particular Attica provider, you can fetch the list by performing a GET call to the 0131 content/categories object (by, for example, opening it in a browser). For example, for an OCS service with the server address 0132 ocs.server.org, you would fetch `https://ocs.server.org/v1/content/categories`, which will give you an XML file, with 0133 all categories available on that service, and their metadata. 0134 0135 ### XdgTargetDir 0136 0137 This defines the location where the downloaded items will be put. This is the name of a directory in your $XDG_DATA_HOME 0138 directory, such as `~/.local/share/wallpapers`, which is what you would get by setting `XdgTargetDir=wallpapers` as in the 0139 example above. 0140 0141 This is what `QStandardPaths::writableLocation(QStandardPaths::GenericDataLocation) + QLatin1Char('/') + name` will return. 0142 0143 The two following options are deprecated and should not be used in new code (and are only listed here to allow you 0144 to understand older knsrc files should you come across them): 0145 0146 * `StandardResource`: Not available in KF5, use XdgTargetDir instead. 0147 * `TargetDir`: Since KF5, this is equivalent to XdgTargetDir. 0148 0149 #### InstallPath 0150 0151 Alternatively to using an XDG data directory, you can bypass this and just have a named location in the user's home directory. 0152 To do this, set `InstallPath` instead of `XdgTargetDir`. For example, setting `InstallPath=Applications` will put downloaded 0153 items into `~/Applications`. 0154 0155 ### Uncompress 0156 0157 Uncompress can be one of: `always`, `never`, `archive`, `surdir`, or `kpackage`: 0158 0159 * `always`: Assume all downloaded files are archives that need to be extracted 0160 * `never`: Never try to extract the file 0161 * `archive`: If the file is an archive, uncompress it, otherwise just pass it on 0162 * `subdir`: Logic as archive, but decompress into a subdirectory named after the payload filename 0163 * `kpackage`: Require that the downloaded file is a kpackage, and use the KPackage framework for handling installation and removal (since 5.70). 0164 See also the note on [KPackage Support below](#kpackage-support) below. 0165 0166 ### Entry and Download Item Tag Filter 0167 0168 Use the `TagFilter` and `DownloadTagFilter` options to set filters based on the abstract tags which can be present 0169 on both entries and the download items they contain. To see the full documentation on this, read further in 0170 KNSCore::Engine::setTagFilter(const QStringList &filter), but the following is an example of its use in a knsrc file: 0171 0172 TagFilter=ghns_excluded!=1,data##mimetype==application/cbr+zip,data##mimetype==application/cbr+rar 0173 0174 This will honor the ghns_exclusion tag (the default value if you do not set one, and generally you should include 0175 this entry). It then further filters out anything that does not include a comic book archive in either ZIP or RAR 0176 format in one or more of the download items. Notice in particular that there are two `data##mimetype` entries. Use this 0177 for when a tag may have multiple values. 0178 0179 ### Automatic Dead Entry Removal 0180 0181 If you set `RemoveDeadEntries=true`, entries whose installed files have all been deleted without going through 0182 KNewStuff will be removed from the cache. The removal will happen only after all listed files have been removed, which 0183 means that if, for example, an entry was installed from archive, which was decompressed to yield multiple installed files, 0184 if even one of those files remains, the entry will remain marked as installed. 0185 0186 **Note** In KDE Frameworks 6, this option will default to `true`, and you should consider switching it on at this point, 0187 and rework your code to support this functionality, or explicitly set it to `false` now, if you need this to retain its 0188 current functionality. 0189 0190 ### Adoption Command 0191 0192 Set the `AdoptionCommand` option to add a supplementary action to the places where entries are displayed which allows the 0193 user to "adopt" the entry (that is, use it in some way, which will depend on the specific type of entry). In NewStuff.Page, 0194 the delegates all get a new button shown on them, and on detail pages, a new action will be shown in either the toolbar 0195 on desktops, or in the context drawer on mobile. 0196 0197 #### Use Label 0198 0199 Usually, once installed, an item will have some canonical way of being used (for example, using a wallpaper will set it 0200 as the wallpaper on the primary desktop, using a color scheme will switch the environment to that scheme), but in some 0201 cases the word "Use" usually used as the label for the action which activates the Adoption Command does not quite fit. 0202 To change this label, you can add an entry like the following to your knsrc file: `UseLabel=Read`, which in this case 0203 will show the word "Read" for that action instead of "Use". 0204 0205 ### Upload Assistance 0206 0207 While KNewStuff does not currently handle content uploading, the UI will attempt to guide users in how to upload new entries 0208 on whatever provider their content is currently coming from. If you as an application developer want to explicitly not 0209 suggest that users should do this, add an `UploadEnabled=false` entry to your configuration file. 0210 0211 Not adding this entry to your configuration will cause KNewStuff to add an entry to NewStuff.Page's contextual actions 0212 with the label "Upload...", which pushes a NewStuff.UploadPage to the stack. At this current time, this page simply 0213 gives instructions on how uploading can be done (with specific attention paid to identifying the KDE Store and giving 0214 more specific instructions for that). 0215 0216 ### Installation Control 0217 0218 The `InstallationCommand` and `UninstallCommand` entries can be used to handle items once they have been put into their 0219 installation location. For example, you might need to register an item with some service, and unregister it before removing 0220 it, and using these two entries will allow that to happen. 0221 0222 You can also handle the output from the installation process, by returning a non-zero value on exiting, and writing 0223 to standard output. If the return value is non-zero, KNewStuff will report this to the user through various ways, 0224 primarily through the error displayer in NewStuff.Page (and associated components), and the KNS3::DownloadDialog. 0225 0226 An example of this is how Plymouth graphical boot themes are handled, by running the `kplymouththemeinstaller` tool with the 0227 appropriate flags set. You can see the file here: [https://invent.kde.org/plasma/plymouth-kcm/-/blob/master/src/plymouth.knsrc] 0228 0229 ### <a id="kpackage-support" />KPackage Support 0230 0231 To make use of the KPackage option described above, in addition to the Uncompress setting above, you should also specify 0232 the type of archive expected by KPackage. While it is possible to deduce this from the package metadata in many situations, 0233 it is not a requirement of the format that this information exists, and we need to have a fallback in the case it is not 0234 available there. As such, you will want to add a `KPackageType` entry to your knsrc file. The following example shows how this 0235 is done for Plasma themes: 0236 0237 [KNewStuff3] 0238 ProvidersUrl=https://autoconfig.kde.org/ocs/providers.xml 0239 Categories=Plasma Theme 0240 StandardResource=tmp 0241 TagFilter=ghns_excluded!=1,plasma##version==5 0242 DownloadTagFilter=plasma##version==5 0243 Uncompress=kpackage 0244 KPackageType=Plasma/Theme 0245 0246 Using KPackage support will automatically enable the removal of dead entries option. You can override this if you 0247 want to, by explicitly adding `RemoveDeadEntries=false` to your knsrc file, though this would likely result in your 0248 knewstuff cache to end up out of sync at some point.