diff options
Diffstat (limited to 'tdelirc/README.profile-creation')
| -rw-r--r-- | tdelirc/README.profile-creation | 145 |
1 files changed, 145 insertions, 0 deletions
diff --git a/tdelirc/README.profile-creation b/tdelirc/README.profile-creation new file mode 100644 index 0000000..80ec429 --- /dev/null +++ b/tdelirc/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 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. |