Better support for option cleanup in python package

[adesklets.git] / doc / adesklets_en.texi

\input texinfo   @c -*-texinfo-*-
@comment %**start of header
@setfilename adesklets_en.info
@include version_en.texi
@settitle adesklets @value{VERSION}
@syncodeindex pg cp
@comment %**end of header
@copying
This manual is for adesklets (version @value{VERSION}, @value{UPDATED}).

Copyright @copyright{} 2004, 2005 Sylvain Fourmanoit
@email{syfou@@users.sourceforge.net}.

Various corrections and updates by Mike Pirnat
@email{exilejedi@@users.sourceforge.net}.

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU General Public License, Version 2 or
any later version published by the Free Software Foundation. 
A copy of the license is included in the appendix entitled 
``Copying This Manual''.

@end quotation
@end copying

@c Define useful weblink macro
@macro weblink{link}
@html
<a href="
@end html
\link\
@html
">\link\</a>
@end html
@end macro

@c Define weblink2 macro: a variation on the previous one
@macro weblink2{desk,link}
@html
<a href="\link\">
@end html
\desk\
@html
</a>
@end html
@end macro

@dircategory Graphics
@direntry
* adesklets: (adesklets).      Another desklets container.
@end direntry

@titlepage
@title adesklets
@subtitle for version @value{VERSION}, @value{UPDATED}
@author Sylvain Fourmanoit (@email{syfou@@users.sourceforge.net})
@author Mike Pirnat (@email{exilejedi@@users.sourceforge.net})
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top
@top adesklets

@ifnothtml
Follow those links for documentation in other languages
(@xref{Top,French version, About adesklets, adesklets_fr,}.).
@end ifnothtml
@ifhtml
@weblink2{[French version],../fr/index.html}
@end ifhtml

@insertcopying
@end ifnottex

@menu
* About adesklets::
* What's new?::
* Installing adesklets::
* Using adesklets::
* Programming adesklets::
* Extending adesklets::
* Help wanted!::
* Frequently asked questions::
@ifhtml
* Python package documentation::
@end ifhtml
* Imlib2 documentation::
* Packaging GNU Makefile for desklets::
* Submitting a desklet::
* Copying This Manual::
* Open PGP Public Key::
* Index::
@end menu

@noindent The current version of this document can be found online at
@weblink{http://adesklets.sf.net/}.

@noindent Screenshots, source tarballs, etc. can also be found on
the project home page: @weblink{http://sf.net/projects/adesklets/}.

@node About adesklets
@chapter What is adesklets?

@section Short answer

@command{adesklets} is an interactive
@weblink2{Imlib2,http://www.enlightenment.org/pages/imlib2.html} console
for the X Window System. It provides scripted languages with a clean and 
simple way to write great looking, mildly interactive desktop integrated
graphic applets (aka ``desklets'').

It can also be used as a command line oriented graphic editor, a bit similar
to @weblink2{ImageMagick,http://www.imagemagick.org/}, but with different
functionality.

@section Long answer

@command{adesklets} stands for ``another desklets [container]''. It was
written as an alternative to other programs such as:

@enumerate
@item
gDesklets (@weblink{http://gdesklets.gnomedesktop.org/})
@item
SuperKaramba (@weblink{http://netdragon.sourceforge.net/}).
@item
GKrellM (@weblink{http://www.gkrellm.net/})
@end enumerate

Since this is 'a'desklets, others still have plenty of space to start similar
projets, from 'b'desklets to 'z', excluding 'g', which is already taken.

Seriously though, all those packages are nice. Nevertheless, the first two
have very heavy requirements in terms of library dependencies; basically,
gDesklets still requires a fair part of the GNOME environment to be installed 
(plus specialized libraries such as gnome-python@footnote{A report on this has 
been produced; you may find it online in PDF format at 
@weblink{http://adesklets.sf.net/verbatim/gdesklets.pdf}.}), while 
SuperKaramba needs almost all of the KDE libraries and base environment.
This also reflects on performance for the task at hand@footnote{Of course, this
is only the author's opinion--and both applications are making big progress on
resource efficiency from version to version.}. On the other hand, while GKrellM
is significantly lighter (it still depends on GTK+ though), it does not deliver
the same experience in terms of ``eye-candiness'' (to the author's taste, of
course) or ``scriptability'' than the other two.

Thus, @command{adesklets} was born. It provides:

@itemize
@item
a minimal framework for X Window desklets seamlessly integrated into the
desktop, with an easy to use central management for starting, positioning 
and stopping them.
@item
a generic, rich and easy to use drawing API similar to gDesklets and
SuperKaramba regarding its high visual quality, thanks to the Imlib2 library.
@item
very limited library dependencies: uses the very good (and lightning fast)
Imlib2 library for all graphic-related operations. No window toolkit used
whatsoever; the program relies directly on xlib.
@item
a light, robust and small interpreter potentially usable with all sorts of
scripting languages thanks to a clean, limited and homogenous syntax. As
on version
@value{VERSION}, support for Python is provided out of the box. Future support
for Perl and Ruby is planned. Feel free to contribute support for your
favorite language!
@item
Minimal disk space, memory footprint and CPU usage. Typically, on glibc 2.3.4
Linux 2.6 x86, a unique executable is less than 130 KB on disk, takes less than
3 MB of virtual memory per desklet right after initialization, and almost no
processor cycles (including cycles from a Python interpreted script) when idle.
@end itemize

It DOES NOT provide:

@itemize
@item
A sophisticated window API, or even access to widgets besides bare, ugly grey
menus.  You clearly cannot write any GUI application with this--only
``desklets''.
@item
Convoluted mechanisms (or just plain mechanisms, for that matter) for
script configuration. Script developers are free (or doomed, depending on how
you see things) to do whatever they see fit.
@item
Support for everything that is not a truly POSIX compliant system. For
instance, it would be very surprising if this would ever compile on Cygwin.
@item
Feature-rich management of user events. @command{adesklets} aims at low
resource consumption and reliability; only a small set of events, mainly 
pointer-related, are exposed through its API.
@end itemize

@node What's new?
@chapter What's new?

@heading What's new in version 0.4.10
This is a bug fix release. An unwanted partial new feature made is way 
into previous release: it caused the contextual menu to stop working 
the advertised way (the control key needed to be pressed for the menu to
get fired). This release just revert back the change, and add a 
configuration-time option, --enable-control-on-context-menu, for
those who really wants this behavior.

@heading What's new in version 0.4.9
This is a bug fix release. It changes the global macro definitions for
adesklets to compile without problems on FreeBSD 6.x, corrects an error
with debugging flag stripping from the C compiler, and adds a new demo 
program about threading.

@heading What's new in version 0.4.8
This is a bug fix release. It changes the global macro definitions for
adesklets to compile without problems on FreeBSD 5.x, and it also adds
fake root window detection for KDE, thanks to yogi77, from the forum.

@heading What's new in version 0.4.7
This is a bug fix release. It removes calls to some C99 math routines not
available in earlier BSD's, making the code more portable. It also adds 
two new commands to the API for handling the image caching mechanism better.

@heading What's new in version 0.4.6
This is a bug fix and documentation update release. It corrects many small
bugs inside the desklets submission process scripts, makes portability changes
to the autoconf structure, adds a new demo scripts in test (widget.py), corrects
the xwindow_move_window routine for a small placement bugs on the screen (thanks
to man1ed from the forum from providing the patch), and finally adds a new
appendix containing a handy online version of the Imlib2 documentation.

@heading What's new in version 0.4.5
This is a bug fix and documentation update release. It improves the desklets
submission process by releasing the full check-in script used by the maintainer.
It also solves a bug with window refresh when using user-defined background
image and menus; thanks to ZeroDivide for reporting this. Various updates and
corrections have also been made to the documentation.
      
@heading What's new in version 0.4.4
This is a documentation update release, principally aimed at desklet 
authors. It basically includes a new appendix on how to submit a desklet 
(including scripted support), and a new subsection on system-wide font
detection as well. The FAQ was also expanded to cover this topic.

@heading What's new in version 0.4.3
This is a documentation update release. Most of the work here was made by 
Mike Pirnat @email{exilejedi@@users.sourceforge.net}, who was kind enough 
to rectify the base author's deficient english by proofreading this manual 
from cover to cover. Thanks Mike! The FAQ was also slightly expanded, and 
a new appendix for desklets writer created.

@heading What's new in version 0.4.2
This is a new bug fix release. It corrects a bug within the Python package
that made it not compile on all versions of Python prior to 2.4.0. Thanks to 
nucular, from the adesklets forum, for reporting this. It also corrects another
minor mmap-related issue in the same package.

@heading What's new in version 0.4.1
This is a new bug fix release. It secures the use of the optional 
@code{adesklets.ConfigFile} class by completely changing 
the way config files are imported, thus removing a potential 
security exploit. Thanks to Mike Pirnat @email{exilejedi@@users.sourceforge.net}
for sharing his concerns on this issue.

@heading What's new in version 0.4.0
This is a new minor version release. The interpreter now supports
internationalization. It can now dynamically work with different
character sets on platforms supporting iconv (as standardized in UNIX98), and
display them in the right fashion. The Python package was also extended
to include an (optional) generic configuration class, hopefully useful
to desklets authors.

@heading What's new in version 0.3.2
This is a documentation update release. Documentation was added for Python
programmers, and the FAQ was slightly expanded.

@heading What's new in version 0.3.1
This is new bug fix release. It just adds support for interruption of time gates
by events. This is a feature absolutely required to make some timed effects 
possible.

@heading What's new in version 0.3.0
This is a new minor version release. Portability has been a big concern for us
since the beginning; with this version, the package compiles and runs flawlessly
on FreeBSD and NetBSD (@xref{Portability}.). Event handling has also been 
internally streamlined, and the Python binding was extended to support 
dynamic modification of caught events (see @file{test/test_events.py}).

The interpreter API now exposes everything the author wanted, 
and will probably not be expanded much further; everything is pretty much
in place to write any desklet, including animations.
 
@heading What's new in version 0.2.1
This is a minor bug fix release which removes a compatibility bug within
the GNU history library usage. Thanks to Mike Pirnat 
@email{exilejedi@@users.sourceforge.net} for reporting this.

@heading What's new in version 0.2.0
This is a new minor version release. Support was added for textual variables
(string substitution, in fact), and execution of timed preregistered
sequences of commands to the interpreter (indirect mode of execution).
This gives desklets a way to perform fluid animations. Run the demo script
@file{test/fading.py} from the source package to see those features in action.

For developers, this version also includes a rewritten, dynamically
configurable debug interface to the interpreter able to generate complete 
logs on any session.

@heading Details
See @file{Changelog} for all details.

@ifplaintext
@c Sets up a marker for automated INSTALL file generation
INSTALL_BEG
@node Installing adesklets
@unnumbered Installing adesklets
@end ifplaintext
@ifnotplaintext
@node Installing adesklets
@chapter Installing adesklets
@end ifnotplaintext

@section Compilation Requirements

To compile adesklets from source, you will need:

@itemize
@item
A compiler supporting ANSI C plus variadic macros (about every version
of @weblink2{gcc,http://gcc.gnu.org} from 2.7.0 will do - or about
everything else published in the last ten years, for that matter)
@item
@weblink2{X11,http://www.x.org/} libraries and
headers@footnote{Except for headless builds, useful
for server environments and such; read further for details.}
@item
Imlib2 1.1.2 and up (the more recent the better; go and fetch it from
@weblink{http://sourceforge.net/projects/enlightenment/})
@item
@weblink2{GNU readline,http://cnswww.cns.cwru.edu/php/chet/readline/rltop.html}
@item
A reasonably POSIX-compliant system
@end itemize

@noindent It can also use, if present in the system:

@itemize
@item
@weblink2{fontconfig,http://www.fontconfig.org/}, for automated detection of
all usable fonts present in the system
@item
@weblink2{GNU history,http://cnswww.cns.cwru.edu/php/chet/readline/rltop.html},
the faithful complement to GNU readline for command history support
@item
iconv library and headers (such
as @weblink2{libiconv,http://www.gnu.org/software/libiconv/}), for 
internationalization support (dynamic support of extended character sets)
@item
@weblink2{Python,http://www.python.org} 2.3 and up, if you want Python support
(you most probably do at this stage as it's the only scripted language that's
currently supported)
@end itemize

@section Portability Notice
@anchor{Portability}
This package was built with portability in mind: all vendor-specific
extensions were avoided, and specs (ANSI, SVID 3, BSD 4.3, POSIX) were followed
in a conservative way. Nevertheless, original development took place on a single
Linux system; it is quite probable that adesklets will not compile or work as 
expected in some cases. Fixing portability issues is an important concern for us.

adesklets has been ported and successfully tested by the developers on many
systems. As of version @value{VERSION}, it has been verified to compile and run
out of the box on:

@itemize
@item Linux 2.4 i386, glibc 2.1.3, gcc 2.95.2 (Debian Woody)
@item Linux 2.6 i686, glibc 2.3.4, gcc 3.4.3 (Gentoo Linux 2005.0)
@item Linux 2.6 amd64, glibc 2.3.3, gcc 3.4.2 (Fedora Core release 3)
@item Linux 2.6 amd64, glibc 2.3.4, gcc 3.4.3 (Gentoo Linux 2005.0)
@item FreeBSD i386, gcc 2.95.4 (4.10-BETA)
@item NetBSD i386, gcc 2.95.3 (1.6.1)
@end itemize

@strong{Update}: adesklets >=0.4.8 has also been reported to work on 
FreeBSD 5.3, but the author did not have a chance to verify this. Now 
that adesklets is in Debian unstable, it seems to at least compile on all
available kernels and architectures: go see @weblink{http://packages.debian.org/unstable/x11/adesklets}.

Did you try to run the package on something not listed here?
Let us know, especially if it did not work.

@section Software download

The current version of the software (as a source bzip'ed tarball) can be found
on the SourceForge project page: @weblink{http://sf.net/projects/adesklets/}

You can extract it from the console with @command{tar}. As of version
@value{VERSION}, the command line would be:

@example
tar xvjf adesklets-@value{VERSION}.tar.bz2
@end example

or, if your installed version of @command{tar} does not support
filtering archives through bzip2:

@example
bzcat adesklets-@value{VERSION}.tar.bz2 | tar xv
@end example

@section Verifying Software Integrity (optional)

As of adesklets @value{VERSION},  you can also
download from @weblink2{SourceForge,http://sf.net/projects/adesklets/} an 
ascii-armored detached signature named 
@command{adesklets-@value{VERSION}.tar.bz2.asc}, that you can match
against the author's Open PGP public key (@pxref{Open PGP Public Key},
in appendix) to assert the package integrity. For instance, with
@command{GnuPG} (@weblink{http://www.gnupg.org/}), you would use:

@example
gpg --verify adesklets-@value{VERSION}.tar.bz2.asc adesklets-@value{VERSION}.tar.bz2
@end example

You can also get the public key for @email{syfou@@users.sourceforge.net}
from various public key servers such as @weblink{http://www.keyserver.net/} or
@weblink{http://pgp.mit.edu/}. Feel free to contact the author directly if you
want to authenticate the key further.

@section Compilation and Installation:

adesklets provides the usual autoconf/automake scripts of GNU packages.

Therefore, in most cases, installation follows the normal three steps:

@enumerate
@item
`cd' to the directory containing the package's source code and type
`./configure' to configure the package for your system.  If you're
using `csh' on an old version of System V, you might need to type
`sh ./configure' instead to prevent `csh' from trying to execute
`configure' itself.

Running `configure' takes awhile.  While running, it prints some
messages describing which features it is checking for.
@item
Type `make' to compile the package.
@item
Type `make install' to install the programs and any data files and
documentation.
@end enumerate

You can remove the program binaries and object files from the
source code directory by typing `make clean'.  To also remove the
files that `configure' created (so you can compile the package for
a different kind of computer), type `make distclean'.

@section Compilers and Options:

Some systems require unusual options for compilation or linking that
the `configure' script does not know about.  You can give `configure'
initial values for variables by setting them in the environment.  Using
a Bourne-compatible shell, you can do that on the command line like
this:

@example
CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure
@end example

@noindent Or on systems that have the `env' program, you can do it like this:

@example
env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure
@end example

@section Optional Features:

adesklets comes with a few optional features you can select or not
from the `configure' script. Type:

@example
./configure --help
@end example

@noindent for a complete, short description. Here are a few interesting ones:

@itemize
@item
You may choose to compile adesklets without X support at all
(@command{--without-x}).
You will get a version that is obviously not suited for
desklets rendering, but still good for command line image manipulation
@item
You can remove support for some others packages as well:
@command{--without-history}, @command{--without-fontconfig}
@end itemize


@node Using adesklets


@chapter Using adesklets

@ifplaintext 
INSTALL_END
@end ifplaintext

@section ... As a desklets container

By itself, adesklets does little: it only provides what is needed to
do more! You either need to tell it what to do by passing it commands
(see the next section) or you need other scripts (the desklets)
that will drive it for you.

@noindent Right now, only a very few desklets have been released: 
you may find them on the SourceForge projet page as separate downloads:
@weblink{http://sf.net/projects/adesklets/}. They will give you a feel
of what @command{adesklets} is capable of.

@subsection Add a new desklet to your X display
To add a new desklet script, simply:

@enumerate
@item
Download its tarball and unpack it somewhere in your home directory
@item
Look at the included README file; special requirements or instructions
will be given. Usually, all you have to do is to get adesklets installed,
your X server running, then launch the executable script file from the
base directory.
@end enumerate

@noindent Please note that:

@itemize
@item
Launching the same desklet script more than once will start multiple instances of it.
@item
On multi-head displays, scripts will be launched on their inherited default 
screen.  (For instance, if you do nothing special, calling a script from an
xterm on screen 1 will launch the desklet on screen 1).
@end itemize

@noindent Most of the time, desklets scripts are made to run as long as you
do not tell them to quit. The user has total control of starting, stopping,
restarting (when possible), and positionning the desklet (using the context menu, 
always available by right-clicking on the desklet). The desklet has 
no control over those operations.

@noindent Those few user settings are stored in the @file{$HOME/.adesklets}
file. Usually, you do not want to edit this file yourself.
If you do, make sure no instances of @command{adesklets} are running at
the same time.

@unnumberedsubsubsec Special notes on system fonts

@emph{You may safely skip this section if you do not intend to use
non-supplied fonts with adesklets.}

Provided your system supports fontconfig (@weblink{http://www.fontconfig.org/})
and adesklets was compiled without using @code{--without-fontconfig} (compiling
with fontconfig support is the default; @xref{Installing adesklets}.), all the
TrueType fonts present in your system are available for use with adesklets.
At initialization time, adesklets with fontconfig support compiled in will go
through all the fonts detected on your system to identify all the TrueType 
fonts. See your fontconfig documentation on how to set up your application
fonts access properly (@xref{Frequently asked questions}, for some fontconfig
debugging hints). It's also good to know that adesklets' package includes a
copy of Bitstream's Vera font; all users can rely on @command{adesklets} 
having at least this font available at all time.

@unnumberedsubsubsec Special notes on internationalization

@emph{You may safely skip this section if you do not intend to use
extended charaters within your desklets.}

If your system includes @command{iconv} support (@xref{Installing adesklets}.),
you should be able to use any character from any charsets your system 
knows about for displaying text, either inside a desklet or in its menus,
provided you have appropriate TrueType fonts (i.e. TrueType fonts containing
those character representations)@footnote{For instance, Bitstream's Vera font 
included with @command{adesklets} contains glyphs for practically all Latin-1
(ISO-8859-1) characters.}. 

Nevertheless, when using extended (outside 7-bit @code{ASCII}) characters, 
you need to make sure your local GNU readline settings do not interfere. These
three parameters should be set as indicated below in the appropriate 
@file{initrc} file@footnote{Please refer to your GNU readline documentation}:

@example
set input-meta on
set convert-meta off
output-meta on
@end example

If you do not want to adapt your GNU readline settings, you can also pass the
@code{--enable-force-extended-characters-input} switch to the @code{configure}
script when configuring the package from source, which will cause those three
variables to always be appropriately overriden internally by the interpreter.

Of course, you will also need desklets built to use those extended characters.
At the time of writing, all non-contributed Python desklets support them; for 
those, the charset can be set by the user in the configuration file, when it 
exists@footnote{When it does not exist, it means the desklet does not need 
internationalization anyway}; users merely have to set the 'coding' line 
appropriately@footnote{See @weblink{http://python.fyxm.net/peps/pep-0263.html}
if you need details.}.

For instance, for using ISO Latin-1 characters, one should use something 
similar to:

@example
# -*- coding: ISO-8859-1 -*-
@end example

as the first or second line in the Python desklet configuration file@footnote{
Obviously, such a configuration file needs to be saved using ISO Latin-1 
encoding or any subset of it, such as @code{ASCII}.}. 

Finally, please note that if your platform does not support iconv,
you should always leave the coding parameter to @code{ASCII}, otherwise
you will get fatal errors such as @code{charset conversion not compiled in}
from the desklets.

@subsection Restore previously running desklets on new X session
Invoking @command{adesklets} without any arguments:

@example
adesklets
@end example

@noindent is enough to restart all desklets that were running the
last time you killed the X server (in this mode, @command{adesklets}
will exit quickly by itself: there is no need to run it in the
background. adesklets does not use a daemon; each applet will fork a 
standalone @command{adesklets} interpreter as a child process). 
Invoking @command{adesklets} when desklets are already running
will cause them to be killed before the creation of new 
instances@footnote{Both @command{adesklets} process and their immediate parents
will be sent a @command{SIGKILL} signal.}.

@noindent If you plan on using desklets on a regular basis, you should put
the previous @code{adesklets} command somewhere in your X session
initialization.  I cannot tell you where with precision, as it varies greatly
from system to system. Have a look at: 
@weblink{http://www.google.ca/search?q=''x window''+startup} for general help.

@section ... As a command-line graphic editor

You can also use adesklets as a command-oriented graphic editor.
If you type, in a console:

@example
adesklets :
@end example

@noindent You will get something similar to:

@anchor{prompt}
@example
adesklets 0.1.0 (Fri Jan 28 19:09:13 EST 2005), on Linux 2.6.10
[gcc 3.4.3 20041125 (Gentoo Linux 3.4.3-r1, ssp-3.4.3-0, pie-8.7.7)]
Press TAB for hints.
0 >>> _
@end example

@noindent The last line is a prompt. It tells you you are ready
to enter command number 0. As of adesklets @value{VERSION}, you have around
150 commands at your fingertips. Thanks to GNU readline, a lot of
autocompletion hooks are present, giving you an easy way to look around. 
Press TAB while typing a  command name or a command's first argument, and 
useful information will be displayed. @xref{primer,,an adesklets's primer}, 
for more info.

@node Programming adesklets
@chapter Programming adesklets
@section An adesklets' primer
@anchor{primer}

As previously stated (@xref{About adesklets}.), adesklets is basically an
interactive Imlib2 console, with one or two aditionnal features:

@itemize
@item
When an X display is present, automated management of a single window
@item
Automated support for pseudo-transparency
@item
Management of long-running applets
@end itemize

@noindent So let's start a typical interactive session to see what
happens. Under X, open a terminal, and type:

@example
adesklets :
@end example

@noindent As in last section (@xref{prompt,,'Using adesklets as a command-line
graphic editor'}.),
you will get a prompt. Now, enter the command '@code{images_info}'. You should
get on stdout:

@example
2 images
id 0 width 1 height 1 alpha 1 filename (null)
id 1 width 1 height 1 alpha 1 filename (null)
command 0 ok: images_info
@end example

@noindent This tells you that you have two images: image 0 and image 1, each
1x1 pixels. Those are the only images you can never destroy nor do any
operations you want with (resize them independently, flip them diagonaly, etc.)
Why is that?

@itemize
@item
Image 0 is the foreground image. By default, it is the only image that is
displayed on the single window that @command{adesklets} manages.
@item
Image 1 is the background image. By default, it always contains the content
of the root window (the desktop) directly below the window.  Unless we set it
to be otherwise, it is always updated when the user moves it, when you resize
it, when your wallpaper changes, etc.
@end itemize

@noindent But where is this window? Well, right know, it is only 1x1 pixels,
and it is not shown@footnote{``Mapped'' in X Window lingo} on the screen.
So let's resize it to 100x100 pixels: type '@code{window_resize 100 100}'.
Now, if you re-enter the command '@code{images_info}', you will get:

@example
2 images
id 0 width 100 height 100 alpha 1 filename (null)
id 1 width 100 height 100 alpha 1 filename (null)
command 2 ok: images_info
@end example

@noindent The foreground and background images have been resized to
100x100 pixels.  Moreover, the background image has been updated to contain
a new image of the background. Now, let's make this window visible. Type two 
commands: '@code{window_reset managed}' and then '@code{window_show}'.

@noindent The first command tell adesklets to let your window manager
``manage'' your window (the default is not to); it means the window gets
decorated, and you can interactively change its visibility@footnote{An
``unmanaged'' window is very useful for scripted desklets: it looks like
it is part of the root window as it can be made to never go on top, and to stay
mapped when workspaces are switched.}. The second command shows our 100x100 
window. So far, it's nothing too impressive--just a black 100x100 square with a
titlebar and fixed-size borders.

@noindent As mentioned above, only image 0 (the foreground) is displayed by
default. Now, type: '@code{window_set_transparency 1}'. Wow! We see the
root window below! With ``window transparency'' on, the image 1 (background)
is first copied onto the window, then image 0 (foreground) which is purely
transparent black, is blended onto it@footnote{Well...Not quite. Actually,
there is a buffer involved for performance, but the operation is logically
equivalent to this description.}.

@noindent It is time to say a word about colors. Remember, adesklets is an 
Imlib2 console. Thus, as with Imlib2@footnote{Keep your Imlib2 documentation 
nearby; it is very handy! @xref{Imlib2 documentation}.}, colors are 
always true 32 colors, RGBA encoded, with eight bits (0 to 255) per channel,
including an alpha channel for transparency. Palette conversion and such will 
automatically take place if your screen depth is less than that, so you do not
need to bother with that. If you type: '@code{context_get_color}', you will get:

@example
command 0 ok: context color 255 255 255 255
@end example

@noindent Imlib2 is a kind of state machine; as such, it comes with a
``context'' that remembers a series of attributes it will use in its future 
operations. For instance, we now know the color it will use as long as we do not
modify it is opaque pure white (red=255, blue=255, green=255, alpha=255). If we type: '@code{context_get_image}', it returns:

@example
command 0 ok: context image 0
@end example

@noindent Which means all window operations we perform are made directly on
the forgeground image. So, let's draw a filled semi-transparent magenta 
rectangle on the foreground. Commands could be: 
'@code{context_set_color 255 0 0 200}' and 
'@code{image_fill_rectangle 25 25 50 50}'. Neat, isn't it?

@noindent If you are used to Imlib2 programming, you will have noticed
by now those last few commands look quite familiar. This is pretty normal;
most of Imlib2 C functions are presented as corresponding 'commands' in
adesklets. This way, adesklets' command '@code{image_fill_rectangle}'
follows the same semantic as Imlib2's '@code{imlib_image_fill_rectangle()}'
function, the command '@code{context_set_color}' functions just like
'@code{imlib_context_set_color()}', etc. The only two significant (and
systematic) differences are that whenever you would use an 
'@code{Imlib_Something}' object in C, you use an integer ID with adesklets,
and on the semantic of the '@code{imlib_free_something()}' functions that need
to be given an ID instead of freeing the context selected object of this type.

@noindent This is pretty easy to illustrate. Let's load the ``Vera'' font 
included with adesklets at a 20pt size, set it as default font, and write in 
pure opaque white ``Hello'' diagonally on the foreground image from the top left
corner before unloading the font. It would look like:

@example
6 >>> load_font Vera/20
command 6 ok: new font 0
7 >>> context_set_font 0
command 7 ok: context_set_font 0
8 >>> context_set_direction text_to_angle
command 8 ok: context_set_direction text_to_angle
9 >>> context_set_angle 45
command 9 ok: context_set_angle 45
10 >>> context_set_color 255 255 255 255
command 10 ok: context_set_color 255 255 255 255
11 >>> text_draw 0 0 Hello
command 11 ok: text_draw 0 0 Hello
12 >>> free_font 0
command 12 ok: free_font 0
@end example

@noindent If you look at your imlib2 documentation, you will immediatly notice
the two differences we just talked about:  all references to the font Vera/20
are made through an integer ID (0 here), and the '@code{free_font}' command, 
unlike the corresponding '@code{imlib_free_font()}' function, is called with
the font ID as an argument instead of the context font.

@noindent Now let's say you want to save you resulting image; not a problem!
Let us type: '@code{save_image out.png}', and the foreground is saved in the
file ``out.png'' in the current working directory@footnote{For this to work, 
you need to have your Imlib2 installation properly configured for using libpng,
or you could receive a ``no loader for file format'' error.}. Now, just for 
the sake of it, let us exit adesklets, and start another interactive session
to see if we can reload this image. Just type in the ``@code{quit}'' command or
press ^D (Control D: end of file). Then your new session should look something like:

@example
0 >>> window_resize 100 100
command 0 ok: window_resize 100 100
1 >>> window_reset managed
command 1 ok: window_reset managed
2 >>> window_set_transparency 1
command 2 ok: window_set_transparency 1
3 >>> load_image out.png
command 3 ok: new image 2
4 >>> blend_image_onto_image 2 1 0 0 100 100 0 0 100 100
command 4 ok: blend_image_onto_image 2 1 0 0 100 100 0 0 100 100
5 >>> window_show
command 5 ok: window_show
6 >>> free_image 2
command 6 ok: free_image 2
@end example

@noindent Of course, we wanted to visualize the result; this is why we
emitted commands '@code{window_reset}', '@code{window_set_transparency}'
and '@code{window_show}'; they are not otherwise useful. The command
'@code{blend_image_onto_image}' comes straight from Imlib2 once again;
it takes the newly created image 2 from the third command and blends it
onto the context image (image 0, foreground by default), for its coordinates
(0,0) to 100x100 pixels farther, and puts it on the rectangle starting at (0,0)
of size 100x100 pixels of image 0. It is finally good to note that, with
adesklets, there is always an image in Imlib2 context: whenever you try to
free the current image, the image context is always reset to the foreground 
image.

@noindent OK, so it is almost the end of this primer... From there you should
play around with adesklets.  It is pretty straightforward to use if you are 
already familiar with Imlib2. If you are not, your best resource is certainly 
having Imlib2 documentation not far away. :-)

@noindent Some last tips:

@itemize
@item
If you get tired of typing, and typing, do not forget you have autocompletion:
'TAB' your problems away!
@item
If you want to have hints on how to do something, you have a built-in
'@code{help}' command.
@item
If you are working out a series of commands, things are not working
and all this interactive usage it getting tiresome:
@enumerate
@item
Use the '@code{history}' command to output your current session to a
file@footnote{For this to work, you need to have GNU history when
building adesklets.}.
@item
Use the '-f' switch with adesklets to get commands from a file instead
of the console tty.
@item
If you try to visualise something, insert a '@code{pause}' command at the
end of the script to freeze the interpreter.
@item
All strings from a pound sign '#' to the end of a line will get discarded,
allowing you to write comments.
@end enumerate
@end itemize

@noindent Here is an example:

@example
#!/usr/bin/env adesklets -f

# Make the window 'managed'
#
window_reset managed

# Resize the window to 100x100 pixels
#
window_resize 100 100

# Show the window, then freeze for 10 seconds before exiting
#
window_show
pause 10
@end example

@noindent You will just have to make this script executable and run it. As
usual, output from the commands will get printed to stdout.

@itemize
@item You could also use the @code{play} command. This two-arguments command
gives you a way to replay any sequence of commands from history, using the 
command number of the first and last command as parameters.
@end itemize

@section Real programming with adesklets: writing desklet scripts

When you are ready for real work@footnote{:-)}, you might want to use
a real scripted language instead of the raw @command{adesklets} interpreter we
used in the primer; you never know when just having variables could come in 
handy.

At the time of this writing (@value{UPDATED}), the Python package is included 
@footnote{adesklets was written to be easily used from a variety of interpreted
languages; future plans includes wrappers for Perl and Ruby--do not hesitate 
to propose your help if you want to speed things up!}, and the Perl 5 binding
is under way.

@subsection General tips for programmers

A really useful feature of the @command{adesklets} interpreter 
is its ability to produce a full trace of its session (commands, events and
special messages), either on @code{stdeerr} or as a log file, independently
of what is driving it. To have access to this feature, one must:

@enumerate
@item Configure the package from source, passing along the @code{--enable-debug}
switch to @code{configure}.
@item Export the @code{ADESKLETS_LOG} variable in the environment if 
the session's output should to be stored in files instead of printed
to @code{stderr}@footnote{Printing to @code{stderr} will break most bindings, 
and should therefore be used mainly when invoking the interpreter directly 
from the console.}. It should be an absolute filename prefix which the
interpreter, inheriting from the environment, can use to create complete file
names to write to.
@end enumerate
From there, it is possible to read complete chronological session logs;
used correcly, it is very useful for debugging purposes. You can use 
it in conjunction with the @code{echo} command to set easy to find log points.

@subsection adesklets and Python 
@unnumberedsubsubsec Python usage example
From Python, things are not very different than from the interpreter.
Commands have been wrapped into Python functions, and an @code{Events_handler} 
class has been made public to handle asynchronous feedback from the
interpreter.  Let's have a look at the @file{test/test.py} script from the
source tarball of version @value{VERSION}:

@verbatiminclude ../test/test.py

That's it! Twenty-six lines of Python code, and we have a perfectly functionnal
desklet. I think things are pretty self-explanatory; have a look at the
Python online help for @code{adesklets}, @code{adesklets.commands} and 
@code{adesklets.Events_handler} for a good, complete explanation
@ifhtml
(@xref{Python package documentation}.)
@end ifhtml
.  All we do here is:

@enumerate
@item
Import the @code{adesklets} package:
this automatically instantiates a child @command{adesklets} process and sets up
all communications.  When the package initialization returns without raising
any exception, it means the interpreter is up and ready to accept commands.
@item
Subclass @code{adesklets.Events_handler} and redefine the methods invoked
for the events we are interested in (all other events are not just ignored,
they are not generated).
@item
Instantiate an object of this class, and put it on hold indefinitely
@footnote{This last step is not mandatory; the script may very well continue,
but it should be written so that it supports signal interruptions. See
@code{help(adesklets.Events_handler)} for further explanations}.
@end enumerate 

@unnumberedsubsubsec Gotchas: a bit more about object IDs

All adesklets objects (fonts, images, color ranges, polygons, etc), are stored 
in stacks (one stack per object type). Python's ID's are nothing more than the 
initial position of given objects inside the relevant stack, and therefore 
will become invalid if an object of the same type below them gets freed.

For instance, if we start with a clean state, all we have in the stack of 
images is the window's foreground (ID 0) and background (ID 1). 
When someone creates two other images from Python like so: 
@example
im_1 = adesklets.create_image(10,10)
im_2 = adesklets.create_image(10,10)
@end example
@noindent We get @code{im_1==1}, and @code{im_2==2}. Whenever someones does:
@example
adesklets.free_image(im_1) 
@end example
@noindent The stack starts collapsing, and what was once image 3 (@code{im_1}) 
is now image 2, and @code{im_2} is now an invalid reference. This clearly means 
that invoking:
@example
adesklets.free_image(im_2) 
@end example
@noindent would generate an @code{image out of range} error message.

@unnumberedsubsubsec Special subject: animations

@command{adesklets} now includes an indirect mode of execution and textual 
variables (non-recursive textual replacements, to be precise) as well. 
This means desklets writers have what is needed to create precisely-timed
animations. You can find an easy-to-follow example in @file{test/fading.py}.
A somewhat more involved use of these features is also made in the @code{yab}
desklet. To realize an animation from Python, one should:

@enumerate
@item @strong{Record} a sequence of commands 
(we will call it a macro command, or macro for now on). From Python, this
involves toggling on indirect mode using the @code{adesklets.start_recording()}
function, emitting an undetermined number of @command{adesklets} commands,
then toggling back into normal mode (direct execution) with 
@code{adesklets.stop_recording()}. Of course, no command is ever evaluated
while the interpreter is in indirect mode; commands are only stored in the
history for future replay.
@item @strong{Set up} whether the to-be-replayed sequence of commands can be
interrupted by events or not, using the @code{adesklets.play_set_abort_on_events()}
function. The high-level @code{adesklets.Events_handler::set_events()} method
can also be used to dynamicaly change what events are caught. See 
@file{test/test_events.py} for an example.
@item @strong{Set up} the variables used within the recorded macro using the 
@code{adesklets.set()} function, very similar to its Bourne shell homonym.
@item @strong{Play} the macro using the @code{adesklets.play()} function.
@end enumerate

Here are a few additional remarks:
@itemize
@item Precise timing during replay is achieved through the @code{time_gate}
command. This works very simply: every time a macro replays, adesklets
records its starting time, and whenever a @code{time_gate} command is
encountered during the replay, it waits for the number of seconds given as
an argument to @code{time_gate} to run out. For instance, specifing
@code{time_gate 0.1} in a macro will make any subsequent commands within the
macro not execute before the macro has run for at least a tenth of second.
@item Variable expansion always occurs just before command execution, regardless
of current interpreter mode (direct or indirect). All sequences of characters
not containing spaces directly following a single '$' will get replaced with
the corresponding variable content (previously configured using @code{set}).
If no matching variable is found, the sequence is simply discarded.
@item All macro commands replayed through the @code{play} command are always 
atomic for the driving desklet, as are any other non-macro commands. 
Simply put, it means no event will ever get generated while a macro is replayed;
they will all get issued right after the @code{play} command returns.
@item As usual, the adesklets interpreter is stateful for indirect mode related 
states and variables. You do not have to set up the @code{set_abort_on_events}
flags or variable every time you want to call a macro, only if something
needs to be changed since the last call.
@item The main use of high-level @code{adesklets.Events_handler::set_events()}
is to stop the catching of specific events during macro playback, so the macro
can be interrupted only in specific circumstances. Of course, all events
generated before the call to the method will not be lost but queued, and
appropriate event methods will be called later, provided the handlers are set 
back once the macro playback completes.
@item Did we mention that it is a bad idea to do any of this from an unprotected
place? Well, it is. Don't forget to use @code{adesklets.Events_handler::block()}
and @code{adesklets.Events_handler::unblock()} around all animation-related code
if you have an object of a child class of @code{adesklets.Events_handler}
instantiated.
@end itemize

@unnumberedsubsubsec Configuration and internationalization

Let us just mention here that from @command{adesklets} 0.4.0, the
@code{adesklets.utils} module now includes an optional 
@code{ConfigFile} class that can be easily reused by desklets authors 
to add an easily extendable configuration facility to their 
code@footnote{You can look at any non-contributed configurable desklet for 
example usage.}
@ifhtml
(@xref{Python package documentation}.)
@end ifhtml
. The class also handles internationalization automatically by default, 
setting the charsets according to users' needs. Charset usage can of course 
be determined or changed at any time using the @code{adesklets.get_charset()}
and  @code{adesklets.set_charset()} functions. The 
@code{adesklets.utils.ConfigFile} class also has a @code{charset} attribute one
can examine to determine the user's preference. When using this class, one
should  note that an 'ASCII' charset is considered the default, and will not 
toggle any conversion. This way, users on platforms not supporting iconv will 
always be able to use @command{adesklets} without internationalization support.

@unnumberedsubsubsec Final words

@noindent Finally, let us mention you may want to take a look at the 
@file{weather} desklet source code from the
@weblink2{SourceForge project web site,http://sourceforge.net/projects/adesklets/} 
for a more substantial piece of Python code using adesklets. There are also a 
few other test desklets under @file{test/} that may give you some ideas.
@ifhtml
You could also have a look at pydoc's autogenerated
@command{adesklets} package help, included with this document
(@xref{Python package documentation}.). Whenever you are happy enough with 
your desklet, feel free to share it with the rest of us (this would be 
much appreciated)--package it (@xref{Packaging GNU Makefile for desklets}.), 
and then submit it (@xref{Submitting a desklet}.).
@end ifhtml

@node Extending adesklets
@chapter Using adesklets from other language environments

adesklets was made to be easily usable from a variety of langage
environments@footnote{We use the term ``langage environment'' because the 
problem is not the syntax or the paradigm used (should it be imperative, 
functional, or anything else); it is the way you can handle basic POSIX-related
operations with files, signals, etc. (@xref{Requirements}.). Thus, a Perl 5 
user should use adesklets easily, while a Linux JDK user would probably 
encounter more difficulties (no flames intended).}. This chapter explains 
to programmers how the adesklets interpreter hooks itself into the system 
in a language-neutral fashion.

@noindent If you are not minimally used to POSIX systems or do not have basic 
notions on operating system programming, this chapter is probably of no
interest to you.

@noindent Please note that the Python package under 
@file{scripting/python/adesklets} 
is a good complement for what you are about to read.

@section Requirements 
@anchor{Requirements}
If you want to use the adesklets interpreter from your favorite language
but it is not supported out of the box@footnote{As of adesklets
@value{VERSION}, only Python is supported out of the box.}, you can still do
it, provided your langague supports one of these features:

@itemize
@item Reading and writing in pipes; or
@item Reading and writing from/to files unbuffered 
@end itemize

@noindent It should also be able to either@footnote{This said, having both IPC
support and poll/select will make things both simplier and cleaner. Being able 
to block signals is also very useful.}:

@itemize
@item Catch IPC reliable signals; or
@item Read files in non-blocking mode; or
@item Be able to perform a poll/select on files
@end itemize

@noindent Finally, it should also be able to start a child process. 

@noindent Those a pretty light requirements from a POSIX point of view, but let
us mention for the sake of completeness that if your language environment does
not meet these requirements, you could still use it provided you can get your
application to talk reliably with another program@footnote{This would be a
wrapper, basically.} that meets them. Of course, this is not an ideal situation
and it should be avoided as much as possible.

@section Initialization mechanism

As you probably know (@xref{Using adesklets}.), there are two modes of operation
for @command{adesklets}, as it can be called:

@enumerate
@item as a desklets launcher--whenever you call @command{adesklets} without 
arguments.
@item as an interpreter--in all other cases (interactive command line use
or a child process from a desklet).
@end enumerate

@subsection adesklets called as a desklets launcher - restarting all desklets 
@noindent On a new X session, the typical startup sequence is:

@enumerate
@item @command{adesklets} gets called without arguments, somewhere 
from the X session initialization scripts.
@item From there, the new adesklets instance acts as a desklets launcher. 
It parses the @file{$HOME/.adesklets file}, then forks as many times as there 
are desklets to start.  The original launcher process then exits as there is
no need for a daemon here.
@item All forked processes set up the @code{ADESKLETS_ID} environment variable
with a string representation of the proper integer ID, then execute
@footnote{With a call from the execve* family; see @code{man 2 execve}.} 
the associated script.
@item Each desklet launches itself an @command{adesklets} instance as a child
process, passing along the @code{ADESKLETS_ID} variable without altering it. 
It is the desklet's duty to make sure that:
@itemize
@item the adesklets interpreter standard streams, 
@code{stdin}, @code{stdout} and @code{stderr}, get separately redirected, 
in a way that parent process can easily write to adesklets' @code{stdin}, 
and read from @code{stdout} and @code{stderr}. Use of pipes, FIFOs or event
regular files are all possible.
@item the writes to @code{stdin} and reads to the two other streams are 
all unbuffered.
@item the first command argument given to @command{adesklets} is the absolute
file name of the desklet script.
@end itemize
@item Each newly created @command{adesklets} interpreter process initializes 
itself using the environment @code{ADESKLETS_ID} variable and the command
line absolute desklet name given as its first argument to lookup its 
unscriptable characteristics@footnote{They are, namely, its screen and 
coordinates.} from @file{$HOME/.adesklets}. When this operation is over, 
the @code{ready!} event is generated (@xref{Events}.), and the interpreter is 
ready to process commands.
@end enumerate

@subsection adesklets called as an interpreter - registration of a new desklet

When a new desklet gets called directly, the startup sequence described in
the previous subsection is the same, except for the first, second and third
steps which simply don't occur. This means that the environment 
@code{ADESKLETS_ID} is not set; the new @command{adesklets} interpreter uses 
this fact to detect this is a new desklet, parse the @file{$HOME/.adesklets}
configuration file and allocate the first free ID to the desklet.

@noindent It should be noted that if the desklet file name given as the first 
argument to the child @command{adesklets} instance is relative or is not both
readable and executable by the current user, the desklet will not get registered
in @file{$HOME/.adesklets}, and therefore not automatically restarted in 
subsequent new X sessions by the launcher. In case @code{stdin} is a 
terminal@footnote{Which means the session is interactive}, the registration
does not take place either.

@subsection Consequences
This way, from the scripted desklet perspective, both cases are identical, and
no conditionnal treatment is needed. All the desklet initialization job 
is synthesized in the fourth point in the subsection above.

@noindent If needed later on, the desklet can use the @code{get_id} command 
to determine its ID.

@section Using streams

As explained previously, a desklet communicates with its private adesklets 
interpreter via redirected unbuffered streams. Here, let us see what information
they convey.

@subsection stdin: the commands

On the interpreter's @code{stdin}, the desklet outputs the commands it wants to
execute in the order in which it wants them to be executed, one command per 
line@footnote{A '\n' character should be emitted after each command.}. Since 
reading this stream is suspended while a command is processed, a desklet should
generally wait for a command to be processed before emitting 
another@footnote{This is to avoid process blocking by overflowing the stream 
with arbitrarily long commands; of course, there is no problem sending three
commands of a few hundred bytes in one shot!} (See the next section).

@noindent The command format is pretty simple: it is a command name, followed 
by arguments separated by spaces, all in plain text representation, including 
numbers. adesklets does not care about the number of spaces between arguments,
as long as there is at least one. In the special case of commands where the
last argument is a string (@code{text_draw}, for instance), adesklets will
choose its first non-space characters to be its beginning; the rest of the
line, including spaces, are considered to be part of the string.

@noindent Two files, automatically kept in sync with the source 
(@file{scripting/prototypes} and  @file{scripting/enums}) from the base source
distribution, provide in tab-separated plain text format the description of all
the commands and numeric constants that can be made available to the 
desklets@footnote{See @file{scripting/protoize.sh.in} and 
@file{scripting/enums.sh} for details on the format of the two files.}. A good 
binding for a specific language should come with some automation to
auto-generate pertinent parts of its own codebase based on those files; for
instance, the Python binding adds a @code{protoize} action to its 
@file{setup.py} @code{distutils} script to do so. Ideally, this automation code
should be redacted in the target language with a reasonable set of 
libraries@footnote{The key idea being that most users of your binding should be
able to run it more or less from their base installation of the language.}; 
if it is not well suited to this task, you need to limit yourself to use:

@itemize
@item Portable Bourne shell, conforming to POSIX 1003.2 and 1003.2a, scripts
@item A recent sed (Streaming Editor), compatible with GNU
sed@footnote{Nowadays, there is no problem running GNU sed on practically any
POSIX system.}
@item Portable use of any bc for arithmetic
@end itemize

@noindent if you want your work to become part of the official package.

@subsection stdout: the command results

The @command{adesklets} interpreter frequently polls its @code{stdin} 
for new characters, and reads from it as needed. Whenever it receives an
End-Of-Line ('\n'), it stops reading from it and tries executing the command. 
Once the command has been carried out (possibly emitting a few lines on
@code{stdout}), it sends as its last entry on it a status message of the form:

@example
command RANK ok: MESSAGE_STRING
@end example

@noindent if the command was successful, or:

@example
command RANK error: ERROR_STRING
@end example

@noindent if an error occurred.

@noindent @code{RANK} is the numerical ID of the command (an unsigned integer)
that starts at zero when the interpreter is created, and then is automatically
incremented by one for every subsquent line it receives. All commands are 
guaranteed to be processed in the order they were submitted. 
@code{ERROR_STRING} is a free-form message in human-readable form explaining the
source of the error. @code{MESSAGE_STRING} is also in human-readable form, but
is formatted in such a way that it can be used to retrieve algorithmically
useful return values for any commands. Those return values can be:

@enumerate
@item an integer--the return value ID (@code{create_image} and such)
@item a tuple of integers--the numerical command output 
(for @code{context_get_color} and the like)
@item a list of strings--the ordered list of output strings 
(for @code{images_info} and the like) for commands that output multiple lines
on @code{stdout}, with the last line being the status message 
@item a description string--a one-line textual answer from the command
@item nothing at all
@end enumerate

@noindent Algorithmically, your "return value retrieving routine" should first
try to retrieve integers from 
@code{MESSAGE_STRING}@footnote{All parameters from the @code{MESSAGE_STRING}
are separated by single spaces.}. If there is one or more integers present, 
it should verify that the message is not a mere copy of an emitted command;
if it is, the return value follows the fifth case (see above); otherwise, 
if only one integer is found, this is the first case; if more than one is
found, the second one.  If no integers are found and there was a list of lines 
sent to stdout before the status message of the command, and after the status
message of the previous command, it then returns according to third case.
In what's left, if the status message is different from the emitted command, it
is the fourth case. All remaining conditions should be mapped to the fifth
case. This retrieving algorithm is working for all commands listed in
@file{scripting/prototypes}.

@subsection stderr: the events
@anchor{Events}

All remaining asynchronous event reports are sent to the interpreter's
@code{stderr}. They are asynchronous regarding the processing of commands;
if they will never occur while a command is processed (in the time interval
between the submission of the complete command on @code{stdin} and the output
of its message status line on @code{stdout}), they can be sent at any other
time@footnote{No event is ever lost anyway; its report is only delayed.}.

@noindent Event reports are single lines of the form@footnote{All other outputs
on @code{stderr} can safely be discarded.}:

@example
event: EVENT_MESSAGE
@end example

@noindent In a stylized Backus Naur form, the grammar for EVENT_MESSAGE would 
be:

@verbatim
EVENT_MESSAGE :: ready! |
                 backgroundgrab |
                 menufire MENU_ID MENU_STR |
                 motionnotify X Y |
                 enternotify X Y | 
                 leavenotify X Y |
                 buttonpress X Y BUTTON_ID |
                 buttonrelease X Y BUTTON_ID
;;
@end verbatim

@noindent where @code{MENU_ID}, @code{X}, @code{Y}, and @code{BUTTON_ID} are
all integers greater than or equal to zero, and @code{MENU_STR} is a string of
characters, possibly including spaces. Let us detail things a bit further:

@itemize
@item Ready event: sent only once, whenever the @command{adesklets} interpreter
becomes ready to process commands.
@item BackgroundGrab event: sent every time the background image (image 1) gets 
regenerated.
@item MenuFire event: sent every time the user select an item in a menu not
managed internally by adesklets.
@item MotionNotify event: sent whenever the pointer moves inside the adesklets 
window.
@item EnterNotify, LeaveNotify: sent whenever the cursor passes over a visible
border of the interpreter window, either going in or out.
@item ButtonPress, ButtonRelease: sent when a pointer button is clicked inside 
the interpreter window.
@end itemize

@noindent All events but Ready! (namely: MotionNotify, EnterNotify, 
LeaveNotify, ButtonPress, ButtonRelease, BackgroundGrab and MenuFire) are
masquable by the desklet. In fact, @command{adesklets} provides the desklet
with commands for specifically handling the generation and output of events.
They are: 
@code{event_catch}, @code{events_get_send_sigusr1}, @code{events_reset_all},
@code{event_uncatch}, @code{events_info}, @code{events_set_echo}, 
@code{events_get_echo}, @code{events_purge} and @code{events_set_send_sigusr1}.
It should be noted that those functions are not listed in
@file{scripting/prototypes} as you most probably do not want your users having
access to them. You should probably start an interactive session and play with
them to make sure you fully understand this. This is also the right time to
mention the @file{src/adesklets_debug.sh} script, which comes in handy when
interactively experimenting with events.

@noindent Two last things are worth mentionning about events:

@enumerate
@item By default, events are not echoed, but stored internally, waiting 
to be purged with @code{events_purge}. You can change this with
@code{events_set_echo}.
@item You can set the adesklet interpreter to send a SIGUSR1 signal every time
an event is printed out to its parent process (the desklet). It is a very
useful IPC, since the signal can be trapped, allowing the event management
routine to run only when necessary. This is what the Python package uses within
its @code{Events_handler} class.
@end enumerate

@section SIGCHLD signal handler

Whenever your language allows it, you should install some kind of SIGCHILD
handler, so you can at least be notified if the adesklets interpreter ever
exists without a reason (child zombies notwithstanding)@footnote{@code{man 2
signal} is a very good reference on signals.}.

@section Textual variables

@command{adesklets} also supports differed execution (indirect mode)
and textual replacement of variables. Here how variables work in indirect mode:

@enumerate
@item Once a command is entered, it is stored untouched into the commands
history list, if applicable (in non-interactive usage of the interpreter,
when the command lies bethween calls to @code{start_recording} 
and @code{stop_recording})
@item When a macro command is played back (using the @code{play} command,
@xref{Programming adesklets}.), variables get expanded in a single pass, and no
indirect reference is possible.  Expansion is pretty straightforward. The stored
command line is scanned for any non-empty sequence of non-space characters
beginning with a single '$'.  Each such sequence is replaced with the 
corresponding @code{$variable} value, or removed if no variable is found.
@item Expanded command get executed.
@end enumerate

The same expansion mechanism also applies to the direct mode of execution. All
this leads to the fact that, using the Python package for instance, these two
code snippets are equivalent:

@example
adesklets.window_resize(100,100)
@end example

and:

@example
adesklets.set('dim',100)
adesklets.window_resize('$dim','$dim')
@end example

This did not require any alteration of our Python code, since Python is a
dynamic language, but some other languages will require further thinking.

@section Final words

You should now know pretty much everything needed for integrating adesklets with
your language environment. It may appear to be a daunting task, but a very
clean binding can be produced by one programmer in only a few days. Once again,
have a look at @file{src/adesklets_debug.sh}; it is a (very lame) Bourne shell 
binding for adesklets written in only fifty lines, including comments.

If you ever need assistance, you are encouraged to post on the 
@weblink2{adesklets-devel mailing list,https://lists.sourceforge.net/lists/listinfo/adesklets-devel}...

Happy coding!

@noindent 
@node Help wanted!
@chapter Contributing to adesklets

Your help is wanted! You can valuably contribute to adesklets by:

@itemize
@item
@strong{Posting your adesklets screenshots online}. You use adesklets and think
you have a pretty cool desktop? Share it with the world by posting it online,
and send us a link! This way, you will help people learn about the project.
@item
@strong{Contribute to the documentation}. You have very good written
knowledge of German, Spanish, Portugese, Arab or Swahili? Translators are always 
welcomed, proofreaders too, for all languages.
@item
@strong{Writing new desklets}. adesklets is still young: we crave
talented desklets writers, and we would be more than willing to post or link
to your work. Do not worry too much about interface changes; the author spent
considerable effort to ensure that the interface would be fairly stable even
in the earliest releases.  It's not frozen forever, but it shouldn't break your
desklets without some warning.  At this point, the API is predominantly getting
internal bug fixes and portability improvements.
@item
@strong{Adding bindings for your language of choice}. Contact the developers 
beforehand so that you don't waste time on something that is already written;
they will be glad to share code.  Subscribe to the
@weblink2{adesklets-devel mailing
list,https://lists.sourceforge.net/lists/listinfo/adesklets-devel} on
SourceForge for quick access to them.
@end itemize

@noindent Contact me by email at @email{syfou@@users.sourceforge.net}.

@node Frequently asked questions
@appendix Frequently asked questions

Last update: @value{UPDATED}
@section Compiling adesklets

@subsection The adesklets configure script says my Python install is too old, but it's not. What's the problem?

Some platforms (NetBSD, Ubuntu Linux, probably others too) sometimes alter 
the Python version, appending letters, prefixing minor numbers, etc., thus 
preventing the configuration script from detecting it properly. If you know 
@strong{for sure} that what you have installed is at least 2.3.0,
you can pass the @code{--with-python-force-detection} switch to 
@code{configure}; this will make the configuration script skip the version 
detection.

@section Starting desklets

@subsection When I try to start a new desklet, I get an @code{ImportError: No module named adesklets} error from the Python interpreter. What's happening?

It means what is written: @command{python} cannot find the @code{adesklets}
package; maybe it did not get installed, or it did get installed in the wrong
place.

@itemize
@item Restart from the beginning the installation procedure
(@xref{Installing adesklets}.). Make sure you @strong{do not} select
the @code{--without-python-support} configuration option.
@item Retry starting the desklet. If it still does not work, verify that the
installation directory, given by:@example
sed -n '/PYTHON_SITE_PKG/p' Makefile
@end example
@noindent is included in :@example
echo 'import sys; print sys.path' | python
@end example

@noindent If not, you can still manually move the adesklets directory 
from @code{PYTHON_SITE_PKG} to any path displayed by this last command.
@end itemize

@subsection When I try to start a new desklet, I get an @code{ADESKLETSError: adesklets process exited} error from the Python interpreter. What is this?

On some rare systems (@weblink2{archlinux,http://www.archlinux.org/} for instance),
the @code{PATH} variable for the Python interpreter differs from
what is inherited from standard environment, which causes the Python package to
fail to launch adesklets as a child process. On such systems, make sure
to install @command{adesklets} using an appropriate @code{--prefix} switch at
the configuration stage. For instance, on most recent Linux platforms, you 
should use:

@example
./configure --prefix=/usr
@end example

@subsection Everything worked fine but then I tried upgrading a desklet, and I couldn't ever see the new one. What is wrong?

There is a built-in lock mechanism in the interpreter that prevents a user from
simultaneously running more than one desklet with the same @code{ID} and name,
regardless of version.  Whenever you upgrade a given desklet, you should first
cleanly quit the desklet (by using @code{Quit} from the context menu), then
install the updated desklet by following the instructions provided in the 
@file{README} file.

@subsection Gosh! The desklet X is working, but does not remember its settings, or it always starts on the top left corner of screen 0 on a new X session. What is that? It sucks!

This is most probably related to the way you started the desklet
(Please @pxref{Using adesklets}.). You need to invoke the desklet script
@strong{only once}. Afterwards you just need to run the command:

@example
@command{adesklets}
@end example

and it will remember where you placed your desklets and which desklets 
you had running.

@subsection This is exactly what I did, but the darn thing wouldn't restart anyway.

Did you store the desklets under a @file{$HOME/.adesklets} directory?
Please don't.
@command{adesklets} need a @file{$HOME/.adesklets} file to store the various
user settings on running desklets; setting up a directory of the same name 
prevents it from doing its job right, so just move your directory some place 
else (@file{$HOME/.desklets}, for instance).

@section Displaying desklets

@subsection Where are my desklets? @command{adesklets} interpreters seem to be running fine, but I just cannot see anything on my desktop!

Try the command:

@example
python test/test.py
@end example

@noindent from the base source directory. If a 100x100 window appears, 
it most probably means you are using a window manager that draws 
a big window over the root window; your desklets are just drawn below it.
Such window managers include Nautilus, KDE, Xfce4, CDE or E17. 
Right now, Nautilus, KDE and Xfce4 are handled automatically, but others are not.

All the necessary infrastructure is already in place. In most cases, only the 
@code{xwindow_get_root_window()} function from @file{src/xwindow.c} has 
to be expanded to detect new window managers. You can either submit a patch, 
or ask for it on the @weblink2{adesklets development mailing list, http://lists.sourceforge.net/lists/listinfo/adesklets-devel}.

@subsection I cannot see smaller desklets such as xmms_bar or asimpleclock, while others work. What gives?

New desklets are always started in the leftmost, upper corner of the screen, at
the very bottom of the windows stack. Make sure you do not have some elements 
(gnomebar, engage, etc) already masking this zone of the screen. Beware! Some 
applications use pseudo-transparency, and can mask the root window seamlessly.

@subsection I am running Fvwm as my window manager. Why can't I keep the desklets below all my other windows? They keep popping on top!

Go see the Fvwm faq: @weblink{http://www.fvwm.org/documentation/faq/#5.11}.
This @code{BugOpts RaiseOverUnmanaged on} option was reported to work for many 
Fvwm users.

@section Running desklets
@subsection The 'Configure' item from the context menu of many desklets doesn't work!
For this to work--at least for all the demo desklets--you need to have
@command{xterm} installed, and the @code{EDITOR} variable properly set in 
your environment, as it is customary in UNIX. Please note this only launches a 
text editor in a terminal. Editing the desklet's configuration file
(usually @file{config.txt} from base desklet directory) has the same effect.

@subsection Do you plan including SVG support? I would like to use a SVG image in one of my desklets.
No we do not, sorry. It is not
that @weblink2{SVG,http://www.w3.org/Graphics/SVG/} is a bad format; in fact 
it is quite good. But it is also a vector-oriented one (and rather complex), 
while Imlib2, on which @command{adesklets} relies heavily, is completely 
raster-oriented, and using Imlib2 is the main reason for @command{adesklets}'
simplicity, relatively good speed and low resource usage. 

That said, there is no reason for you not using SVG's with desklets, since 
it is quite easy to convert images in SVG to high quality PNG's, 
using programs such as @weblink2{sodipodi,http://www.sodipodi.com/}, @weblink2{inkscape,http://www.inkscape.org/} or @weblink2{xsvg,http://xsvg.org/}. 
In a directory full of SVG's, on a GNU system you can use a command such as:
@example
ls *.svg | sed 's/\(.*\).svg/-z --file=& --export-png=\1.png --export-width=128 --export-height=128/' | xargs --max-lines=1 sodipodi
@end example
to convert them all to 128x128 semi-transparent PNG's.

@subsection I would like to use some of my system's fonts with adesklets, but I cannot get my desklets to find them. What should I do?

First, you need to have fontconfig support enabled in adesklets. See the
config.log from the configuration phase to verify it. If you did not keep the
log, you can also look at the dynamic libraries linked against the interpreter.
On a system with GNU binutils, you can do something like:
@example
ldd `which adesklets` | grep fontconfig
@end example
If you get output similar to:
@example
 libfontconfig.so.1 => /usr/lib/libfontconfig.so.1 (0x45c75000)
@end example
it means everything is fine. Otherwise, you should recompile 
@command{adesklets} from source. From there, you can use the line:
@example
echo 'list_font_path' | adesklets :
@end example
to see all the font directories that adesklets will into look for TrueType
fonts.  Consult your fontconfig documentation to learn how to change this
(on up-to-date systems, @code{man 5 fonts-conf} is a good starting point).
Similarily:
@example
echo 'list_fonts' | adesklets :
@end example
Will give you all the fonts that are currently found... Keep in mind when
typing them that font names are case-sensitive.

Alternatively, if you just cannot get fontconfig to work, a way to get around
the problem would be to create symbolic links to the fonts you want to use
inside any absolute font paths listed by the command
@code{echo 'list_font_path' ...} above.
@ifhtml
@node Python package documentation
@appendix Python package documentation

Here are links to significant sections of the Python package documentation:

@itemize
@item @weblink2{adesklets,../pydoc/adesklets.html}
@item @weblink2{adesklets.events_handler,../pydoc/adesklets.events_handler.html}
@item @weblink2{adesklets.commands,../pydoc/adesklets.commands.html}
@item @weblink2{adesklets.utils,../pydoc/adesklets.utils.html}
@item @weblink2{adesklets.configfile,../pydoc/adesklets.configfile.html}
@end itemize

@end ifhtml

@node Imlib2 documentation
@appendix Imlib2 documentation

Carsten Haitzler (@email{raster@@rasterman.com}) took the time to produce very
nice cross-referenced documentation for Imlib2, but for some reason (size
considerations most probably), it is not included in the Imlib2 source
tarball@footnote{Although it can be quite easily regenerated using doxygen.}.
You can
@ifhtml
have it @weblink2{here,../imlib2}.
@end ifhtml

@ifnothtml
find it online at @weblink{http://adesklets.sf.net/doc/imlib2/}.
@end ifnothtml

Most functions of the Imlib2 API have corresponding, homonymic commands
in @command{adesklets}. @xref{Programming adesklets}, for specific details
on the transition from direct Imlib2 programming in C to adesklets.

@node Packaging GNU Makefile for desklets
@appendix Packaging GNU Makefile for desklets

Here is a convenient Makefile that automates the packaging of new or 
existing desklets on a GNU system. Just copy the Makefile below 
into @file{GNUmakefile} from your base desklet directory to use it. 
There is nothing at all to edit, provided you named your base directory
in a proper 'NAME-MAJOR.MINOR.REVISION' fashion, such as @code{beast-0.666.0}.

@verbatiminclude ../utils/GNUmakefile.desklet

@node Submitting a desklet

@appendix Submitting a desklet

@section Desklet package requirements
Requirements for ``official'' desklets packages are scarce; authors are free to
do as they wish. There are only two things that should be enforced:
@enumerate
@item A meaningful @file{README} file should exist in the base source directory 
of the desklet archive and be kept up to date. It should at least contain:
@itemize
@item the name and contact email adress of the author@footnote{It is probably 
not a good idea to give away your private email adress here; 
for spam-related reasons, you should probably open an account 
on @weblink2{SourceForge,http://sourceforge.net/}, or at another similar place 
with a serious spam containment infrastructure.}
@item a short description of the desklet
@item the requirements for running it
@item how to run it
@end itemize
@item The package should be a bzip'ed tarball containing a single source
directory of the form @code{NAME-MAJOR.MINOR.REVISION}, where @code{NAME} is 
the desklet base name, and @code{MAJOR.MINOR.REVISION} the version. Please note
that a makefile (@xref{Packaging GNU Makefile for desklets}.) is also provided
to automate creation of such an archive on GNU systems.
@end enumerate

@section The @command{adesklets_submit} script

Starting in @command{adesklets} 0.4.4, desklet authors are provided with a 
Python script to automate the submission of their desklets: 
@file{utils/adesklets_submit} from the source package. Use the 
@code{--with-python-install-submission-scripts} option at configuration time
to place it in your @code{bindir} directory upon installation.

@file{adesklets_submit} can be used to:
@itemize
@item Submit a new or updated desklet description for inclusion on the
@weblink2{adesklets web site,http://adesklets.sf.net/desklets.html};
@item Submit a bzip'ed desklet archive for inclusion in SourceForge's desklets
package (this is optional--you may choose to host it yourself).
@end itemize

@section Invoking @command{adesklets_submit}
Desklet submission is initiated by sending a specially crafted email to 
@email{adesklets@@mailworks.org}@footnote{It is useless to send anything else 
to this address; all messages that cannot be parsed by the automatic reception
script are just silently dropped. Write to @email{syfou@@users.sourceforge.net}
instead if you want to get in touch with the maintainer.}.
The @command{adesklets_submit} script assits you in the construction of
such an email using the user configuration file @file{$HOME/.adesklets_submit}
and the command line switches. Here is an example of a valid
@file{$HOME/.adesklets_submit} configuration:

@verbatiminclude ../utils/adesklets_submit.example

This is pretty self-explanatory, but here are a few less obvious points:

@itemize
@item
Try to avoid using pseudonyms and nicknames for the @code{author_name} as much
as possible, unless, of course, you already have a pretty well-established
online identity under this name.
@item
@code{send_confirmation} specifies if an email should be sent back to your 
@code{author_email} address whenever your desklet is succesfully published. 
If the submitted entry is rejected, you will always be written back anyway
with an explanation. Usually, the maintainer will not try to make changes to
problematic entries; it will only summarize back to the author what was not OK.
@item
@emph{Double check} your @code{author_email} address, since this is the only
one the maintainer will try to use when contacting you, regardless of what 
the headers say. Failing to supply a valid address will cause all messages to
fail to be sent to you, and all new desklet entries will be rejected.
@item
You can very well use adesklets_submit without any prior contact with the adesklets
maintainer (either via email, within the forum using this adress for
registration, or through the mailing list), but some back and forth will be
needed before publication just to assert your identity and its effective
relation to the provided email address.
@item
@code{desklets} is a dictionary of dictionaries (one dictionary per desklet, 
desklets' names being the keys); all the items referring to files (thumbnail,
screenshot and download) could either be publicly accessible URI's (this is the
preferred method), or local files, either absolute or relative to your $HOME
directory. In that case, needed files will be attached to the generated
multipart email.
@item
All images will always be fetched and integrated on the adesklets.sf.net
web site; you can safely remove them from your online location afterwards 
if you provided live URI's.
@item
When updating already included desklets, there is no need to submit back
the @code{thumbnail} or @code{screenshot} images if they did not change;
you can just as easily reference the already installed images on SourceForge:
@itemize
@item The @code{thumbnail} is always stored under @code{http://adesklets.sf.net/images/NAME_thumb.[jpg|png]}
@item The @code{screenshot} is always stored under @code{http://adesklets.sf.net/images/NAME_screen.[jpg|png]}
where @code{NAME} is the name of the desklet.
@end itemize
@item
Using the @code{host_on_sourceforge} value, you can choose to have 
your desklet package either hosted on SourceForge or just referenced 
on your site if you provided a URI. Of course, choosing this last 
alternative also means you will need to keep it in place.
@item
The @code{thumbnail} image should be a JPG (preferably) or PNG (if you 
@emph{really} need higher resolutions) of dimensions lying between 190x35 and 
230x110 pixels.
@item
The @code{screenshot} image should be a 640x480 JPG (preferably) or PNG.
It should put your desklet in evidence, and thus contain no other ones.  
@item
You can choose not to submit thumbnails and/or screenshots. In that case,
default, generic images will be used instead.
@item
@code{Category} is unused for now, and just ignored.
@item
All emails weighing more than 300 KB will be rejected by the maintainer's
email server; thus, adesklets_submit will refuse to generate them. Instead of
submitting such big entries, use the URI facility described above to trim
them down.
@item @command{adesklets_submit} does not enforce the requirements above; it only
checks what is strictly required to build a compliant submission email:
the existence of dictionary entries, availability of files, the validity 
of file types if they are local... It is your duty to make sure the entries
meet the other requirements if you want to avoid rejection.
@end itemize

For example, Belial Leviathan would fisrt check his @code{beast} desklet's
entry by doing something similar to:
@example
adesklets_submit beast
@end example

If everything goes fine, it will output the resulting submission email 
on @code{stdout}. From there, Belial can either:
@itemize
@item Pipe it to his favorite MTA (mail transfert agent) to send it to
@email{adesklets@@mailworks.org}.
@item Make @command{adesklets_submit} send it itself by SMTP, using the
@code{smtp_host} and @code{smtp_port} parameters in its 
@file{$HOME/.adesklets_submit}. For this, Belial would use:
@end itemize
@example
adesklets_submit --send beast
@end example

One last thing: you should try to avoid sending minor corrections multiple
times, especially if you use local files.  It both adds to the workload of the
maintainer's email server and to the management work. Please try to create a
valid entry @emph{then} send it, not the other way around.

@subsection Further submission validation using @command{adesklets_checkin}
From @command{adesklets} 0.4.5, you now have access to the 
@command{adesklets_checkin} script as well. This is the Python 
script that the maintainer uses for checking in all submissions.
@emph{Be aware that this script is only provided to desklet authors as a
convenience, to lower their submission rejection count--developers are in no
way forced to use it, and may even be unable to do so, since the script was not
written with portability in mind as adesklets_submit was. Look at the script 
header for a complete list of requirements.}

@command{adesklets_checkin} has two modes of operation: interactive and 
non-interactive. Only the non-interactive mode will interest desklet authors.
In this mode, usage is fairly simple. Belial, for instance, would do:
@example
adesklets_submit beast | adesklets_checkin
@end example

If everything goes fine, an output similar to this will be produced:
@example
Validation started. Please wait.
Everything seems fine, but keep in mind a few things cannot be
verified without human intervention. See documentation for details.
@end example

If not, you will get an exception trace with some (hopefully) meaningful 
explanations. 

@subsection Limitations of @command{adesklets_checkin} in non-interactive mode

Here are the remaining problems that @command{adesklets_checkin} 
cannot detect and thus must absolutely be solved manually
(the maintainer would interactively catch most of them, and you would have to
resubmit anyway):
@itemize
@item
Incomplete README file in base directory (Does it contain all the details
enumerated above?).
@item
Out-of-date README file (Does its content reflect the current state
of the desklet?).
@item
Desklet fails to run out-of-the-box (i.e. with or without minimal
configuration) when requirements in the README file are met and special
instructions are followed.
@end itemize

@node Copying This Manual
@appendix Copying This Manual

@menu
* GNU General Public License::  License for copying this manual.
@end menu

@include gpl.texi

@node Open PGP Public Key
@appendix Open PGP Public Key

@verbatiminclude syfou.asc

@noindent You can also get this certificate from many public key servers on 
the internet, such as @weblink{http://www.keyserver.net/}, or
@weblink{http://pgp.mit.edu/}. Contact its rightful owner,
Sylvain Fourmanoit, by email at @email{syfou@@users.sourceforge.net} 
to arrange further key validation if you need any.

@node Index
@unnumbered Index

@printindex cp

@bye