1 \input texinfo @c -*-texinfo-*-
2 @comment %**start of header
3 @setfilename adesklets_en.info
4 @include version_en.texi
5 @settitle adesklets @value{VERSION}
7 @comment %**end of header
9 This manual is for adesklets (version @value{VERSION}, @value{UPDATED}).
11 Copyright @copyright{} 2004, 2005 Sylvain Fourmanoit
12 @email{syfou@@users.sourceforge.net}.
14 Various corrections and updates by Mike Pirnat
15 @email{exilejedi@@users.sourceforge.net}.
18 Permission is granted to copy, distribute and/or modify this document
19 under the terms of the GNU General Public License, Version 2 or
20 any later version published by the Free Software Foundation.
21 A copy of the license is included in the appendix entitled
22 ``Copying This Manual''.
27 @c Define useful weblink macro
38 @c Define weblink2 macro: a variation on the previous one
39 @macro weblink2{desk,link}
51 * adesklets: (adesklets). Another desklets container.
56 @subtitle for version @value{VERSION}, @value{UPDATED}
57 @author Sylvain Fourmanoit (@email{syfou@@users.sourceforge.net})
58 @author Mike Pirnat (@email{exilejedi@@users.sourceforge.net})
60 @vskip 0pt plus 1filll
71 Follow those links for documentation in other languages
72 (@xref{Top,French version, About adesklets, adesklets_fr,}.).
75 @weblink2{[French version],../fr/index.html}
84 * Installing adesklets::
86 * Programming adesklets::
87 * Extending adesklets::
89 * Frequently asked questions::
91 * Python package documentation::
93 * Imlib2 documentation::
94 * Packaging GNU Makefile for desklets::
95 * Submitting a desklet::
96 * Copying This Manual::
97 * Open PGP Public Key::
101 @noindent The current version of this document can be found online at
102 @weblink{http://adesklets.sf.net/}.
104 @noindent Screenshots, source tarballs, etc. can also be found on
105 the project home page: @weblink{http://sf.net/projects/adesklets/}.
107 @node About adesklets
108 @chapter What is adesklets?
110 @section Short answer
112 @command{adesklets} is an interactive
113 @weblink2{Imlib2,http://www.enlightenment.org/pages/imlib2.html} console
114 for the X Window System. It provides scripted languages with a clean and
115 simple way to write great looking, mildly interactive desktop integrated
116 graphic applets (aka ``desklets'').
118 It can also be used as a command line oriented graphic editor, a bit similar
119 to @weblink2{ImageMagick,http://www.imagemagick.org/}, but with different
124 @command{adesklets} stands for ``another desklets [container]''. It was
125 written as an alternative to other programs such as:
129 gDesklets (@weblink{http://gdesklets.gnomedesktop.org/})
131 SuperKaramba (@weblink{http://netdragon.sourceforge.net/}).
133 GKrellM (@weblink{http://www.gkrellm.net/})
136 Since this is 'a'desklets, others still have plenty of space to start similar
137 projets, from 'b'desklets to 'z', excluding 'g', which is already taken.
139 Seriously though, all those packages are nice. Nevertheless, the first two
140 have very heavy requirements in terms of library dependencies; basically,
141 gDesklets still requires a fair part of the GNOME environment to be installed
142 (plus specialized libraries such as gnome-python@footnote{A report on this has
143 been produced; you may find it online in PDF format at
144 @weblink{http://adesklets.sf.net/verbatim/gdesklets.pdf}.}), while
145 SuperKaramba needs almost all of the KDE libraries and base environment.
146 This also reflects on performance for the task at hand@footnote{Of course, this
147 is only the author's opinion--and both applications are making big progress on
148 resource efficiency from version to version.}. On the other hand, while GKrellM
149 is significantly lighter (it still depends on GTK+ though), it does not deliver
150 the same experience in terms of ``eye-candiness'' (to the author's taste, of
151 course) or ``scriptability'' than the other two.
153 Thus, @command{adesklets} was born. It provides:
157 a minimal framework for X Window desklets seamlessly integrated into the
158 desktop, with an easy to use central management for starting, positioning
161 a generic, rich and easy to use drawing API similar to gDesklets and
162 SuperKaramba regarding its high visual quality, thanks to the Imlib2 library.
164 very limited library dependencies: uses the very good (and lightning fast)
165 Imlib2 library for all graphic-related operations. No window toolkit used
166 whatsoever; the program relies directly on xlib.
168 a light, robust and small interpreter potentially usable with all sorts of
169 scripting languages thanks to a clean, limited and homogenous syntax. As
171 @value{VERSION}, support for Python is provided out of the box. Future support
172 for Perl and Ruby is planned. Feel free to contribute support for your
175 Minimal disk space, memory footprint and CPU usage. Typically, on glibc 2.3.4
176 Linux 2.6 x86, a unique executable is less than 130 KB on disk, takes less than
177 3 MB of virtual memory per desklet right after initialization, and almost no
178 processor cycles (including cycles from a Python interpreted script) when idle.
185 A sophisticated window API, or even access to widgets besides bare, ugly grey
186 menus. You clearly cannot write any GUI application with this--only
189 Convoluted mechanisms (or just plain mechanisms, for that matter) for
190 script configuration. Script developers are free (or doomed, depending on how
191 you see things) to do whatever they see fit.
193 Support for everything that is not a truly POSIX compliant system. For
194 instance, it would be very surprising if this would ever compile on Cygwin.
196 Feature-rich management of user events. @command{adesklets} aims at low
197 resource consumption and reliability; only a small set of events, mainly
198 pointer-related, are exposed through its API.
204 @heading What's new in version 0.4.11
205 This is a bug fix release. Documentation wize, it brings the french
206 documentation up to speed with the english version (thanks to Martin
207 Kirchgessner @email{martin.kirch@@gmail.com} for all his work), and take
208 the whole documentation source and html
209 version out of the main package (thanks to this, adesklets is now about 300 KB
210 lighter). Code wize, this version includes many small fixes for various platforms
211 -- FreeBSD 7 should hopefully be supported unpatched, manuals have been added
212 for desklets submission script to please Debian. Yet, the biggest change is
213 probably the inclusion of an optional shell driver to the interpreter, that
214 ease up the administration of adesklets and the quick adaptation of the code
215 to new windows managers.
217 @heading What's new in version 0.4.10
218 This is a bug fix release. An unwanted partial new feature made is way
219 into previous release: it caused the contextual menu to stop working
220 the advertised way (the control key needed to be pressed for the menu to
221 get fired). This release just revert back the change, and add a
222 configuration-time option, --enable-control-on-context-menu, for
223 those who really wants this behavior.
225 @heading What's new in version 0.4.9
226 This is a bug fix release. It changes the global macro definitions for
227 adesklets to compile without problems on FreeBSD 6.x, corrects an error
228 with debugging flag stripping from the C compiler, and adds a new demo
229 program about threading.
231 @heading What's new in version 0.4.8
232 This is a bug fix release. It changes the global macro definitions for
233 adesklets to compile without problems on FreeBSD 5.x, and it also adds
234 fake root window detection for KDE, thanks to yogi77, from the forum.
236 @heading What's new in version 0.4.7
237 This is a bug fix release. It removes calls to some C99 math routines not
238 available in earlier BSD's, making the code more portable. It also adds
239 two new commands to the API for handling the image caching mechanism better.
241 @heading What's new in version 0.4.6
242 This is a bug fix and documentation update release. It corrects many small
243 bugs inside the desklets submission process scripts, makes portability changes
244 to the autoconf structure, adds a new demo scripts in test (widget.py), corrects
245 the xwindow_move_window routine for a small placement bugs on the screen (thanks
246 to man1ed from the forum from providing the patch), and finally adds a new
247 appendix containing a handy online version of the Imlib2 documentation.
249 @heading What's new in version 0.4.5
250 This is a bug fix and documentation update release. It improves the desklets
251 submission process by releasing the full check-in script used by the maintainer.
252 It also solves a bug with window refresh when using user-defined background
253 image and menus; thanks to ZeroDivide for reporting this. Various updates and
254 corrections have also been made to the documentation.
256 @heading What's new in version 0.4.4
257 This is a documentation update release, principally aimed at desklet
258 authors. It basically includes a new appendix on how to submit a desklet
259 (including scripted support), and a new subsection on system-wide font
260 detection as well. The FAQ was also expanded to cover this topic.
262 @heading What's new in version 0.4.3
263 This is a documentation update release. Most of the work here was made by
264 Mike Pirnat @email{exilejedi@@users.sourceforge.net}, who was kind enough
265 to rectify the base author's deficient english by proofreading this manual
266 from cover to cover. Thanks Mike! The FAQ was also slightly expanded, and
267 a new appendix for desklets writer created.
269 @heading What's new in version 0.4.2
270 This is a new bug fix release. It corrects a bug within the Python package
271 that made it not compile on all versions of Python prior to 2.4.0. Thanks to
272 nucular, from the adesklets forum, for reporting this. It also corrects another
273 minor mmap-related issue in the same package.
275 @heading What's new in version 0.4.1
276 This is a new bug fix release. It secures the use of the optional
277 @code{adesklets.ConfigFile} class by completely changing
278 the way config files are imported, thus removing a potential
279 security exploit. Thanks to Mike Pirnat @email{exilejedi@@users.sourceforge.net}
280 for sharing his concerns on this issue.
282 @heading What's new in version 0.4.0
283 This is a new minor version release. The interpreter now supports
284 internationalization. It can now dynamically work with different
285 character sets on platforms supporting iconv (as standardized in UNIX98), and
286 display them in the right fashion. The Python package was also extended
287 to include an (optional) generic configuration class, hopefully useful
290 @heading What's new in version 0.3.2
291 This is a documentation update release. Documentation was added for Python
292 programmers, and the FAQ was slightly expanded.
294 @heading What's new in version 0.3.1
295 This is new bug fix release. It just adds support for interruption of time gates
296 by events. This is a feature absolutely required to make some timed effects
299 @heading What's new in version 0.3.0
300 This is a new minor version release. Portability has been a big concern for us
301 since the beginning; with this version, the package compiles and runs flawlessly
302 on FreeBSD and NetBSD (@xref{Portability}.). Event handling has also been
303 internally streamlined, and the Python binding was extended to support
304 dynamic modification of caught events (see @file{test/test_events.py}).
306 The interpreter API now exposes everything the author wanted,
307 and will probably not be expanded much further; everything is pretty much
308 in place to write any desklet, including animations.
310 @heading What's new in version 0.2.1
311 This is a minor bug fix release which removes a compatibility bug within
312 the GNU history library usage. Thanks to Mike Pirnat
313 @email{exilejedi@@users.sourceforge.net} for reporting this.
315 @heading What's new in version 0.2.0
316 This is a new minor version release. Support was added for textual variables
317 (string substitution, in fact), and execution of timed preregistered
318 sequences of commands to the interpreter (indirect mode of execution).
319 This gives desklets a way to perform fluid animations. Run the demo script
320 @file{test/fading.py} from the source package to see those features in action.
322 For developers, this version also includes a rewritten, dynamically
323 configurable debug interface to the interpreter able to generate complete
327 See @file{Changelog} for all details.
330 @c Sets up a marker for automated INSTALL file generation
332 @node Installing adesklets
333 @unnumbered Installing adesklets
336 @node Installing adesklets
337 @chapter Installing adesklets
340 @section Compilation Requirements
342 To compile adesklets from source, you will need:
346 A compiler supporting ANSI C plus variadic macros (about every version
347 of @weblink2{gcc,http://gcc.gnu.org} from 2.7.0 will do - or about
348 everything else published in the last ten years, for that matter)
350 @weblink2{X11,http://www.x.org/} libraries and
351 headers@footnote{Except for headless builds, useful
352 for server environments and such; read further for details.}
354 Imlib2 1.1.2 and up (the more recent the better; go and fetch it from
355 @weblink{http://sourceforge.net/projects/enlightenment/})
357 @weblink2{GNU readline,http://cnswww.cns.cwru.edu/php/chet/readline/rltop.html}
359 A reasonably POSIX-compliant system
362 @noindent It can also use, if present in the system:
366 @weblink2{fontconfig,http://www.fontconfig.org/}, for automated detection of
367 all usable fonts present in the system
369 @weblink2{GNU history,http://cnswww.cns.cwru.edu/php/chet/readline/rltop.html},
370 the faithful complement to GNU readline for command history support
372 iconv library and headers (such
373 as @weblink2{libiconv,http://www.gnu.org/software/libiconv/}), for
374 internationalization support (dynamic support of extended character sets)
376 @weblink2{Python,http://www.python.org} 2.3 and up, if you want Python support
377 (you most probably do at this stage as it's the only scripted language that's
381 The optional adesklets shell frontend, installed by default, will itself
382 need a few utilities, all expected to minimally comply with POSIX 1003.2 and
383 1003.2a specifications:
386 @item a sh-compatible @command{/bin/sh} shell
387 @item a Streaming EDitor (sed)
388 @item test, mkdir, rmdir, sleep, kill and ls
391 The @command{xwininfo} and @command{xprop} programs can also be used, if
392 a given fake-root window detection routine is explicitely invoked. Both
393 XFree86 and X.org implementations of these utilities have been tested.
395 @section Portability Notice
397 This package was built with portability in mind: all vendor-specific
398 extensions were avoided, and specs (ANSI, SVID 3, BSD 4.3, POSIX) were followed
399 in a conservative way. Nevertheless, original development took place on a single
400 Linux system; it is quite probable that adesklets will not compile or work as
401 expected in some cases. Fixing portability issues is an important concern for us.
403 adesklets has been ported and successfully tested by the developers on many
404 systems. As of version @value{VERSION}, it has been verified to compile and run
405 out of the box on a variety of
408 @item @strong{Kernels/Systems}: Linux (2.2, 2.4, 2.6 series), FreeBSD
409 (4.10, 5, 6 and 7), NetBSD (1.6)
410 @item @strong{C Libraries} (when applicable): glibc (2.1.3 and up), uclibc (0.9.28)
411 @item @strong{Compilers}: gcc (2.95.2, whole 3 serie, 4.0.1),
412 icc 7.0 (with tweaking)
415 At the time of writing, adesklets is already integrated in ports collections of
416 many BSD and software libraries of linux distributions. For reference, let's
420 @item Debian package: @weblink{http://packages.debian.org/unstable/x11/adesklets}, maintained by Bartosz Fenski @email{fenio@@debian.org}.
421 @item FreeBSD ports: @weblink{http://www.freshports.org/deskutils/adesklets/}, maintained by Roman Bogorodskiy @email{novel@@freebsd.org}.
424 Did you try to run the package on something not listed here?
425 Let us know, especially if it did not work.
427 @section Software download
429 The current version of the software (as a source bzip'ed tarball) can be found
430 on the SourceForge project page: @weblink{http://sf.net/projects/adesklets/}
432 You can extract it from the console with @command{tar}. As of version
433 @value{VERSION}, the command line would be:
436 tar xvjf adesklets-@value{VERSION}.tar.bz2
439 or, if your installed version of @command{tar} does not support
440 filtering archives through bzip2:
443 bzcat adesklets-@value{VERSION}.tar.bz2 | tar xv
446 @section Verifying Software Integrity (optional)
448 As of adesklets @value{VERSION}, you can also
449 download from @weblink2{SourceForge,http://sf.net/projects/adesklets/} an
450 ascii-armored detached signature named
451 @command{adesklets-@value{VERSION}.tar.bz2.asc}, that you can match
452 against the author's Open PGP public key (@pxref{Open PGP Public Key},
453 in appendix) to assert the package integrity. For instance, with
454 @command{GnuPG} (@weblink{http://www.gnupg.org/}), you would use:
457 gpg --verify adesklets-@value{VERSION}.tar.bz2.asc adesklets-@value{VERSION}.tar.bz2
460 You can also get the public key for @email{syfou@@users.sourceforge.net}
461 from various public key servers such as @weblink{http://www.keyserver.net/} or
462 @weblink{http://pgp.mit.edu/}. Feel free to contact the author directly if you
463 want to authenticate the key further.
465 @section Compilation and Installation:
467 adesklets provides the usual autoconf/automake scripts of GNU packages.
469 Therefore, in most cases, installation follows the normal three steps:
473 `cd' to the directory containing the package's source code and type
474 `./configure' to configure the package for your system. If you're
475 using `csh' on an old version of System V, you might need to type
476 `sh ./configure' instead to prevent `csh' from trying to execute
479 Running `configure' takes awhile. While running, it prints some
480 messages describing which features it is checking for.
482 Type `make' to compile the package.
484 Type `make install' to install the programs and any data files and
488 You can remove the program binaries and object files from the
489 source code directory by typing `make clean'. To also remove the
490 files that `configure' created (so you can compile the package for
491 a different kind of computer), type `make distclean'.
493 @section Compilers and Options:
495 Some systems require unusual options for compilation or linking that
496 the `configure' script does not know about. You can give `configure'
497 initial values for variables by setting them in the environment. Using
498 a Bourne-compatible shell, you can do that on the command line like
502 CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure
505 @noindent Or on systems that have the `env' program, you can do it like this:
508 env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure
511 @section Optional Features:
513 adesklets comes with a few optional features you can select or not
514 from the `configure' script. Type:
520 @noindent for a complete, short description. Here are a few interesting ones:
524 You may choose to compile adesklets without X support at all
525 (@command{--without-x}).
526 You will get a version that is obviously not suited for
527 desklets rendering, but still good for command line image manipulation
529 You can remove support for some others packages as well:
530 @command{--without-history}, @command{--without-fontconfig}
532 The shell frontend can be avoided altogether using:
533 @command{--disable-frontend-shell-driver}
537 @node Using adesklets
540 @chapter Using adesklets
546 @section ... As a desklets container
548 By itself, adesklets does little: it only provides what is needed to
549 do more! You either need to tell it what to do by passing it commands
550 (see the next section) or you need other scripts (the desklets)
551 that will drive it for you.
553 @noindent Right now, many desklets exist:
554 you may find them on adesklets web page as separate downloads:
555 @weblink{http://adesklets.sf.net/desklets.html}.
557 @subsection Add a new desklet to your X display
558 To add a new desklet script, simply:
562 Download its tarball and unpack it somewhere in your home directory
564 Look at the included README file; special requirements or instructions
565 will be given. Usually, all you have to do is to get adesklets installed,
566 your X server running, then launch the executable script file from the
570 @noindent Please note that:
574 Launching the same desklet script more than once will start multiple instances of it.
576 On multi-head displays, scripts will be launched on their inherited default
577 screen. (For instance, if you do nothing special, calling a script from an
578 xterm on screen 1 will launch the desklet on screen 1).
581 @noindent Most of the time, desklets scripts are made to run as long as you
582 do not tell them to quit. The user has total control of starting, stopping,
583 restarting (when possible), and positionning the desklet (using the context menu,
584 always available by right-clicking on the desklet). The desklet has
585 no control over those operations.
587 @noindent Those few user settings are stored in the @file{$HOME/.adesklets}
588 file. Usually, you do not want to edit this file yourself.
589 If you do, make sure no instances of @command{adesklets} are running at
592 @unnumberedsubsubsec Special notes on system fonts
594 @emph{You may safely skip this section if you do not intend to use
595 non-supplied fonts with adesklets.}
597 Provided your system supports fontconfig (@weblink{http://www.fontconfig.org/})
598 and adesklets was compiled without using @code{--without-fontconfig} (compiling
599 with fontconfig support is the default; @xref{Installing adesklets}.), all the
600 TrueType fonts present in your system are available for use with adesklets.
601 At initialization time, adesklets with fontconfig support compiled in will go
602 through all the fonts detected on your system to identify all the TrueType
603 fonts. See your fontconfig documentation on how to set up your application
604 fonts access properly (@xref{Frequently asked questions}, for some fontconfig
605 debugging hints). It's also good to know that adesklets' package includes a
606 copy of Bitstream's Vera font; all users can rely on @command{adesklets}
607 having at least this font available at all time.
609 @unnumberedsubsubsec Special notes on internationalization
611 @emph{You may safely skip this section if you do not intend to use
612 extended charaters within your desklets.}
614 If your system includes @command{iconv} support (@xref{Installing adesklets}.),
615 you should be able to use any character from any charsets your system
616 knows about for displaying text, either inside a desklet or in its menus,
617 provided you have appropriate TrueType fonts (i.e. TrueType fonts containing
618 those character representations)@footnote{For instance, Bitstream's Vera font
619 included with @command{adesklets} contains glyphs for practically all Latin-1
620 (ISO-8859-1) characters.}.
622 Nevertheless, when using extended (outside 7-bit @code{ASCII}) characters,
623 you need to make sure your local GNU readline settings do not interfere. These
624 three parameters should be set as indicated below in the appropriate
625 @file{initrc} file@footnote{Please refer to your GNU readline documentation}:
633 If you do not want to adapt your GNU readline settings, you can also pass the
634 @code{--enable-force-extended-characters-input} switch to the @code{configure}
635 script when configuring the package from source, which will cause those three
636 variables to always be appropriately overriden internally by the interpreter.
638 Of course, you will also need desklets built to use those extended characters.
639 At the time of writing, all non-contributed Python desklets support them; for
640 those, the charset can be set by the user in the configuration file, when it
641 exists@footnote{When it does not exist, it means the desklet does not need
642 internationalization anyway}; users merely have to set the 'coding' line
643 appropriately@footnote{See @weblink{http://python.fyxm.net/peps/pep-0263.html}
644 if you need details.}.
646 For instance, for using ISO Latin-1 characters, one should use something
650 # -*- coding: ISO-8859-1 -*-
653 as the first or second line in the Python desklet configuration file@footnote{
654 Obviously, such a configuration file needs to be saved using ISO Latin-1
655 encoding or any subset of it, such as @code{ASCII}.}.
657 Finally, please note that if your platform does not support iconv,
658 you should always leave the coding parameter to @code{ASCII}, otherwise
659 you will get fatal errors such as @code{charset conversion not compiled in}
662 @subsection Restore previously running desklets on new X session
663 Invoking @command{adesklets} without any arguments@footnote{A word of warning:
664 by default on adesklets 0.4.11 and up, you @emph{need} to employ some flags if
665 your Window Manager uses a fake root window. @xref{Frequently asked questions}.}:
671 @noindent is enough to restart all desklets that were running the
672 last time you killed the X server (in this mode, @command{adesklets}
673 will exit quickly by itself: there is no need to run it in the
674 background. adesklets does not use a daemon; each applet will fork a
675 standalone @command{adesklets} interpreter as a child process).
676 Invoking @command{adesklets} when desklets are already running
677 will cause them to be killed before the creation of new
678 instances@footnote{Both @command{adesklets} process and their immediate parents
679 will be sent a @command{SIGKILL} signal.}.
681 @noindent If you plan on using desklets on a regular basis, you should put
682 the previous @code{adesklets} command somewhere in your X session
683 initialization. I cannot tell you where with precision, as it varies greatly
684 from system to system. Have a look at:
685 @weblink{http://www.google.ca/search?q=''x window''+startup} for general help.
687 Since adesklets 0.4.11, a more complete shell based frontend is available
688 to you, if you installed it (which is the default). It gives you a more
689 feature-complete set of options. Run
695 To see what is at your fingertips.
697 @section ... As a command-line graphic editor
699 You can also use adesklets as a command-oriented graphic editor.
700 If you type, in a console:
706 @noindent You will get something similar to:
710 adesklets 0.1.0 (Fri Jan 28 19:09:13 EST 2005), on Linux 2.6.10
711 [gcc 3.4.3 20041125 (Gentoo Linux 3.4.3-r1, ssp-3.4.3-0, pie-8.7.7)]
716 @noindent The last line is a prompt. It tells you you are ready
717 to enter command number 0. As of adesklets @value{VERSION}, you have around
718 150 commands at your fingertips. Thanks to GNU readline, a lot of
719 autocompletion hooks are present, giving you an easy way to look around.
720 Press TAB while typing a command name or a command's first argument, and
721 useful information will be displayed. @xref{primer,,an adesklets's primer},
724 @node Programming adesklets
725 @chapter Programming adesklets
726 @section An adesklets' primer
729 As previously stated (@xref{About adesklets}.), adesklets is basically an
730 interactive Imlib2 console, with one or two aditionnal features:
734 When an X display is present, automated management of a single window
736 Automated support for pseudo-transparency
738 Management of long-running applets
741 @noindent So let's start a typical interactive session to see what
742 happens. Under X, open a terminal, and type:
748 @noindent As in last section (@xref{prompt,,'Using adesklets as a command-line
750 you will get a prompt. Now, enter the command '@code{images_info}'. You should
755 id 0 width 1 height 1 alpha 1 filename (null)
756 id 1 width 1 height 1 alpha 1 filename (null)
757 command 0 ok: images_info
760 @noindent This tells you that you have two images: image 0 and image 1, each
761 1x1 pixels. Those are the only images you can never destroy nor do any
762 operations you want with (resize them independently, flip them diagonaly, etc.)
767 Image 0 is the foreground image. By default, it is the only image that is
768 displayed on the single window that @command{adesklets} manages.
770 Image 1 is the background image. By default, it always contains the content
771 of the root window (the desktop) directly below the window. Unless we set it
772 to be otherwise, it is always updated when the user moves it, when you resize
773 it, when your wallpaper changes, etc.
776 @noindent But where is this window? Well, right know, it is only 1x1 pixels,
777 and it is not shown@footnote{``Mapped'' in X Window lingo} on the screen.
778 So let's resize it to 100x100 pixels: type '@code{window_resize 100 100}'.
779 Now, if you re-enter the command '@code{images_info}', you will get:
783 id 0 width 100 height 100 alpha 1 filename (null)
784 id 1 width 100 height 100 alpha 1 filename (null)
785 command 2 ok: images_info
788 @noindent The foreground and background images have been resized to
789 100x100 pixels. Moreover, the background image has been updated to contain
790 a new image of the background. Now, let's make this window visible. Type two
791 commands: '@code{window_reset managed}' and then '@code{window_show}'.
793 @noindent The first command tell adesklets to let your window manager
794 ``manage'' your window (the default is not to); it means the window gets
795 decorated, and you can interactively change its visibility@footnote{An
796 ``unmanaged'' window is very useful for scripted desklets: it looks like
797 it is part of the root window as it can be made to never go on top, and to stay
798 mapped when workspaces are switched.}. The second command shows our 100x100
799 window. So far, it's nothing too impressive--just a black 100x100 square with a
800 titlebar and fixed-size borders.
802 @noindent As mentioned above, only image 0 (the foreground) is displayed by
803 default. Now, type: '@code{window_set_transparency 1}'. Wow! We see the
804 root window below! With ``window transparency'' on, the image 1 (background)
805 is first copied onto the window, then image 0 (foreground) which is purely
806 transparent black, is blended onto it@footnote{Well...Not quite. Actually,
807 there is a buffer involved for performance, but the operation is logically
808 equivalent to this description.}.
810 @noindent It is time to say a word about colors. Remember, adesklets is an
811 Imlib2 console. Thus, as with Imlib2@footnote{Keep your Imlib2 documentation
812 nearby; it is very handy! @xref{Imlib2 documentation}.}, colors are
813 always true 32 colors, RGBA encoded, with eight bits (0 to 255) per channel,
814 including an alpha channel for transparency. Palette conversion and such will
815 automatically take place if your screen depth is less than that, so you do not
816 need to bother with that. If you type: '@code{context_get_color}', you will get:
819 command 0 ok: context color 255 255 255 255
822 @noindent Imlib2 is a kind of state machine; as such, it comes with a
823 ``context'' that remembers a series of attributes it will use in its future
824 operations. For instance, we now know the color it will use as long as we do not
825 modify it is opaque pure white (red=255, blue=255, green=255, alpha=255). If we type: '@code{context_get_image}', it returns:
828 command 0 ok: context image 0
831 @noindent Which means all window operations we perform are made directly on
832 the forgeground image. So, let's draw a filled semi-transparent magenta
833 rectangle on the foreground. Commands could be:
834 '@code{context_set_color 255 0 0 200}' and
835 '@code{image_fill_rectangle 25 25 50 50}'. Neat, isn't it?
837 @noindent If you are used to Imlib2 programming, you will have noticed
838 by now those last few commands look quite familiar. This is pretty normal;
839 most of Imlib2 C functions are presented as corresponding 'commands' in
840 adesklets. This way, adesklets' command '@code{image_fill_rectangle}'
841 follows the same semantic as Imlib2's '@code{imlib_image_fill_rectangle()}'
842 function, the command '@code{context_set_color}' functions just like
843 '@code{imlib_context_set_color()}', etc. The only two significant (and
844 systematic) differences are that whenever you would use an
845 '@code{Imlib_Something}' object in C, you use an integer ID with adesklets,
846 and on the semantic of the '@code{imlib_free_something()}' functions that need
847 to be given an ID instead of freeing the context selected object of this type.
849 @noindent This is pretty easy to illustrate. Let's load the ``Vera'' font
850 included with adesklets at a 20pt size, set it as default font, and write in
851 pure opaque white ``Hello'' diagonally on the foreground image from the top left
852 corner before unloading the font. It would look like:
855 6 >>> load_font Vera/20
856 command 6 ok: new font 0
857 7 >>> context_set_font 0
858 command 7 ok: context_set_font 0
859 8 >>> context_set_direction text_to_angle
860 command 8 ok: context_set_direction text_to_angle
861 9 >>> context_set_angle 45
862 command 9 ok: context_set_angle 45
863 10 >>> context_set_color 255 255 255 255
864 command 10 ok: context_set_color 255 255 255 255
865 11 >>> text_draw 0 0 Hello
866 command 11 ok: text_draw 0 0 Hello
868 command 12 ok: free_font 0
871 @noindent If you look at your imlib2 documentation, you will immediatly notice
872 the two differences we just talked about: all references to the font Vera/20
873 are made through an integer ID (0 here), and the '@code{free_font}' command,
874 unlike the corresponding '@code{imlib_free_font()}' function, is called with
875 the font ID as an argument instead of the context font.
877 @noindent Now let's say you want to save you resulting image; not a problem!
878 Let us type: '@code{save_image out.png}', and the foreground is saved in the
879 file ``out.png'' in the current working directory@footnote{For this to work,
880 you need to have your Imlib2 installation properly configured for using libpng,
881 or you could receive a ``no loader for file format'' error.}. Now, just for
882 the sake of it, let us exit adesklets, and start another interactive session
883 to see if we can reload this image. Just type in the ``@code{quit}'' command or
884 press ^D (Control D: end of file). Then your new session should look something like:
887 0 >>> window_resize 100 100
888 command 0 ok: window_resize 100 100
889 1 >>> window_reset managed
890 command 1 ok: window_reset managed
891 2 >>> window_set_transparency 1
892 command 2 ok: window_set_transparency 1
893 3 >>> load_image out.png
894 command 3 ok: new image 2
895 4 >>> blend_image_onto_image 2 1 0 0 100 100 0 0 100 100
896 command 4 ok: blend_image_onto_image 2 1 0 0 100 100 0 0 100 100
898 command 5 ok: window_show
900 command 6 ok: free_image 2
903 @noindent Of course, we wanted to visualize the result; this is why we
904 emitted commands '@code{window_reset}', '@code{window_set_transparency}'
905 and '@code{window_show}'; they are not otherwise useful. The command
906 '@code{blend_image_onto_image}' comes straight from Imlib2 once again;
907 it takes the newly created image 2 from the third command and blends it
908 onto the context image (image 0, foreground by default), for its coordinates
909 (0,0) to 100x100 pixels farther, and puts it on the rectangle starting at (0,0)
910 of size 100x100 pixels of image 0. It is finally good to note that, with
911 adesklets, there is always an image in Imlib2 context: whenever you try to
912 free the current image, the image context is always reset to the foreground
915 @noindent OK, so it is almost the end of this primer... From there you should
916 play around with adesklets. It is pretty straightforward to use if you are
917 already familiar with Imlib2. If you are not, your best resource is certainly
918 having Imlib2 documentation not far away. :-)
920 @noindent Some last tips:
924 If you get tired of typing, and typing, do not forget you have autocompletion:
925 'TAB' your problems away!
927 If you want to have hints on how to do something, you have a built-in
928 '@code{help}' command.
930 If you are working out a series of commands, things are not working
931 and all this interactive usage it getting tiresome:
934 Use the '@code{history}' command to output your current session to a
935 file@footnote{For this to work, you need to have GNU history when
936 building adesklets.}.
938 Use the '-f' switch with adesklets to get commands from a file instead
941 If you try to visualise something, insert a '@code{pause}' command at the
942 end of the script to freeze the interpreter.
944 All strings from a pound sign '#' to the end of a line will get discarded,
945 allowing you to write comments.
949 @noindent Here is an example:
952 #!/usr/bin/env adesklets -f
954 # Make the window 'managed'
958 # Resize the window to 100x100 pixels
960 window_resize 100 100
962 # Show the window, then freeze for 10 seconds before exiting
968 @noindent You will just have to make this script executable and run it. As
969 usual, output from the commands will get printed to stdout.
972 @item You could also use the @code{play} command. This two-arguments command
973 gives you a way to replay any sequence of commands from history, using the
974 command number of the first and last command as parameters.
977 @section Real programming with adesklets: writing desklet scripts
979 When you are ready for real work@footnote{:-)}, you might want to use
980 a real scripted language instead of the raw @command{adesklets} interpreter we
981 used in the primer; you never know when just having variables could come in
984 At the time of this writing (@value{UPDATED}), the Python package is included
985 @footnote{adesklets was written to be easily used from a variety of interpreted
986 languages; future plans includes wrappers for Perl and Ruby--do not hesitate
987 to propose your help if you want to speed things up!}, and the Perl 5 binding
990 @subsection General tips for programmers
992 A really useful feature of the @command{adesklets} interpreter
993 is its ability to produce a full trace of its session (commands, events and
994 special messages), either on @code{stdeerr} or as a log file, independently
995 of what is driving it. To have access to this feature, one must:
998 @item Configure the package from source, passing along the @code{--enable-debug}
999 switch to @code{configure}.
1000 @item Export the @code{ADESKLETS_LOG} variable in the environment if
1001 the session's output should to be stored in files instead of printed
1002 to @code{stderr}@footnote{Printing to @code{stderr} will break most bindings,
1003 and should therefore be used mainly when invoking the interpreter directly
1004 from the console.}. It should be an absolute filename prefix which the
1005 interpreter, inheriting from the environment, can use to create complete file
1008 From there, it is possible to read complete chronological session logs;
1009 used correcly, it is very useful for debugging purposes. You can use
1010 it in conjunction with the @code{echo} command to set easy to find log points.
1012 @subsection adesklets and Python
1013 @unnumberedsubsubsec Python usage example
1014 From Python, things are not very different than from the interpreter.
1015 Commands have been wrapped into Python functions, and an @code{Events_handler}
1016 class has been made public to handle asynchronous feedback from the
1017 interpreter. Let's have a look at the @file{test/test.py} script from the
1018 source tarball of version @value{VERSION}:
1020 @verbatiminclude ../test/test.py
1022 That's it! Twenty-six lines of Python code, and we have a perfectly functionnal
1023 desklet. I think things are pretty self-explanatory; have a look at the
1024 Python online help for @code{adesklets}, @code{adesklets.commands} and
1025 @code{adesklets.Events_handler} for a good, complete explanation
1027 (@xref{Python package documentation}.)
1029 . All we do here is:
1033 Import the @code{adesklets} package:
1034 this automatically instantiates a child @command{adesklets} process and sets up
1035 all communications. When the package initialization returns without raising
1036 any exception, it means the interpreter is up and ready to accept commands.
1038 Subclass @code{adesklets.Events_handler} and redefine the methods invoked
1039 for the events we are interested in (all other events are not just ignored,
1040 they are not generated).
1042 Instantiate an object of this class, and put it on hold indefinitely
1043 @footnote{This last step is not mandatory; the script may very well continue,
1044 but it should be written so that it supports signal interruptions. See
1045 @code{help(adesklets.Events_handler)} for further explanations}.
1048 @unnumberedsubsubsec Gotchas: a bit more about object IDs
1050 All adesklets objects (fonts, images, color ranges, polygons, etc), are stored
1051 in stacks (one stack per object type). Python's ID's are nothing more than the
1052 initial position of given objects inside the relevant stack, and therefore
1053 will become invalid if an object of the same type below them gets freed.
1055 For instance, if we start with a clean state, all we have in the stack of
1056 images is the window's foreground (ID 0) and background (ID 1).
1057 When someone creates two other images from Python like so:
1059 im_1 = adesklets.create_image(10,10)
1060 im_2 = adesklets.create_image(10,10)
1062 @noindent We get @code{im_1==1}, and @code{im_2==2}. Whenever someones does:
1064 adesklets.free_image(im_1)
1066 @noindent The stack starts collapsing, and what was once image 3 (@code{im_1})
1067 is now image 2, and @code{im_2} is now an invalid reference. This clearly means
1070 adesklets.free_image(im_2)
1072 @noindent would generate an @code{image out of range} error message.
1074 @unnumberedsubsubsec Special subject: animations
1076 @command{adesklets} now includes an indirect mode of execution and textual
1077 variables (non-recursive textual replacements, to be precise) as well.
1078 This means desklets writers have what is needed to create precisely-timed
1079 animations. You can find an easy-to-follow example in @file{test/fading.py}.
1080 A somewhat more involved use of these features is also made in the @code{yab}
1081 desklet. To realize an animation from Python, one should:
1084 @item @strong{Record} a sequence of commands
1085 (we will call it a macro command, or macro for now on). From Python, this
1086 involves toggling on indirect mode using the @code{adesklets.start_recording()}
1087 function, emitting an undetermined number of @command{adesklets} commands,
1088 then toggling back into normal mode (direct execution) with
1089 @code{adesklets.stop_recording()}. Of course, no command is ever evaluated
1090 while the interpreter is in indirect mode; commands are only stored in the
1091 history for future replay.
1092 @item @strong{Set up} whether the to-be-replayed sequence of commands can be
1093 interrupted by events or not, using the @code{adesklets.play_set_abort_on_events()}
1094 function. The high-level @code{adesklets.Events_handler::set_events()} method
1095 can also be used to dynamicaly change what events are caught. See
1096 @file{test/test_events.py} for an example.
1097 @item @strong{Set up} the variables used within the recorded macro using the
1098 @code{adesklets.set()} function, very similar to its Bourne shell homonym.
1099 @item @strong{Play} the macro using the @code{adesklets.play()} function.
1102 Here are a few additional remarks:
1104 @item Precise timing during replay is achieved through the @code{time_gate}
1105 command. This works very simply: every time a macro replays, adesklets
1106 records its starting time, and whenever a @code{time_gate} command is
1107 encountered during the replay, it waits for the number of seconds given as
1108 an argument to @code{time_gate} to run out. For instance, specifing
1109 @code{time_gate 0.1} in a macro will make any subsequent commands within the
1110 macro not execute before the macro has run for at least a tenth of second.
1111 @item Variable expansion always occurs just before command execution, regardless
1112 of current interpreter mode (direct or indirect). All sequences of characters
1113 not containing spaces directly following a single '$' will get replaced with
1114 the corresponding variable content (previously configured using @code{set}).
1115 If no matching variable is found, the sequence is simply discarded.
1116 @item All macro commands replayed through the @code{play} command are always
1117 atomic for the driving desklet, as are any other non-macro commands.
1118 Simply put, it means no event will ever get generated while a macro is replayed;
1119 they will all get issued right after the @code{play} command returns.
1120 @item As usual, the adesklets interpreter is stateful for indirect mode related
1121 states and variables. You do not have to set up the @code{set_abort_on_events}
1122 flags or variable every time you want to call a macro, only if something
1123 needs to be changed since the last call.
1124 @item The main use of high-level @code{adesklets.Events_handler::set_events()}
1125 is to stop the catching of specific events during macro playback, so the macro
1126 can be interrupted only in specific circumstances. Of course, all events
1127 generated before the call to the method will not be lost but queued, and
1128 appropriate event methods will be called later, provided the handlers are set
1129 back once the macro playback completes.
1130 @item Did we mention that it is a bad idea to do any of this from an unprotected
1131 place? Well, it is. Don't forget to use @code{adesklets.Events_handler::block()}
1132 and @code{adesklets.Events_handler::unblock()} around all animation-related code
1133 if you have an object of a child class of @code{adesklets.Events_handler}
1137 @unnumberedsubsubsec Configuration and internationalization
1139 Let us just mention here that from @command{adesklets} 0.4.0, the
1140 @code{adesklets.utils} module now includes an optional
1141 @code{ConfigFile} class that can be easily reused by desklets authors
1142 to add an easily extendable configuration facility to their
1143 code@footnote{You can look at any non-contributed configurable desklet for
1146 (@xref{Python package documentation}.)
1148 . The class also handles internationalization automatically by default,
1149 setting the charsets according to users' needs. Charset usage can of course
1150 be determined or changed at any time using the @code{adesklets.get_charset()}
1151 and @code{adesklets.set_charset()} functions. The
1152 @code{adesklets.utils.ConfigFile} class also has a @code{charset} attribute one
1153 can examine to determine the user's preference. When using this class, one
1154 should note that an 'ASCII' charset is considered the default, and will not
1155 toggle any conversion. This way, users on platforms not supporting iconv will
1156 always be able to use @command{adesklets} without internationalization support.
1158 @unnumberedsubsubsec Final words
1160 @noindent Finally, let us mention you may want to take a look at the
1161 @file{weather} desklet source code from the
1162 @weblink2{SourceForge project web site,http://sourceforge.net/projects/adesklets/}
1163 for a more substantial piece of Python code using adesklets. There are also a
1164 few other test desklets under @file{test/} that may give you some ideas.
1166 You could also have a look at pydoc's autogenerated
1167 @command{adesklets} package help, included with this document
1168 (@xref{Python package documentation}.). Whenever you are happy enough with
1169 your desklet, feel free to share it with the rest of us (this would be
1170 much appreciated)--package it (@xref{Packaging GNU Makefile for desklets}.),
1171 and then submit it (@xref{Submitting a desklet}.).
1174 @node Extending adesklets
1175 @chapter Using adesklets from other language environments
1177 adesklets was made to be easily usable from a variety of langage
1178 environments@footnote{We use the term ``langage environment'' because the
1179 problem is not the syntax or the paradigm used (should it be imperative,
1180 functional, or anything else); it is the way you can handle basic POSIX-related
1181 operations with files, signals, etc. (@xref{Requirements}.). Thus, a Perl 5
1182 user should use adesklets easily, while a Linux JDK user would probably
1183 encounter more difficulties (no flames intended).}. This chapter explains
1184 to programmers how the adesklets interpreter hooks itself into the system
1185 in a language-neutral fashion.
1187 @noindent If you are not minimally used to POSIX systems or do not have basic
1188 notions on operating system programming, this chapter is probably of no
1191 @noindent Please note that the Python package under
1192 @file{scripting/python/adesklets}
1193 is a good complement for what you are about to read.
1195 @section Requirements
1196 @anchor{Requirements}
1197 If you want to use the adesklets interpreter from your favorite language
1198 but it is not supported out of the box@footnote{As of adesklets
1199 @value{VERSION}, only Python is supported out of the box.}, you can still do
1200 it, provided your langague supports one of these features:
1203 @item Reading and writing in pipes; or
1204 @item Reading and writing from/to files unbuffered
1207 @noindent It should also be able to either@footnote{This said, having both IPC
1208 support and poll/select will make things both simplier and cleaner. Being able
1209 to block signals is also very useful.}:
1212 @item Catch IPC reliable signals; or
1213 @item Read files in non-blocking mode; or
1214 @item Be able to perform a poll/select on files
1217 @noindent Finally, it should also be able to start a child process.
1219 @noindent Those a pretty light requirements from a POSIX point of view, but let
1220 us mention for the sake of completeness that if your language environment does
1221 not meet these requirements, you could still use it provided you can get your
1222 application to talk reliably with another program@footnote{This would be a
1223 wrapper, basically.} that meets them. Of course, this is not an ideal situation
1224 and it should be avoided as much as possible.
1226 @section Initialization mechanism
1228 As you probably know (@xref{Using adesklets}.), there are two modes of operation
1229 for @command{adesklets}, as it can be called:
1232 @item as a desklets launcher--whenever you call @command{adesklets} without
1234 @item as an interpreter--in all other cases (interactive command line use
1235 or a child process from a desklet).
1238 @subsection adesklets called as a desklets launcher - restarting all desklets
1239 @noindent On a new X session, the typical startup sequence is:
1242 @item @command{adesklets} gets called without arguments, somewhere
1243 from the X session initialization scripts.
1244 @item From there, the new adesklets instance acts as a desklets launcher.
1245 It parses the @file{$HOME/.adesklets file}, then forks as many times as there
1246 are desklets to start. The original launcher process then exits as there is
1247 no need for a daemon here.
1248 @item All forked processes set up the @code{ADESKLETS_ID} environment variable
1249 with a string representation of the proper integer ID, then execute
1250 @footnote{With a call from the execve* family; see @code{man 2 execve}.}
1251 the associated script.
1252 @item Each desklet launches itself an @command{adesklets} instance as a child
1253 process, passing along the @code{ADESKLETS_ID} variable without altering it.
1254 It is the desklet's duty to make sure that:
1256 @item the adesklets interpreter standard streams,
1257 @code{stdin}, @code{stdout} and @code{stderr}, get separately redirected,
1258 in a way that parent process can easily write to adesklets' @code{stdin},
1259 and read from @code{stdout} and @code{stderr}. Use of pipes, FIFOs or event
1260 regular files are all possible.
1261 @item the writes to @code{stdin} and reads to the two other streams are
1263 @item the first command argument given to @command{adesklets} is the absolute
1264 file name of the desklet script.
1266 @item Each newly created @command{adesklets} interpreter process initializes
1267 itself using the environment @code{ADESKLETS_ID} variable and the command
1268 line absolute desklet name given as its first argument to lookup its
1269 unscriptable characteristics@footnote{They are, namely, its screen and
1270 coordinates.} from @file{$HOME/.adesklets}. When this operation is over,
1271 the @code{ready!} event is generated (@xref{Events}.), and the interpreter is
1272 ready to process commands.
1275 @subsection adesklets called as an interpreter - registration of a new desklet
1277 When a new desklet gets called directly, the startup sequence described in
1278 the previous subsection is the same, except for the first, second and third
1279 steps which simply don't occur. This means that the environment
1280 @code{ADESKLETS_ID} is not set; the new @command{adesklets} interpreter uses
1281 this fact to detect this is a new desklet, parse the @file{$HOME/.adesklets}
1282 configuration file and allocate the first free ID to the desklet.
1284 @noindent It should be noted that if the desklet file name given as the first
1285 argument to the child @command{adesklets} instance is relative or is not both
1286 readable and executable by the current user, the desklet will not get registered
1287 in @file{$HOME/.adesklets}, and therefore not automatically restarted in
1288 subsequent new X sessions by the launcher. In case @code{stdin} is a
1289 terminal@footnote{Which means the session is interactive}, the registration
1290 does not take place either.
1292 @subsection Consequences
1293 This way, from the scripted desklet perspective, both cases are identical, and
1294 no conditionnal treatment is needed. All the desklet initialization job
1295 is synthesized in the fourth point in the subsection above.
1297 @noindent If needed later on, the desklet can use the @code{get_id} command
1298 to determine its ID.
1300 @section Using streams
1302 As explained previously, a desklet communicates with its private adesklets
1303 interpreter via redirected unbuffered streams. Here, let us see what information
1306 @subsection stdin: the commands
1308 On the interpreter's @code{stdin}, the desklet outputs the commands it wants to
1309 execute in the order in which it wants them to be executed, one command per
1310 line@footnote{A '\n' character should be emitted after each command.}. Since
1311 reading this stream is suspended while a command is processed, a desklet should
1312 generally wait for a command to be processed before emitting
1313 another@footnote{This is to avoid process blocking by overflowing the stream
1314 with arbitrarily long commands; of course, there is no problem sending three
1315 commands of a few hundred bytes in one shot!} (See the next section).
1317 @noindent The command format is pretty simple: it is a command name, followed
1318 by arguments separated by spaces, all in plain text representation, including
1319 numbers. adesklets does not care about the number of spaces between arguments,
1320 as long as there is at least one. In the special case of commands where the
1321 last argument is a string (@code{text_draw}, for instance), adesklets will
1322 choose its first non-space characters to be its beginning; the rest of the
1323 line, including spaces, are considered to be part of the string.
1325 @noindent Two files, automatically kept in sync with the source
1326 (@file{scripting/prototypes} and @file{scripting/enums}) from the base source
1327 distribution, provide in tab-separated plain text format the description of all
1328 the commands and numeric constants that can be made available to the
1329 desklets@footnote{See @file{scripting/protoize.sh.in} and
1330 @file{scripting/enums.sh} for details on the format of the two files.}. A good
1331 binding for a specific language should come with some automation to
1332 auto-generate pertinent parts of its own codebase based on those files; for
1333 instance, the Python binding adds a @code{protoize} action to its
1334 @file{setup.py} @code{distutils} script to do so. Ideally, this automation code
1335 should be redacted in the target language with a reasonable set of
1336 libraries@footnote{The key idea being that most users of your binding should be
1337 able to run it more or less from their base installation of the language.};
1338 if it is not well suited to this task, you need to limit yourself to use:
1341 @item Portable Bourne shell, conforming to POSIX 1003.2 and 1003.2a, scripts
1342 @item A recent sed (Streaming Editor), compatible with GNU
1343 sed@footnote{Nowadays, there is no problem running GNU sed on practically any
1345 @item Portable use of any bc for arithmetic
1348 @noindent if you want your work to become part of the official package.
1350 @subsection stdout: the command results
1352 The @command{adesklets} interpreter frequently polls its @code{stdin}
1353 for new characters, and reads from it as needed. Whenever it receives an
1354 End-Of-Line ('\n'), it stops reading from it and tries executing the command.
1355 Once the command has been carried out (possibly emitting a few lines on
1356 @code{stdout}), it sends as its last entry on it a status message of the form:
1359 command RANK ok: MESSAGE_STRING
1362 @noindent if the command was successful, or:
1365 command RANK error: ERROR_STRING
1368 @noindent if an error occurred.
1370 @noindent @code{RANK} is the numerical ID of the command (an unsigned integer)
1371 that starts at zero when the interpreter is created, and then is automatically
1372 incremented by one for every subsquent line it receives. All commands are
1373 guaranteed to be processed in the order they were submitted.
1374 @code{ERROR_STRING} is a free-form message in human-readable form explaining the
1375 source of the error. @code{MESSAGE_STRING} is also in human-readable form, but
1376 is formatted in such a way that it can be used to retrieve algorithmically
1377 useful return values for any commands. Those return values can be:
1380 @item an integer--the return value ID (@code{create_image} and such)
1381 @item a tuple of integers--the numerical command output
1382 (for @code{context_get_color} and the like)
1383 @item a list of strings--the ordered list of output strings
1384 (for @code{images_info} and the like) for commands that output multiple lines
1385 on @code{stdout}, with the last line being the status message
1386 @item a description string--a one-line textual answer from the command
1387 @item nothing at all
1390 @noindent Algorithmically, your "return value retrieving routine" should first
1391 try to retrieve integers from
1392 @code{MESSAGE_STRING}@footnote{All parameters from the @code{MESSAGE_STRING}
1393 are separated by single spaces.}. If there is one or more integers present,
1394 it should verify that the message is not a mere copy of an emitted command;
1395 if it is, the return value follows the fifth case (see above); otherwise,
1396 if only one integer is found, this is the first case; if more than one is
1397 found, the second one. If no integers are found and there was a list of lines
1398 sent to stdout before the status message of the command, and after the status
1399 message of the previous command, it then returns according to third case.
1400 In what's left, if the status message is different from the emitted command, it
1401 is the fourth case. All remaining conditions should be mapped to the fifth
1402 case. This retrieving algorithm is working for all commands listed in
1403 @file{scripting/prototypes}.
1405 @subsection stderr: the events
1408 All remaining asynchronous event reports are sent to the interpreter's
1409 @code{stderr}. They are asynchronous regarding the processing of commands;
1410 if they will never occur while a command is processed (in the time interval
1411 between the submission of the complete command on @code{stdin} and the output
1412 of its message status line on @code{stdout}), they can be sent at any other
1413 time@footnote{No event is ever lost anyway; its report is only delayed.}.
1415 @noindent Event reports are single lines of the form@footnote{All other outputs
1416 on @code{stderr} can safely be discarded.}:
1419 event: EVENT_MESSAGE
1422 @noindent In a stylized Backus Naur form, the grammar for EVENT_MESSAGE would
1426 EVENT_MESSAGE :: ready! |
1428 menufire MENU_ID MENU_STR |
1432 buttonpress X Y BUTTON_ID |
1433 buttonrelease X Y BUTTON_ID
1437 @noindent where @code{MENU_ID}, @code{X}, @code{Y}, and @code{BUTTON_ID} are
1438 all integers greater than or equal to zero, and @code{MENU_STR} is a string of
1439 characters, possibly including spaces. Let us detail things a bit further:
1442 @item Ready event: sent only once, whenever the @command{adesklets} interpreter
1443 becomes ready to process commands.
1444 @item BackgroundGrab event: sent every time the background image (image 1) gets
1446 @item MenuFire event: sent every time the user select an item in a menu not
1447 managed internally by adesklets.
1448 @item MotionNotify event: sent whenever the pointer moves inside the adesklets
1450 @item EnterNotify, LeaveNotify: sent whenever the cursor passes over a visible
1451 border of the interpreter window, either going in or out.
1452 @item ButtonPress, ButtonRelease: sent when a pointer button is clicked inside
1453 the interpreter window.
1456 @noindent All events but Ready! (namely: MotionNotify, EnterNotify,
1457 LeaveNotify, ButtonPress, ButtonRelease, BackgroundGrab and MenuFire) are
1458 masquable by the desklet. In fact, @command{adesklets} provides the desklet
1459 with commands for specifically handling the generation and output of events.
1461 @code{event_catch}, @code{events_get_send_sigusr1}, @code{events_reset_all},
1462 @code{event_uncatch}, @code{events_info}, @code{events_set_echo},
1463 @code{events_get_echo}, @code{events_purge} and @code{events_set_send_sigusr1}.
1464 It should be noted that those functions are not listed in
1465 @file{scripting/prototypes} as you most probably do not want your users having
1466 access to them. You should probably start an interactive session and play with
1467 them to make sure you fully understand this. This is also the right time to
1468 mention the @file{src/adesklets_debug.sh} script, which comes in handy when
1469 interactively experimenting with events.
1471 @noindent Two last things are worth mentionning about events:
1474 @item By default, events are not echoed, but stored internally, waiting
1475 to be purged with @code{events_purge}. You can change this with
1476 @code{events_set_echo}.
1477 @item You can set the adesklet interpreter to send a SIGUSR1 signal every time
1478 an event is printed out to its parent process (the desklet). It is a very
1479 useful IPC, since the signal can be trapped, allowing the event management
1480 routine to run only when necessary. This is what the Python package uses within
1481 its @code{Events_handler} class.
1484 @section SIGCHLD signal handler
1486 Whenever your language allows it, you should install some kind of SIGCHILD
1487 handler, so you can at least be notified if the adesklets interpreter ever
1488 exists without a reason (child zombies notwithstanding)@footnote{@code{man 2
1489 signal} is a very good reference on signals.}.
1491 @section Textual variables
1493 @command{adesklets} also supports differed execution (indirect mode)
1494 and textual replacement of variables. Here how variables work in indirect mode:
1497 @item Once a command is entered, it is stored untouched into the commands
1498 history list, if applicable (in non-interactive usage of the interpreter,
1499 when the command lies bethween calls to @code{start_recording}
1500 and @code{stop_recording})
1501 @item When a macro command is played back (using the @code{play} command,
1502 @xref{Programming adesklets}.), variables get expanded in a single pass, and no
1503 indirect reference is possible. Expansion is pretty straightforward. The stored
1504 command line is scanned for any non-empty sequence of non-space characters
1505 beginning with a single '$'. Each such sequence is replaced with the
1506 corresponding @code{$variable} value, or removed if no variable is found.
1507 @item Expanded command get executed.
1510 The same expansion mechanism also applies to the direct mode of execution. All
1511 this leads to the fact that, using the Python package for instance, these two
1512 code snippets are equivalent:
1515 adesklets.window_resize(100,100)
1521 adesklets.set('dim',100)
1522 adesklets.window_resize('$dim','$dim')
1525 This did not require any alteration of our Python code, since Python is a
1526 dynamic language, but some other languages will require further thinking.
1528 @section Final words
1530 You should now know pretty much everything needed for integrating adesklets with
1531 your language environment. It may appear to be a daunting task, but a very
1532 clean binding can be produced by one programmer in only a few days. Once again,
1533 have a look at @file{src/adesklets_debug.sh}; it is a (very lame) Bourne shell
1534 binding for adesklets written in only fifty lines, including comments.
1536 If you ever need assistance, you are encouraged to post on the
1537 @weblink2{adesklets-devel mailing list,https://lists.sourceforge.net/lists/listinfo/adesklets-devel}...
1543 @chapter Contributing to adesklets
1545 Your help is wanted! You can valuably contribute to adesklets by:
1549 @strong{Posting your adesklets screenshots online}. You use adesklets and think
1550 you have a pretty cool desktop? Share it with the world by posting it online,
1551 and send us a link! This way, you will help people learn about the project.
1553 @strong{Contribute to the documentation}. You have very good written
1554 knowledge of German, Spanish, Portugese, Arab or Swahili? Translators are always
1555 welcomed, proofreaders too, for all languages.
1557 @strong{Writing new desklets}. adesklets is still young: we crave
1558 talented desklets writers, and we would be more than willing to post or link
1559 to your work. Do not worry too much about interface changes; the author spent
1560 considerable effort to ensure that the interface would be fairly stable even
1561 in the earliest releases. It's not frozen forever, but it shouldn't break your
1562 desklets without some warning. At this point, the API is predominantly getting
1563 internal bug fixes and portability improvements.
1565 @strong{Adding bindings for your language of choice}. Contact the developers
1566 beforehand so that you don't waste time on something that is already written;
1567 they will be glad to share code. Subscribe to the
1568 @weblink2{adesklets-devel mailing
1569 list,https://lists.sourceforge.net/lists/listinfo/adesklets-devel} on
1570 SourceForge for quick access to them.
1573 @noindent Contact me by email at @email{syfou@@users.sourceforge.net}.
1575 @node Frequently asked questions
1576 @appendix Frequently asked questions
1578 Last update: @value{UPDATED}
1579 @appendixsection Compiling adesklets
1581 @heading The adesklets configure script says my Python install is too old, but it's not. What's the problem?
1583 Some platforms (NetBSD, Ubuntu Linux, probably others too) sometimes alter
1584 the Python version, appending letters, prefixing minor numbers, etc., thus
1585 preventing the configuration script from detecting it properly. If you know
1586 @strong{for sure} that what you have installed is at least 2.3.0,
1587 you can pass the @code{--with-python-force-detection} switch to
1588 @code{configure}; this will make the configuration script skip the version
1591 @appendixsection Starting desklets
1593 @heading 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?
1595 It means what is written: @command{python} cannot find the @code{adesklets}
1596 package; maybe it did not get installed, or it did get installed in the wrong
1600 @item Restart from the beginning the installation procedure
1601 (@xref{Installing adesklets}.). Make sure you @strong{do not} select
1602 the @code{--without-python-support} configuration option.
1603 @item Retry starting the desklet. If it still does not work, verify that the
1604 installation directory, given by:@example
1605 sed -n '/PYTHON_SITE_PKG/p' Makefile
1607 @noindent is included in :@example
1608 echo 'import sys; print sys.path' | python
1611 @noindent If not, you can still manually move the adesklets directory
1612 from @code{PYTHON_SITE_PKG} to any path displayed by this last command.
1615 @heading When I try to start a new desklet, I get an @code{ADESKLETSError: adesklets process exited} error from the Python interpreter. What is this?
1617 On some rare systems (@weblink2{archlinux,http://www.archlinux.org/} for instance),
1618 the @code{PATH} variable for the Python interpreter differs from
1619 what is inherited from standard environment, which causes the Python package to
1620 fail to launch adesklets as a child process. On such systems, make sure
1621 to install @command{adesklets} using an appropriate @code{--prefix} switch at
1622 the configuration stage. For instance, on most recent Linux platforms, you
1626 ./configure --prefix=/usr
1629 @heading Everything worked fine but then I tried upgrading a desklet, and I couldn't ever see the new one. What is wrong?
1631 There is a built-in lock mechanism in the interpreter that prevents a user from
1632 simultaneously running more than one desklet with the same @code{ID} and name,
1633 regardless of version. Whenever you upgrade a given desklet, you should first
1634 cleanly quit the desklet (by using @code{Quit} from the context menu), then
1635 install the updated desklet by following the instructions provided in the
1638 @heading 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!
1640 This is most probably related to the way you started the desklet
1641 (Please @pxref{Using adesklets}.). You need to invoke the desklet script
1642 @strong{only once}. Afterwards you just need to run the command:
1648 and it will remember where you placed your desklets and which desklets
1651 @heading This is exactly what I did, but the darn thing wouldn't restart anyway.
1653 Did you store the desklets under a @file{$HOME/.adesklets} directory?
1655 @command{adesklets} need a @file{$HOME/.adesklets} file to store the various
1656 user settings on running desklets; setting up a directory of the same name
1657 prevents it from doing its job right, so just move your directory some place
1658 else (@file{$HOME/.desklets}, for instance).
1660 @appendixsec Displaying desklets
1662 @heading Where are my desklets? @command{adesklets} interpreters seem to be running fine, but I just cannot see anything on my desktop!
1670 @noindent from the base source directory. If a 100x100 window appears when
1671 testing the desklet, it most probably means you are using a window manager
1672 that draws a big window (so called ``fake'' root window) over the root window;
1673 your desklets are just drawn below it. Such window managers include Nautilus,
1674 KDE, Xfce4, CDE or E17. Right now, only Xfce4 is fully handled automatically.
1676 As for adesklets 0.4.11, the fake root window detection method had changed:
1677 it is no longer part of the C code by default@footnote{Although you can get back
1678 the old behavior if you wish by using
1679 @command{--enable-legacy-fake-root-window-detection} at configuration time.
1680 @xref{Installing adesklets}.}. The interpreter now expects
1681 the ADESKLETS_ROOT environment variable to contain the correct fake root
1682 window ID, if any. You can of course set it manually, but you also have
1683 by default a shell frontend to help you. Try invoking:
1689 If the shell frontend is installed, you will get many options. For instance,
1696 Will make the frontend assumes you are using Xfce4, and should set ADESKLETS_ROOT
1697 accordingly. You also have a ``universal'' fake root window detection under
1698 the switch @command{--user}. Finally, please note the frontend is a simple
1699 sh-compatible script, installed by default under
1700 @command{$prefix/share/adesklets} -- it should be pretty
1701 straighforward to modify by anyone wishing to implement other detection schemes.
1703 @heading Okay, I get it. Any hints concerning KDE 3.4.1, 3.4.2 ?
1705 Yes. Those versions of KDE are able not to use any fake root window whatsoever,
1706 thus running adesklets out of the box; the trick is to toggle off the ``Control
1707 Center -> Desktop -> Show icons on desktop'' option (thanks to Stefan Jungcurt
1708 for reporting this).
1710 Theorically, it should be possible to use the mechanism described previously
1711 for the other cases, but further investigations will be needed, as the author
1712 encountered problems.
1714 @heading I cannot see smaller desklets such as xmms_bar or asimpleclock, while others work. What gives?
1716 New desklets are always started in the leftmost, upper corner of the screen, at
1717 the very bottom of the windows stack. Make sure you do not have some elements
1718 (gnomebar, engage, etc) already masking this zone of the screen. Beware! Some
1719 applications use pseudo-transparency, and can mask the root window seamlessly.
1721 @heading 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!
1723 Go see the Fvwm faq: @weblink{http://www.fvwm.org/documentation/faq/#5.11}.
1724 This @code{BugOpts RaiseOverUnmanaged on} option was reported to work for many
1727 @section Running desklets
1728 @heading The 'Configure' item from the context menu of many desklets doesn't work!
1729 For this to work--at least for all the demo desklets--you need to have
1730 @command{xterm} installed, and the @code{EDITOR} variable properly set in
1731 your environment, as it is customary in UNIX. Please note this only launches a
1732 text editor in a terminal. Editing the desklet's configuration file
1733 (usually @file{config.txt} from base desklet directory) has the same effect.
1735 @heading Do you plan including SVG support? I would like to use a SVG image in one of my desklets.
1736 No we do not, sorry. It is not
1737 that @weblink2{SVG,http://www.w3.org/Graphics/SVG/} is a bad format; in fact
1738 it is quite good. But it is also a vector-oriented one (and rather complex),
1739 while Imlib2, on which @command{adesklets} relies heavily, is completely
1740 raster-oriented, and using Imlib2 is the main reason for @command{adesklets}'
1741 simplicity, relatively good speed and low resource usage.
1743 That said, there is no reason for you not using SVG's with desklets, since
1744 it is quite easy to convert images in SVG to high quality PNG's,
1745 using programs such as @weblink2{sodipodi,http://www.sodipodi.com/}, @weblink2{inkscape,http://www.inkscape.org/} or @weblink2{xsvg,http://xsvg.org/}.
1746 In a directory full of SVG's, on a GNU system you can use a command such as:
1748 ls *.svg | sed 's/\(.*\).svg/-z --file=& --export-png=\1.png --export-width=128 --export-height=128/' | xargs --max-lines=1 sodipodi
1750 to convert them all to 128x128 semi-transparent PNG's.
1752 @heading 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?
1754 First, you need to have fontconfig support enabled in adesklets. See the
1755 config.log from the configuration phase to verify it. If you did not keep the
1756 log, you can also look at the dynamic libraries linked against the interpreter.
1757 On a system with GNU binutils, you can do something like:
1759 ldd `which adesklets` | grep fontconfig
1761 If you get output similar to:
1763 libfontconfig.so.1 => /usr/lib/libfontconfig.so.1 (0x45c75000)
1765 it means everything is fine. Otherwise, you should recompile
1766 @command{adesklets} from source. From there, you can use the line:
1768 echo 'list_font_path' | adesklets :
1770 to see all the font directories that adesklets will into look for TrueType
1771 fonts. Consult your fontconfig documentation to learn how to change this
1772 (on up-to-date systems, @code{man 5 fonts-conf} is a good starting point).
1775 echo 'list_fonts' | adesklets :
1777 Will give you all the fonts that are currently found... Keep in mind when
1778 typing them that font names are case-sensitive.
1780 Alternatively, if you just cannot get fontconfig to work, a way to get around
1781 the problem would be to create symbolic links to the fonts you want to use
1782 inside any absolute font paths listed by the command
1783 @code{echo 'list_font_path' ...} above.
1785 @node Python package documentation
1786 @appendix Python package documentation
1788 Here are links to significant sections of the Python package documentation:
1791 @item @weblink2{adesklets,../pydoc/adesklets.html}
1792 @item @weblink2{adesklets.events_handler,../pydoc/adesklets.events_handler.html}
1793 @item @weblink2{adesklets.commands,../pydoc/adesklets.commands.html}
1794 @item @weblink2{adesklets.utils,../pydoc/adesklets.utils.html}
1795 @item @weblink2{adesklets.configfile,../pydoc/adesklets.configfile.html}
1800 @node Imlib2 documentation
1801 @appendix Imlib2 documentation
1803 Carsten Haitzler (@email{raster@@rasterman.com}) took the time to produce very
1804 nice cross-referenced documentation for Imlib2, but for some reason (size
1805 considerations most probably), it is not included in the Imlib2 source
1806 tarball@footnote{Although it can be quite easily regenerated using doxygen.}.
1809 have it @weblink2{here,../imlib2}.
1813 find it online at @weblink{http://adesklets.sf.net/doc/imlib2/}.
1816 Most functions of the Imlib2 API have corresponding, homonymic commands
1817 in @command{adesklets}. @xref{Programming adesklets}, for specific details
1818 on the transition from direct Imlib2 programming in C to adesklets.
1820 @node Packaging GNU Makefile for desklets
1821 @appendix Packaging GNU Makefile for desklets
1823 Here is a convenient Makefile that automates the packaging of new or
1824 existing desklets on a GNU system. Just copy the Makefile below
1825 into @file{GNUmakefile} from your base desklet directory to use it.
1826 There is nothing at all to edit, provided you named your base directory
1827 in a proper 'NAME-MAJOR.MINOR.REVISION' fashion, such as @code{beast-0.666.0}.
1829 @verbatiminclude ../utils/GNUmakefile.desklet
1831 @node Submitting a desklet
1833 @appendix Submitting a desklet
1835 @section Desklet package requirements
1836 Requirements for ``official'' desklets packages are scarce; authors are free to
1837 do as they wish. There are only two things that should be enforced:
1839 @item A meaningful @file{README} file should exist in the base source directory
1840 of the desklet archive and be kept up to date. It should at least contain:
1842 @item the name and contact email adress of the author@footnote{It is probably
1843 not a good idea to give away your private email adress here;
1844 for spam-related reasons, you should probably open an account
1845 on @weblink2{SourceForge,http://sourceforge.net/}, or at another similar place
1846 with a serious spam containment infrastructure.}
1847 @item a short description of the desklet
1848 @item the requirements for running it
1851 @item The package should be a bzip'ed tarball containing a single source
1852 directory of the form @code{NAME-MAJOR.MINOR.REVISION}, where @code{NAME} is
1853 the desklet base name, and @code{MAJOR.MINOR.REVISION} the version. Please note
1854 that a makefile (@xref{Packaging GNU Makefile for desklets}.) is also provided
1855 to automate creation of such an archive on GNU systems.
1858 @section The @command{adesklets_submit} script
1860 Starting in @command{adesklets} 0.4.4, desklet authors are provided with a
1861 Python script to automate the submission of their desklets:
1862 @file{utils/adesklets_submit} from the source package. Use the
1863 @code{--with-python-install-submission-scripts} option at configuration time
1864 to place it in your @code{bindir} directory upon installation.
1866 @file{adesklets_submit} can be used to:
1868 @item Submit a new or updated desklet description for inclusion on the
1869 @weblink2{adesklets web site,http://adesklets.sf.net/desklets.html};
1870 @item Submit a bzip'ed desklet archive for inclusion in SourceForge's desklets
1871 package (this is optional--you may choose to host it yourself).
1874 @section Invoking @command{adesklets_submit}
1875 Desklet submission is initiated by sending a specially crafted email to
1876 @email{adesklets@@mailworks.org}@footnote{It is useless to send anything else
1877 to this address; all messages that cannot be parsed by the automatic reception
1878 script are just silently dropped. Write to @email{syfou@@users.sourceforge.net}
1879 instead if you want to get in touch with the maintainer.}.
1880 The @command{adesklets_submit} script assits you in the construction of
1881 such an email using the user configuration file @file{$HOME/.adesklets_submit}
1882 and the command line switches. Here is an example of a valid
1883 @file{$HOME/.adesklets_submit} configuration:
1885 @verbatiminclude ../utils/adesklets_submit.example
1887 This is pretty self-explanatory, but here are a few less obvious points:
1891 Try to avoid using pseudonyms and nicknames for the @code{author_name} as much
1892 as possible, unless, of course, you already have a pretty well-established
1893 online identity under this name.
1895 @code{send_confirmation} specifies if an email should be sent back to your
1896 @code{author_email} address whenever your desklet is succesfully published.
1897 If the submitted entry is rejected, you will always be written back anyway
1898 with an explanation. Usually, the maintainer will not try to make changes to
1899 problematic entries; it will only summarize back to the author what was not OK.
1901 @emph{Double check} your @code{author_email} address, since this is the only
1902 one the maintainer will try to use when contacting you, regardless of what
1903 the headers say. Failing to supply a valid address will cause all messages to
1904 fail to be sent to you, and all new desklet entries will be rejected.
1906 You can very well use adesklets_submit without any prior contact with the adesklets
1907 maintainer (either via email, within the forum using this adress for
1908 registration, or through the mailing list), but some back and forth will be
1909 needed before publication just to assert your identity and its effective
1910 relation to the provided email address.
1912 @code{desklets} is a dictionary of dictionaries (one dictionary per desklet,
1913 desklets' names being the keys); all the items referring to files (thumbnail,
1914 screenshot and download) could either be publicly accessible URI's (this is the
1915 preferred method), or local files, either absolute or relative to your $HOME
1916 directory. In that case, needed files will be attached to the generated
1919 All images will always be fetched and integrated on the adesklets.sf.net
1920 web site; you can safely remove them from your online location afterwards
1921 if you provided live URI's.
1923 When updating already included desklets, there is no need to submit back
1924 the @code{thumbnail} or @code{screenshot} images if they did not change;
1925 you can just as easily reference the already installed images on SourceForge:
1927 @item The @code{thumbnail} is always stored under @code{http://adesklets.sf.net/images/NAME_thumb.[jpg|png]}
1928 @item The @code{screenshot} is always stored under @code{http://adesklets.sf.net/images/NAME_screen.[jpg|png]}
1929 where @code{NAME} is the name of the desklet.
1932 Using the @code{host_on_sourceforge} value, you can choose to have
1933 your desklet package either hosted on SourceForge or just referenced
1934 on your site if you provided a URI. Of course, choosing this last
1935 alternative also means you will need to keep it in place.
1937 The @code{thumbnail} image should be a JPG (preferably) or PNG (if you
1938 @emph{really} need higher resolutions) of dimensions lying between 190x35 and
1941 The @code{screenshot} image should be a 640x480 JPG (preferably) or PNG.
1942 It should put your desklet in evidence, and thus contain no other ones.
1944 You can choose not to submit thumbnails and/or screenshots. In that case,
1945 default, generic images will be used instead.
1947 @code{Category} is unused for now, and just ignored.
1949 All emails weighing more than 300 KB will be rejected by the maintainer's
1950 email server; thus, adesklets_submit will refuse to generate them. Instead of
1951 submitting such big entries, use the URI facility described above to trim
1953 @item @command{adesklets_submit} does not enforce the requirements above; it only
1954 checks what is strictly required to build a compliant submission email:
1955 the existence of dictionary entries, availability of files, the validity
1956 of file types if they are local... It is your duty to make sure the entries
1957 meet the other requirements if you want to avoid rejection.
1960 For example, Belial Leviathan would fisrt check his @code{beast} desklet's
1961 entry by doing something similar to:
1963 adesklets_submit beast
1966 If everything goes fine, it will output the resulting submission email
1967 on @code{stdout}. From there, Belial can either:
1969 @item Pipe it to his favorite MTA (mail transfert agent) to send it to
1970 @email{adesklets@@mailworks.org}.
1971 @item Make @command{adesklets_submit} send it itself by SMTP, using the
1972 @code{smtp_host} and @code{smtp_port} parameters in its
1973 @file{$HOME/.adesklets_submit}. For this, Belial would use:
1976 adesklets_submit --send beast
1979 One last thing: you should try to avoid sending minor corrections multiple
1980 times, especially if you use local files. It both adds to the workload of the
1981 maintainer's email server and to the management work. Please try to create a
1982 valid entry @emph{then} send it, not the other way around.
1984 @appendixsubsec Further submission validation using @command{adesklets_checkin}
1985 From @command{adesklets} 0.4.5, you now have access to the
1986 @command{adesklets_checkin} script as well. This is the Python
1987 script that the maintainer uses for checking in all submissions.
1988 @emph{Be aware that this script is only provided to desklet authors as a
1989 convenience, to lower their submission rejection count--developers are in no
1990 way forced to use it, and may even be unable to do so, since the script was not
1991 written with portability in mind as adesklets_submit was. Look at the script
1992 header for a complete list of requirements.}
1994 @command{adesklets_checkin} has two modes of operation: interactive and
1995 non-interactive. Only the non-interactive mode will interest desklet authors.
1996 In this mode, usage is fairly simple. Belial, for instance, would do:
1998 adesklets_submit beast | adesklets_checkin
2001 If everything goes fine, an output similar to this will be produced:
2003 Validation started. Please wait.
2004 Everything seems fine, but keep in mind a few things cannot be
2005 verified without human intervention. See documentation for details.
2008 If not, you will get an exception trace with some (hopefully) meaningful
2011 @appendixsubsec Limitations of @command{adesklets_checkin} in non-interactive mode
2013 Here are the remaining problems that @command{adesklets_checkin}
2014 cannot detect and thus must absolutely be solved manually
2015 (the maintainer would interactively catch most of them, and you would have to
2019 Incomplete README file in base directory (Does it contain all the details
2022 Out-of-date README file (Does its content reflect the current state
2025 Desklet fails to run out-of-the-box (i.e. with or without minimal
2026 configuration) when requirements in the README file are met and special
2027 instructions are followed.
2030 @node Copying This Manual
2031 @appendix Copying This Manual
2034 * GNU General Public License:: License for copying this manual.
2039 @node Open PGP Public Key
2040 @appendix Open PGP Public Key
2042 @verbatiminclude syfou.asc
2044 @noindent You can also get this certificate from many public key servers on
2045 the internet, such as @weblink{http://www.keyserver.net/}, or
2046 @weblink{http://pgp.mit.edu/}. Contact its rightful owner,
2047 Sylvain Fourmanoit, by email at @email{syfou@@users.sourceforge.net}
2048 to arrange further key validation if you need any.