From 2bda8f7717adf28da4af0d34fb82f63d2868c31d Mon Sep 17 00:00:00 2001 From: toma Date: Wed, 25 Nov 2009 17:56:58 +0000 Subject: Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features. BUG:215923 git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdeutils@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da --- kdelirc/README.profile-creation | 145 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 145 insertions(+) create mode 100644 kdelirc/README.profile-creation (limited to 'kdelirc/README.profile-creation') diff --git a/kdelirc/README.profile-creation b/kdelirc/README.profile-creation new file mode 100644 index 0000000..95d9e78 --- /dev/null +++ b/kdelirc/README.profile-creation @@ -0,0 +1,145 @@ +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 KDELirc has +the ability to interface any button to any DCOP 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 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 kdelirc/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: + + + + + + +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. + + + + + My Application + Me + + + +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. + + + + + My Application + Me + + + + + +d) Give the action a name and comment: + + + + + My Application + Me + + + Show Integers + Shows a configurable integer + + + +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: + + + + + My Application + Me + + + Show Integers + Shows a configurable integer + + 5 + The integer to be shown + + + + +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. -- cgit v1.2.1