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.

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>