Rename kdessh -> tdessh and kdelirc -> tdelirc.

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.