tdeutils/tdelirc/README.profile-creation

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

by Gav Wood, 2003.

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

All DCOP-using applications under KDE have basic lirc support, since TDELirc has
the ability to interface any button to any DCOP call. However, to give your
application the real professional touch when using it with TDELirc, I recommend
you create a profile for it.

A profile tells TDELirc (and the user!) what the various DCOP calls do.
Essentially this is a kind of documentation for the DCOP calls. You don't have
to include all DCOP calls - just the ones that you feel would benefit end-users
the most (usually "interface adjusting" calls rather the "information gathering"
calls).


Method
------

1. DCOP

The first thing to do is to give your application DCOP functionality. This is
*very* easy and essentially amounts to adding a declaration to each object you
want to give DCOP accessibility and adding an entry to your Makefile. I wont go
into it here as the KDE documentation already provides a suitable resource for
such information.

Ensure you provide a full accessibility to your application's interface by DCOP,
and especially in the case of IR-interfacing, try not to have functions with too
many parameters, or with exotic types (stick to ints and QStrings where
necessary).

2. Create a profile

Having coded the necessary DCOP 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 tdelirc/profiles
directory. A quick guide is given here:

a) First create top level "profile" tags with the DCOP 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 TDELirc 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 DCOP action you want to be
available to the user. Each action tag should have DCOP object name and function
prototype.
   Several optional attrubutes to specify are the key-class (an identifier to
act as an abstract binding between remote controls and applications). 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>

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.