# KDE Remote Control Configuration

## Introduction

This module allows you to configure your remote controls. You can assign actions that are executed on button presses. Actions can start applications, control them or execute system commands, such as powering off your computer.

### Requirements

To use &kremotecontrol; you must have set up a compatible backend for remote controls on your computer. Currently there is only a backend for LIRC available. If LIRC is properly set up, the &kremotecontrol; icon in the system tray will light up red . If not, it will be gray and crossed out .

For more information about LIRC, visit their website at http://www.lirc.org.

## Usage

The configuration module consists of two lists. The list on the left shows the available remote controls and their modes. The list on the right displays all configured actions for the current selected remote and mode. KRemoteControl configuration Lists of remotes and configured modes and actions

### Remote Controls and Modes

Each remote control can have a number of different modes. Having multiple modes allows buttons to execute different actions in different situations. Think of it as a TV/Video/Satellite/DVD multi-purpose remote control. Instead of using different remote controls for different applications, you can change the behavior of one remote control to adapt to an application by creating different modes and switching them as needed. Actions defined directly to the remote control are always available, no matter in what mode the remote currently is. Actions defined in a mode are only executed if the remote is currently set to that mode. Each remote control can be only in one mode at a time. It may also be in no mode at all meaning that only always available actions are executed on button presses. You can also define a default mode, which is the mode automatically assigned on startup.

You can add modes to a remote control by selecting the remote and using the + button besides to the list. When creating a mode you need to supply a name for it. Optionally you can assign a button that is used to activate the mode and an icon that is used for notifications for this mode. You can delete modes by selecting them and using the - button. Add mode Adding a new mode

By default, if there are multiple modes with the same assigned button, the button is used to cycle through those modes. This way you can group your modes. For example you could assign a button named Music to cycle through modes for &amarok; and &juk; while a button named Video could cycle through modes for &dragon; or KMplayer. If you rather would like to have a button for cycling though all modes and a second one to reverse-cycling through the modes, you can set this behavior in a remotes preferences by selecting a remote and pressing the edit button. EditRemote Editing a remote

### Actions

After selecting a remote or a mode, you can add actions to it using the + button on the right. There are two different ways how actions can be created. By using a template or by browsing the D-Bus session bus manually. AddAction Adding an action

Creating actions using templates is easier but limited. You can find templates for the most common applications such as &amarok; or the &kde; program launcher and system commands for shutting down your computer. Those templates are collected in profiles that group them into similar task. For example there is a Profile called Power management that contains templates for shutting down or suspending your computer. AddProfileAction Adding an action using a template

Creating actions by browsing the D-Bus lists all currently running applications. You can browse through them and their functions. This requires a basic understanding of how D-Bus works, but you can use more applications and functions than those in the template list. AddDBusAction Adding an action using D-Bus

When adding an action you can tweak a few more options. The first one of them defines if the actions is executed repeatedly when the button on the remote control is being held down. This is a useful behavior for actions like increasing or decreasing volume but may be undesired for actions like toggling play/pause on a media player. The second one defines if the target application should be started if it is not running yet when the button is pressed. For example it would not make sense for actions that should close an application to launch it. The third and last option for actions is to define which instance of an application should receive the action if there are more then on instances running. If you have selected an application that cannot be run multiple times this option is disabled.

AddActionOptions Options for actions

Actions may also be automatically populated using the wizard button. This means that &kremotecontrol; can attempt to match buttons to functions for you. The autopopulate dialog shows all available templates collections with a flag. Depending on the color of the flag your remote control is fully, partially or not supported by that profile. Green means all contained templates can be matched to your remote control, yellow means some of the contained actions match and red means none of the templates can be matched to buttons of your remote control. This doesn't mean that you cannot use those templates. You just have to configure them one by one, setting the desired button by yourself. AutoPopulate Automatically generate actions using templates

Note: If your remote control isn't compatible to any profile you might haven't configured LIRC using namespaces.

## Advanced Information

This chapter will discuss some information which might be interesting for more advanced users or developers. You will learn how to create your own profiles.

### Creating a Profile

#### Introduction

Nearly all &DBus; capable applications can be used with &kremotecontrol; without any further actions. However, to provide user friendly configuration and let the application appear in the autopopulate dialog you might want to create a profile for it.

A profile tells &kremotecontrol; (and the user!) what the various &DBus; calls do. Essentially this is a kind of documentation for &DBus; calls. You don't have to include all &DBus; calls - just the ones that you feel end-users would benefit the most (usually interface adjusting calls rather the information gathering calls).

#### Profile HowTo

1. #### &DBus;

   Make sure the application you want to create the profile for, provides functions on the &DBus; session bus. You can check this by trying to add actions for that application using the manual method in &kremotecontrol;. qdbusviewer, an application which is shipped with your Qt4 installation is also a very good tool to find out about &DBus; capabilities of applications.

2. #### Step by step

   Once you have found the appropriate &DBus; functions you need to describe them in a `appname.profile.xml` document. Here is a quick guide how to create such files:

   1. First create a new file containing the content below. The tag name defines a short descriptive name of the profile. Add a description of the profile in the description tag. Also add your name into the author tag and a version number in the version tag. The version number is important for upgrading your profile. &kremotecontrol; will use the one with the highest number if multiple versions of your profile are found on the system.

          <xml version="1.0" encoding="UTF-8"?>
          <profile xmlns="urn:org-kde-kremotecontrol"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="urn:org-kde-kremotecontrol file:profile.xsd">

              <name>My Profile</name>
              <version>0.1</version>
              <author>Me</author>
              <description>Some descriptive information about what the profile does</description>
              <action>
                  <--  This tag will be explained in the next step-->
              <action>

          </profile>

   2. After you have created the profile skeleton it's time to add some action templates.

          <?xml version="1.0" encoding="UTF-8"?>
          <profile xmlns="urn:org-kde-kremotecontrol"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="urn:org-kde-kremotecontrol file:profile.xsd">

              <name>My Profile</name>
              <version>0.1</version>
              <author>Me</author>
              <description>Some descriptive information about what the profile does</description>

              <action id="someUniquId"  repeat="true|false" button="someButton">
                <name>My Action</name>
                <description>What this action does</description>
                <prototype>
                  <--  This tag will be explained in the next step-->
                <prototype>
                <ifmulti>ifMultiOption</ifmulti>
              </action>

          </profile>

      First define a unique identifier. This will be used by &kremotecontrol; to match existing actions to the template, for example for reading the description. This id must be unique through the whole profile. The button attribute is used for the autopopulate function. Look at the profile.xsd schema file for a complete list of available button names. The repeat attribute tells whether the action should be executed multiple times if the button on the remote is being held pressed. If the application should be started if not running on incoming button presses set autostart to true. The attributes button, repeat and autostart are optional. If repeat and autostart are not defined, they will default to false.

      Add a short name to the name tag and a description using the description tag. The ifmulti property specifies what &kremotecontrol; should do if there are multiple instances running when a button is pressed. You can use the following values for this property: sendtotop (send call to the instance on top of the window stack), sendtobottom (send call to the instance on bottom of the window stack), sendtoall (send to all instances), dontsend (don't send the action to any instance) and unique (This application does not allow multiple instances). If this tag is not defined &kremotecontrol; assumes that the applications cannot be run multiple times, defaulting this tag to unique.

   3. Next define the &DBus; function which should be executed in the prototype tag:

          <?xml version="1.0" encoding="UTF-8"?>
          <profile xmlns="urn:org-kde-kremotecontrol"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="urn:org-kde-kremotecontrol file:profile.xsd">

              <name>My Profile</name>
              <version>0.1</version>
              <author>Me</author>
              <description>Some descriptive information about what the profile does</description>

              <action id="someUniquId"  repeat="true|false" button="someButton">
                <name>My Action</name>
                <description>What this action does</description>

                <prototype>
                  <serviceName>org.example.application</serviceName>
                  <node>Some/Node</node>
                  <function>function</function>
                </prototype>

                <ifmulti>ifMultiOption</ifmulti>
              </action>

          </profile>

      servicename holds the &DBus; service name for the application, ⪚ org.kde.plasma-desktop. node holds the respective &DBus; node such as App. Add the function name without return value and arguments using the function tag. For example toggleDashboard.

   4. If the function has arguments you need to describe each one of those, providing a description for the user, a type and optionally a default value. A list of supported types is can be found in the profile.xsd schema file. The comment tag should contain a nice user friendly description of what the argument is used for. You should also declare a default value for each argument between the default tags. Note that templates containing a button need to supply a default value for all arguments or the autopopulate function will produce broken functions.

          <?xml version="1.0" encoding="UTF-8"?>
          <profile xmlns="urn:org-kde-kremotecontrol"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="urn:org-kde-kremotecontrol file:profile.xsd">

             <name>My Profile</name>
              <version>0.1</version>
              <author>Me</author>
              <description>Some descriptive information about what the profile does</description>

              <action id="someUniquId"  repeat="true|false" button="someButton">
                <name>My Action</name>
                <description>What this action does</description>

                <prototype>
                  <serviceName>org.example.application</serviceName>
                  <node>SomeNode</node>
                  <function>function</function>

                  <arguments>
                    <argument type="QString">
                      <comment>Additional comment</comment>
                      <default>someValue</default>
                    </argument>
                  </arguments>

                </prototype>

                <ifmulti>ifMultiOption</ifmulti>
              </action>

          </profile>

#### Installation

To test and use the profile you need to copy it into `$(kde_datadir)/profiles` and restart &kremotecontrol;.

If you would like to contribute the profile to the &kde; SC please send it to the kdeutils team at kde-utils-devel@kde.org.