# &kde; Infrared Remote Control Configuration

## Introduction

### Requirements

To use the &kdelirc; framework you must have set up LIRC on your computer. If it is properly set up, the &kdelirc; icon in the system tray will light up red . If not, it will be grey and crossed out .

For more information about LIRC and how to configure it, visit their website at http://www.lirc.org.

Note: When configuring LIRC it is recommended to make use of button-namespaces.

## Usage

There are three tabs giving you several sections of configuration and additional information. The first tab, called Controller Functions is used to configure modes and actions for all available remotes. The tab named Profiles Overview contains details about the available profiles. The Available Remotes tab shows you additional information about your remote controls. Selecting a remote gives you an overview about their buttons.

### Controller Functions

#### 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 behaviour 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.

The list on the left contains all remote controls detected on your system. Modes may be added and removed by selecting the desired remote control or mode and using the buttons directly below the list. The Edit button allows you to change existing modes.

#### Assigning actions to buttons

&kdelirc; knows two different types of actions. Mode switches and actions to be executed. Mode switches allow to switch the current remote to a different mode, while regular actions allow executing commands over &DBus;. When defining a new executable action you have two options. One is to use a template while the other requires to manually specify all possible options. Templates for actions are called profiles. While using profiles to create actions is more easy and straight forward it is not possible to access all functions with profiles. More advanced actions may be configured by manually selecting functions and their parameters.

To add an action use the Add... button on the lower right side. A wizard will show up asking you what type of action should be created. The first option will create an action based on a profile. The second option lets you create the entire action manually. Remember that the application you would like to control must be running at the time you configure the action or it won't show up in the list of available applications. The third option allows to create a mode switch action. Select the desired type of action and follow the steps through the wizard.

Actions may also be automatically populated using the Autopopulate... button. This means that &kdelirc; can attempt to match buttons to functions for you. The autopopulate dialog shows all available profiles with a flag. Depending on the color of the flag your remote control is fully, partially or not supported by that profile. Green means full support, yellow partial and red none.

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

### Profiles Overview

The Profiles Overview tab gives you information about the available profiles. By selecting a profile you can see detailed informations such as the author's details and a list of all defined actions. Each action entry contains information about additional settings, a comment and the identifier of the button to be used by the autopopulate function.

If you would like to contribute application profiles see the advanced information chapter.

### Available Remotes

This tab gives you detailed information on your remote controls. You can check here if your remote controls were recognized correctly by the system.

## 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.

### Profile Creation

#### Introduction

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

A profile tells &kdelirc; (and the user!) what the various &DBus; calls do. Essentially this is a kind of documentation for the &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).

#### Creation

1. #### &DBus;

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

2. #### Create a profile

   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 following content. Replace myapp with the executable name of the application and My Application with a descriptive application name.

          <?xml version="1.0" ?>
          <!DOCTYPE profile SYSTEM "profile.dtd">

            <profile id="myapp" servicename="My Application">
            </profile>

   2. Inside the profile tag add name and author information. The instances tag tells &kdelirc; whether the application can be executed multiple times or not. Set unique to 0 if you can start the application multiple times (it defaults to 1). The ifmulti property specifies what &kdelirc; should do if there are multiple instances running when a button is pressed. The options are dontsend (do nothing if >1 instance), sendtoone (send call to one arbitrarily chosen instance) and sendtoall (send to all instances). The default is dontsend, however, sendtoone may be the most useful in many circumstances.

          <?xml version="1.0" ?>
          <!DOCTYPE profile SYSTEM "profile.dtd">

            <profile id="myapp" servicename="My Application">
              <name>My Application</name>
              <author>Me</author>
              <instances unique="0" ifmulti="sendtoone"/>
            </profile>

   3. Populate the profile with action tags. Each action tag should contain the &DBus; object name and the function prototype.

      &kdelirc; needs some additional attributes to know how to handle an action. The button tag is used for the autopopulate function. See the solid API docs for a complete list of available button names. The repeat tag tells whether the action should be executed multiple times if the button on the remote is being held pressed (0 = No, 1 = Yes). The autostart tag defines whether the application should be started if not already running.

          <?xml version="1.0" ?>
          <!DOCTYPE profile SYSTEM "profile.dtd">

            <profile id="myapp" servicename="My Application">
              <name>My Application</name>
              <author>Me</author>
              <instances unique="0" ifmulti="sendtoone"/>
              <action objid="MyApp" prototype="void showint(short int)"
                button="Menu" repeat="0" autostart="0">
              </action>
            </profile>

   4. Add a name and a comment to the action. This is shown in the &kdelirc; user interface.

          <?xml version="1.0" ?>
          <!DOCTYPE profile SYSTEM "profile.dtd">

            <profile id="myapp" servicename="My Application">
              <name>My Application</name>
              <author>Me</author>
              <instances unique="0" ifmulti="sendtoone"/>
              <action objid="MyApp" prototype="void showints(short int)"
                  button="Menu" repeat="0" autostart="0">
                <name>Show Integers</name>
                <comment>Shows a configurable integer</comment>
              </action>
            </profile>

   5. Describe each argument with a comment and type attribute. A list of valid types can be found in the profiles description file. You should declare a default value for each argument between the default tags:

          <?xml version="1.0" ?>
          <!DOCTYPE profile SYSTEM "profile.dtd">

            <profile id="myapp" servicename="My Application">
              <name>My Application</name>
              <author>Me</author>
              <instances unique="0" ifmulti="sendtoone"/>
              <action objid="MyApp" prototype="void showints(short int)"
                  button="Menu" repeat="0" autostart="0">
                <name>Show Integers</name>
                <comment>Shows a configurable integer</comment>
                <argument type="int">
                  <default>5</default>
                  <comment>The integer to be shown</comment>
                </argument>
              </action>
            </profile>

#### Installation

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

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.