Warning, /frameworks/knewstuff/README.md is written in an unsupported language. File is not indexed.

0001 # KNewStuff
0003 Framework for downloading and sharing additional application data
0005 ## Introduction
0007 The KNewStuff library implements collaborative data sharing for
0008 applications. It uses libattica to support the Open Collaboration Services
0009 specification.
0012 ## Usage
0014 There are three parts to KNewStuff:
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.
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:
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):
0034     find_package(KF5 COMPONENTS NewStuffCore NewStuff NewStuffQuick)
0036 Or use the old-fashioned syntax
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
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:
0046     import org.kde.newstuff 1.0
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:
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)
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.
0066 ## Which module should you use?
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.
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.
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.
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).
0083 ## Configuration Files
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.
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).
0094 As an example, the file might look like this for wallpapers found on the KDE Store:
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
0103 ### Name
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`.
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).
0113 ### ProvidersUrl
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`.
0123 ### Categories
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().
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.
0135 ### XdgTargetDir
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.
0141 This is what `QStandardPaths::writableLocation(QStandardPaths::GenericDataLocation) + QLatin1Char('/') + name` will return.
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):
0146 * `StandardResource`: Not available in KF5, use XdgTargetDir instead.
0147 * `TargetDir`: Since KF5, this is equivalent to XdgTargetDir.
0149 #### InstallPath
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`.
0155 ### Uncompress
0157 Uncompress can be one of: `always`, `never`, `archive`, `surdir`, or `kpackage`:
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.
0166 ### Entry and Download Item Tag Filter
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:
0172     TagFilter=ghns_excluded!=1,data##mimetype==application/cbr+zip,data##mimetype==application/cbr+rar
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.
0179 ### Automatic Dead Entry Removal
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.
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.
0190 ### Adoption Command
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.
0197 #### Use Label
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".
0205 ### Upload Assistance
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.
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).
0216 ### Installation Control
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.
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.
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]
0229 ### <a id="kpackage-support" />KPackage Support
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:
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
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.