<?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 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>
&lt;xml version="1.0" encoding="UTF-8"?>
&lt;profile xmlns="urn:org-kde-kremotecontrol"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="urn:org-kde-kremotecontrol file:profile.xsd"&gt;

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

&lt;/profile&gt;
                </programlisting>
              </step>

              <step>
                <para>
                  After you have created the profile skeleton it's time to add some action 
                  templates. 
                </para>

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

    &lt;name&gt;My Profile&lt;/name&gt;
    &lt;version&gt;0.1&lt;/version&gt;
    &lt;author&gt;Me&lt;/author&gt;
    &lt;description&gt;Some descriptive information about what the profile does&lt;/description&gt;

    &lt;action id="someUniquId"  repeat="true|false" button="someButton"&gt;
      &lt;name&gt;My Action&lt;/name&gt;
      &lt;description&gt;What this action does&lt;/description&gt;
      &lt;prototype&gt;
        &lt;--  This tag will be explained in the next step--&gt;
      &lt;prototype&gt;
      &lt;ifmulti&gt;ifMultiOption&lt;/ifmulti&gt;
    &lt;/action&gt;
    
&lt;/profile&gt;
                </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>
&lt;?xml version="1.0" encoding="UTF-8"?>
&lt;profile xmlns="urn:org-kde-kremotecontrol"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="urn:org-kde-kremotecontrol file:profile.xsd"&gt;

    &lt;name&gt;My Profile&lt;/name&gt;
    &lt;version&gt;0.1&lt;/version&gt;
    &lt;author&gt;Me&lt;/author&gt;
    &lt;description&gt;Some descriptive information about what the profile does&lt;/description&gt;

    &lt;action id="someUniquId"  repeat="true|false" button="someButton"&gt;
      &lt;name&gt;My Action&lt;/name&gt;
      &lt;description&gt;What this action does&lt;/description&gt;

      &lt;prototype&gt;
        &lt;serviceName&gt;org.example.application&lt;/serviceName&gt;
        &lt;node&gt;Some/Node&lt;/node&gt;
        &lt;function&gt;function&lt;/function&gt;
      &lt;/prototype&gt;

      &lt;ifmulti&gt;ifMultiOption&lt;/ifmulti&gt;
    &lt;/action&gt;

&lt;/profile&gt;
                </programlisting>
                <para>
                <quote>servicename</quote> holds the &DBus; service name for the application, &eg;
                <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>
&lt;?xml version="1.0" encoding="UTF-8"?>
&lt;profile xmlns="urn:org-kde-kremotecontrol"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="urn:org-kde-kremotecontrol file:profile.xsd"&gt;

   &lt;name&gt;My Profile&lt;/name&gt;
    &lt;version&gt;0.1&lt;/version&gt;
    &lt;author&gt;Me&lt;/author&gt;
    &lt;description&gt;Some descriptive information about what the profile does&lt;/description&gt;

    &lt;action id="someUniquId"  repeat="true|false" button="someButton"&gt;
      &lt;name&gt;My Action&lt;/name&gt;
      &lt;description&gt;What this action does&lt;/description&gt;

      &lt;prototype&gt;
        &lt;serviceName&gt;org.example.application&lt;/serviceName&gt;
        &lt;node&gt;SomeNode&lt;/node&gt;
        &lt;function&gt;function&lt;/function&gt;

        &lt;arguments&gt;
          &lt;argument type="QString"&gt;
            &lt;comment&gt;Additional comment&lt;/comment&gt;
            &lt;default&gt;someValue&lt;/default&gt;
          &lt;/argument&gt;
        &lt;/arguments&gt;

      &lt;/prototype&gt;

      &lt;ifmulti&gt;ifMultiOption&lt;/ifmulti&gt;
    &lt;/action&gt;

&lt;/profile&gt;
                  </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>
