<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
<!ENTITY kremotecontrol "<application>KRemoteControl</application>">
<!ENTITY % English "INCLUDE" > <!-- change language only here -->
<!ENTITY % addindex "IGNORE">
]>
<book id="kremotecontrol" lang="&language;">
<bookinfo>
<title>KDE Remote Control Configuration</title>
<authorgroup>
<author>
<firstname>Michael</firstname>
<surname>Zanetti</surname>
<affiliation>
<address><email>michael_zanetti@gmx.net</email></address>
</affiliation>
</author>
<!-- TRANS:ROLES_OF_TRANSLATORS -->
</authorgroup>
<date>2010-03-05</date>
<releaseinfo>1.0</releaseinfo>
<copyright>
<year>2010</year>
<holder>Michael Zanetti</holder>
</copyright>
<abstract>
<para>
&kremotecontrol; configuration: The infrastructure for the &kde;'s
Remote Control functionality.
</para>
</abstract>
<keywordset>
<keyword>KRemoteControl</keyword>
<keyword>kcm_remotecontrol</keyword>
<keyword>Remote Control</keyword>
</keywordset>
</bookinfo>
<chapter id="introduction">
<title>Introduction</title>
<para>
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.
</para>
<sect1 id="requirements">
<title>Requirements</title>
<para>
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
<inlinemediaobject>
<imageobject>
<imagedata fileref="irkick.png" format="PNG" />
</imageobject>
</inlinemediaobject>.
If not, it will be gray and crossed out
<inlinemediaobject>
<imageobject>
<imagedata fileref="irkickoff.png" format="PNG"/>
</imageobject>
</inlinemediaobject>.
</para>
<para>
For more information about LIRC, visit their website at http://www.lirc.org.
</para>
</sect1>
</chapter>
<chapter id="usage">
<title>Usage</title>
<para>
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.
<screenshot>
<screeninfo>KRemoteControl configuration</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="kcmremotecontrol.png" format="PNG"/>
</imageobject>
<textobject>
<phrase>Lists of remotes and configured modes and actions</phrase>
</textobject>
</mediaobject>
</screenshot>
</para>
<sect1 id="modes">
<title>Remote Controls and Modes</title>
<para>
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.
</para>
<para>
You can add modes to a remote control by selecting the remote and using the
<guibutton>+</guibutton> 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 <guibutton>-</guibutton> button.
<screenshot>
<screeninfo>Add mode</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="AddMode.png" format="PNG"/>
</imageobject>
<textobject>
<phrase>Adding a new mode</phrase>
</textobject>
</mediaobject>
</screenshot>
</para>
<para>
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 <quote>Music</quote> to cycle through modes
for &amarok; and &juk; while a button named <quote>Video</quote> 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.
<screenshot>
<screeninfo>EditRemote</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="EditMasterMode.png" format="PNG"/>
</imageobject>
<textobject>
<phrase>Editing a remote</phrase>
</textobject>
</mediaobject>
</screenshot>
</para>
</sect1>
<sect1 id="actions">
<title>Actions</title>
<para>
After selecting a remote or a mode, you can add actions to it using the
<guibutton>+</guibutton> 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.
<screenshot>
<screeninfo>AddAction</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="AddAction.png" format="PNG"/>
</imageobject>
<textobject>
<phrase>Adding an action</phrase>
</textobject>
</mediaobject>
</screenshot>
</para>
<para>
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
<quote>Power management</quote> that contains templates for shutting down or
suspending your computer.
<screenshot>
<screeninfo>AddProfileAction</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="AddProfileAction.png" format="PNG"/>
</imageobject>
<textobject>
<phrase>Adding an action using a template</phrase>
</textobject>
</mediaobject>
</screenshot>
</para>
<para>
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.
<screenshot>
<screeninfo>AddDBusAction</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="AddDBusAction.png" format="PNG"/>
</imageobject>
<textobject>
<phrase>Adding an action using D-Bus</phrase>
</textobject>
</mediaobject>
</screenshot>
</para>
<para>
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.
</para>
<para>
<screenshot>
<screeninfo>AddActionOptions</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="AddActionOptions.png" format="PNG"/>
</imageobject>
<textobject>
<phrase>Options for actions</phrase>
</textobject>
</mediaobject>
</screenshot>
</para>
<para>
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.
<screenshot>
<screeninfo>AutoPopulate</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="AutoPopulate.png" format="PNG"/>
</imageobject>
<textobject>
<phrase>Automatically generate actions using templates</phrase>
</textobject>
</mediaobject>
</screenshot>
</para>
<para>
<emphasis role="strong">Note:</emphasis> If your remote control isn't compatible to any
profile you might haven't configured LIRC using namespaces.
</para>
</sect1>
</chapter>
<chapter id="advancedInformation">
<title>Advanced Information</title>
<para>
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.
</para>
<sect1 id="profileCreation">
<title>Creating a Profile</title>
<sect2>
<title>Introduction</title>
<para>
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.
</para>
<para>
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 <quote>interface adjusting</quote> calls rather the <quote>information
gathering</quote> calls).
</para>
</sect2>
<sect2>
<title>Profile HowTo</title>
<procedure>
<step>
<title>&DBus;</title>
<para>
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;. <quote>qdbusviewer</quote>,
an application which is shipped with your Qt4 installation is also a very good tool
to find out about &DBus; capabilities of applications.
</para>
</step>
<step>
<title>Step by step</title>
<para>
Once you have found the appropriate &DBus; functions you need to describe them in
a <filename>appname.profile.xml</filename> document. Here is a quick guide how to
create such files:
</para>
<substeps>
<step>
<para>
First create a new file containing the content below. The tag
<quote>name</quote> defines a short descriptive name of the profile. Add a
description of the profile in the <quote>description</quote> tag. Also add
your name into the <quote>author</quote> tag and a version number in the
<quote>version</quote> 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.
</para>
<programlisting>
<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>
</programlisting>
</step>
<step>
<para>
After you have created the profile skeleton it's time to add some action
templates.
</para>
<programlisting>
<?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>
</programlisting>
<para>
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 <quote>button</quote>
attribute is used for the autopopulate function. Look at the <quote>profile.xsd</quote>
schema file for a complete list of available button names. The <quote>repeat</quote>
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 <quote>autostart</quote> to <quote>true</quote>.
The attributes <quote>button</quote>, <quote>repeat</quote> and
<quote>autostart</quote> are optional. If <quote>repeat</quote> and
<quote>autostart</quote> are not defined, they will default to <quote>false</quote>.
</para>
<para>
Add a short name to the <quote>name</quote> tag and a description using the
<quote>description</quote> tag. The <quote>ifmulti</quote> 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:
<quote>sendtotop</quote> (send call to the instance on top of the window stack),
<quote>sendtobottom</quote> (send call to the instance on bottom of the window stack),
<quote>sendtoall</quote> (send to all instances),
<quote>dontsend</quote> (don't send the action to any instance) and
<quote>unique</quote> (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 <quote>unique</quote>.
</para>
</step>
<step>
<para>
Next define the &DBus; function which should be executed in the
<quote>prototype</quote> tag:
</para>
<programlisting>
<?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>
</programlisting>
<para>
<quote>servicename</quote> holds the &DBus; service name for the application, ⪚
<quote>org.kde.plasma-desktop</quote>. <quote>node</quote> holds the respective
&DBus; node such as <quote>App</quote>. Add the function name without return value
and arguments using the <quote>function</quote> tag. For example
<quote>toggleDashboard</quote>.
</para>
</step>
<step>
<para>
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 <quote>profile.xsd</quote> schema file.
The <quote>comment</quote> 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 <quote>default</quote> tags. Note that templates containing
a button need to supply a default value for all arguments or the autopopulate
function will produce broken functions.
</para>
<programlisting>
<?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>
</programlisting>
</step>
</substeps>
</step>
</procedure>
</sect2>
<sect2>
<title>Installation</title>
<para>
To test and use the profile you need to copy it into
<filename>$(kde_datadir)/profiles</filename> and restart &kremotecontrol;.
</para>
<para>
If you would like to contribute the profile to the &kde; SC please send it
to the kdeutils team at <email>kde-utils-devel@kde.org</email>.
</para>
</sect2>
</sect1>
</chapter>
</book>
distrib
>
Mageia
>
6
>
x86_64
>
media
>
core-release
>
by-pkgid
>
b3b7c4727750cedc2913d83239f5941c
>
files
>
11
