Chapter 3. 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 D-Bus 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 D-Bus calls do. Essentially this is a kind of documentation for D-Bus calls. You don't have to include all D-Bus 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. D-Bus

    Make sure the application you want to create the profile for, provides functions on the D-Bus 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 D-Bus capabilities of applications.

  2. Step by step

    Once you have found the appropriate D-Bus 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 D-Bus 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 D-Bus service name for the application, e.g. org.kde.plasma-desktop. node holds the respective D-Bus 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 .