How to give your LIRC remote control KDELIRC functionality
==========================================================

by Gav Wood, 2003.

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

All LIRC-understandable remote controls automatically function in KDELirc.
However, to get the advanced (really cool) KDELirc stuff you'll need to create a
remote.xml file for your remote control. The files are simple and easy to create
so don't be put off.

The function of the remote.xml file is to describe what the remote controls'
buttons do in a general manner and to provide free-form text names for them,
since LIRC only allows non-spaces, non-symbolic charecters in the remote control
definition files.

When you're finished your remote.xml, you might want to send it to me
(gav at kde dot org) for inclusion in the distribution of KDELirc. It may soon
be possible to distribute the remote.xml files along with the lircd.conf files.

Method
------

a) Start with the basic template and define the LIRC ID of the remote control.
The LIRC ID is most important, and must be the identifier (look for the line
"name <...>" after the "begin remote" line). put the text after "name" into "id"
attribute of the "remote" tag in the "lircd.conf" file ("/etc/lircd.conf").
   In addition to this, fill in the author and name tags with your name and the
"nice" name of the remote control. Any extra information you may wish to give it
(such as alternate names, multimedia bundles/system is comes with etc) may be
enclosed between optional information tags:

	<?xml version="1.0" ?>
	<!DOCTYPE remote SYSTEM "remote.dtd">

	<remote id="myremote">
		<name>My Remote Control</name>
		<author>Me</author>
		<information>As bundled with ACME LinTV</information>
	</remote>

This would compliment a "lircd.conf" file:

	begin remote
	  name myremote
	  ...
	end remote

b) With the hard work out of the way, just start going though each button on the
remote control. For each button, make sure the "id" attribute is the same as in
the lircd.conf file.
   For each (common) button, you might also want to specify the class, which will
help KDELirc match it to any application's action. For a list of all button
classes, look in the remote.dtd file which comes with KDELirc. If the class type
is one which encompasses many buttons, for example "number", then you should also
specify which number it is in the parameter attribute. Currently, this only
actually applies to "number" - all other classes are simple and do not require a
parameter attribute.
   Note: If no "class" is given, it will default to the "id". In the unlikely
case that this is not what you want, simply define it to be null (class="").

	<?xml version="1.0" ?>
	<!DOCTYPE remote SYSTEM "remote.dtd">

	<remote id="myremote">
		<name>My Remote Control</name>
		<author>Me</author>
		<button id="num0" class="number" parameter="0">
		</button>
		<button id="rec" class="record">
		</button>
	</remote>

This would compliment a "lircd.conf" file:

	begin remote
	  name myremote
	  ...
	  begin raw_codes
	    name num0
	    ...
	    name rec
	    ...
	  end raw_codes
	end remote

c) The last thing to define in each of your buttons is the "nice" name. This may
be descriptive and use spaces, symbols and mixed case text, in a similar fashion
to the remote control's name. There is no need to copy the remote control's label
verbatim. If necessary expand the description to provide a readable, aethetically
pleasing label e.g. you should name the "CC" button "Closed Captions" or the "Rec"
button "Record".

	<?xml version="1.0" ?>
	<!DOCTYPE remote SYSTEM "remote.dtd">

	<remote id="myremote">
		<name>My Remote Control</name>
		<author>Me</author>
		<button id="num0" class="number" parameter="0">
			<name>0</name>
		</button>
		<button id="rec" class="record">
			<name>Record</name>
		</button>
	</remote>

   Note: The name of a button will automatically default to its "id", so you can
save yourself some time and effort with buttons which share the same name and id
by changing

		<button id="num0" class="number" parameter="0">
			<name>0</name>
		</button>

to the far less cluttered and simpler:

		<button id="num0" class="number" parameter="0"/>

That's it - just save it as <id>.remote.xml, where <id> is the ID of the remote
control (*not* its name but the LIRC id!) and copy it to your KDE remotes data
directory (~/.trinity/share/apps/remotes).

   You'll probably need to restart control center before the remote definition
is recognised.

Gav Wood <gav at kde dot org>