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

 # Purpose
 
 Offers available actions for a specific purpose
 
 ## Introduction
 
 This framework offers the possibility to create integrate services and actions
 on any application without having to implement them specifically. Purpose will
 offer them mechanisms to list the different alternatives to execute given the
 requested action type and will facilitate components so that all the plugins
 can receive all the information they need.
 
 ## Usage
 
 There's 2 main ways of using Purpose: from C++ and QML/QtQuick.
 
 To import it from QML, import
 
     import org.kde.purpose 1.0
 
 It offers different ways of integrating the actions in an application. For full
 control on the procedure, we can use:
 * *AlternativesModel* for listing the different possibilities
 * *JobView* for displaying a job's status, including configuration
 
 Furthermore, there's the *AlternativesView* component that will integrate all the
 process defined below for convenience.
 
 If you want to import in the C++ application, you can import it using CMake by
 calling:
 
     find_package(KF5Purpose)
 
 Or its QMake counterpart. Then you'll have available the Purpose library if it
 needs to be done specifically and PurposeWidgets for convenience.
 
 To integrate on the UI, QtQuick will still be used, as the configuration files
 provided by the plugins are written in QML. The recommended way to integrate
 on a QtWidgets interface is by using the *Purpose::Menu* class that will allow
 us to place the integration wherever pleases us. This class will offer us
 a pointer to the used *Purpose::AlternativesModel* so that we can specify what kind of
 services we're interested in.
 
 ## Plugins
 
 ### The plugin configuration
 
 There will be 2 files specifying the behavior of a plugin:
 * The `*PluginType.json` files.
 * The plugin metadata JSON file.
 
 The plugin type will be identified by the file name. It will specify:
 * `X-Purpose-InboundArguments` defines the arguments the application must provide.
 * `X-Purpose-OutboundArguments` defines the arguments the plugin must provide by
 the end of the execution.
 
 In the plugin metadata we will define:
 * `X-Purpose-PluginTypes` defines the purposes tackled by the plugin
 * `X-Purpose-Constraints` defines the conditions that make plugin is useful, given the
 inboundArguments. These are the currently supported constraints
     * mimeType: for example `mimeType:video/*`. Useful to specify which kind of files
     the plugin is interested in.
     * exec: for example `exec:kate`. Can be used to show the plugin only if an executable is
     present in the `$PATH` directories.
     * application: for example `application:org.kde.okular.desktop`. Checks
     that the specified file is present in the `$XDG_DATA_DIRS/applications`
     directories of the system.
     * dbus: for example `dbus:org.kde.kdeconnect`. Will only offer the plugin if
     a certain dbus service is running on the system.
     * `[]`: for example `['exec:bash', 'exec:zsh']`. an array of constraints
     can be used to restrict to either of the conditions instead of all of them.
 * `X-Purpose-Configuration` provides a list of extra arguments that the plugin will need.
 Ideally everything should be in the plugin type but sometimes we can only wish. This allows
 the opportunity to the application to let the user add the missing data.
 
 ### Plugin types
 The application says what it wants to do, Purpose finds the correct plugins. This
 is how we balance decoupling of implementation but keep on top of what the framework
 is supposed to do.
 
 An example of such files is the `ExportPluginType.json`:
 ```json
 {
     "KPlugin": {
         "Icon": "edit-paste",
         "Name": "Upload..."
     },
     "X-Purpose-InboundArguments": [ "urls", "mimeType" ],
     "X-Purpose-OutboundArguments": [ "url" ]
 }
 ```
 
 As previously discussed, here we can define the generic tasks that the different
 plugins will implement on top, having the inbound arguments as a given and the
 outbound as a requirement.
 
 Examples of such plugin types are (hypothetically, not all implemented yet):
 * Share: where you can get the different services to share
 * GetImage that would list your scanner, camera and also some web services.
 * AddContact that would let you add a contact on your address book or
 in whichever plugin is offered.
 
 ### Plugin creation
 
 There's two approaches to plugin implementation: native plugins and separate
 processes.
 
 #### Native
 To implement a Qt-based plugin, it will be required to implement a
 `Purpose::PluginBase` class, that acts as a factory for its `Purpose::Job`
 instances.
 
 These will be the jobs in charge of performing the action the plugin is meant to
 do.
 
 Furthermore, a `pluginname_config.qml` will be provided for extra Configuration,
 if required.
 
 These plugins can be optionally be executed in-process.
 
 #### Separate Process
 Sometimes executing some actions through Qt code can require some extra work.
 For those cases, it's possible to implement the plugin in a separate process.
 It will require some extra work when it comes to implementing the feedback
 process with the main process but it allows to run plugins in any imaginable
 technologies.
 
 The file structure for these plugins is the one of defined by [KPackage](https://api.kde.org/frameworks-api/frameworks5-apidocs/kpackage/html/index.html)
 which allows to package and distributethe plugins in an archive.
 
 To that end, we will need to provide:
 * A `manifest.json` file, that will define the plugin description, capabilities
 and requirements.
 * A `code/main*` file that will be executed when the plugin action needs happen.
 * A `config/config.qml` file that will be in charge of requesting the necessary
 information to the user.
 
 ### Disallowing plugins
 It is possible to globally disable certain plugins through configuration file called
 `purposerc` in /etc/xdg (applies to all users) or in ~/.config (applies to current
 user).
 
 The disabled plugins are specified as a comma-separated list in the `disabled` key
 in the `plugins` group.
 
 ```
 [plugins]
 # Disable KDE Connect and Imgur sharing plugins
 disabled=kdeconnectplugin,imgurplugin
 ```