You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
146 lines
5.4 KiB
146 lines
5.4 KiB
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.
|