How to give your KDE application IR support under KDE.
======================================================

by Gav Wood, 2003.

Introduction
------------

All DBus-using applications under KDE have basic lirc support, since KDELirc has
the ability to interface any button to any DBus call. However, to give your
application the real professional touch when using it with KDELirc, I recommend
you 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 would benefit end-users
the most (usually "interface adjusting" calls rather the "information gathering"
calls).


Method
------

1. DBus

Make sure the application you want to profile provides method calls over dbus.
You can find this out by using the qdbusviewer application which is shipped with your 
qt4 installation. For your own application please take a look at the developer howtos
and kde/qt documentation how to implement this.

2. Create a profile

Having coded the necessary DBus functionality into your application, the only
other thing to do is describe how it works to the user. This is done by means of
a .profile.xml document, examples of which may be found in the kdelirc/profiles
directory. A quick guide is given here:

a) First create top level "profile" tags with the DBus application id and KDE
service name (found in the .desktop file) as attributes of them:

	<?xml version="1.0" ?>
	<!DOCTYPE profile SYSTEM "profile.dtd">
	<profile id="myapp" servicename="My Application">
	</profile>

b) Inside populate with name and author information. If your application is not a
KUniqueApplication, you **must** declare this with an "instances" tag, giving the
attribute "unique" a value of "0" (it defaults to "1", a KUniqueApplication). You
may optionally describe the default behavior KDELirc should take should there be
more than one instance of the application, with the attribute "ifmulti" which may
take one of "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>

c) Populate the profile with action tags, for each DBus action you want to be
available to the user. Each action tag should have DBus object name and function
prototype.
   Several optional attributes to specify are the key-class. There are
several defined; see the DTD files for a current list. The other options, repeat
and autostart are boolean specificers to tell whether the action should repeat
or automatically start the program by default.

	<?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)"
				class="number" repeat="0" autostart="0">
		</action>
	</profile>

d) Give the action a name and comment:

	<?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)"
				class="number" repeat="0" autostart="0">
			<name>Show Integers</name>
			<comment>Shows a configurable integer</comment>
		</action>
	</profile>

e) Describe each argument with a comment and type attribute. Valid types are
found in the profile.dtd file. If you cant find the exact type, just use one
that is silently castable. You should declare a default value 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)"
				class="number" 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>

If you want to to provide the action for the autopopulate function you have to define the button attribute,
The button attribute you specify the solid button name which is used to execute the action.
To get a list  of all available button names please look at
http://api.kde.org/4.x-api/kdebase-workspace-apidocs/libs/solid/html/classSolid_1_1Control_1_1RemoteControlButton.html

When you have created your profile.xml file, put in your project's main source
tree.

3. Profile installation

There is a data directory in KDE reserved for profiles such as these; it's path
is "$(kde_datadir)/profiles". These extra lines must therefore be added to your
Makefile.am in the directory of your profile.xml:

	profiledata_DATA = [YOURAPPHERE].profile.xml
	profiledatadir = $(kde_datadir)/profiles
	EXTRA_DIST = $(profiledata_DATA)

(replace [YOURAPPHERE] with your application name---the prefix to your
profile.xml file.)


4. Finished

That's it you're done! Your KDE application is now fully IR enabled.
