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::
100 @noindent The latest version of this document can be found online at
101 @weblink{http://adesklets.sf.net/doc/en/}.
103 @noindent Screenshots, source tarballs, downloadable web documentation tarballs,
104 etc. can also be found on the project home page: @weblink{http://sf.net/projects/adesklets/}.
106 @node About adesklets
107 @chapter What is adesklets?
109 @section Short answer
111 @command{adesklets} is an interactive
112 @weblink2{Imlib2,http://www.enlightenment.org/pages/imlib2.html} console
113 for the X Window System. It provides scripted languages with a clean and
114 simple way to write great looking, mildly interactive desktop integrated
115 graphic applets (aka ``desklets'').
117 It can also be used as a command line oriented graphic editor, a bit similar
118 to @weblink2{ImageMagick,http://www.imagemagick.org/}, but with different
123 @command{adesklets} stands for ``another desklets [container]''. It was
124 written as an alternative to other programs such as:
128 gDesklets (@weblink{http://gdesklets.gnomedesktop.org/})
130 SuperKaramba (@weblink{http://netdragon.sourceforge.net/}).
132 GKrellM (@weblink{http://www.gkrellm.net/})
135 Since this is 'a'desklets, others still have plenty of space to start similar
136 projets, from 'b'desklets to 'z', excluding 'g', which is already taken.
138 Seriously though, all those packages are nice. Nevertheless, the first two
139 have very heavy requirements in terms of library dependencies; basically,
140 gDesklets still requires a fair part of the GNOME environment to be installed
141 (plus specialized libraries such as gnome-python@footnote{A report on this has
142 been produced; you may find it online in PDF format at
143 @weblink{http://adesklets.sf.net/verbatim/gdesklets.pdf}.}), while
144 SuperKaramba needs almost all of the KDE libraries and base environment.
145 This also reflects on performance for the task at hand@footnote{Of course, this
146 is only the author's opinion--and both applications are making big progress on
147 resource efficiency from version to version.}. On the other hand, while GKrellM
148 is significantly lighter (it still depends on GTK+ though), it does not deliver
149 the same experience in terms of ``eye-candiness'' (to the author's taste, of
150 course) or ``scriptability'' than the other two.
152 Thus, @command{adesklets} was born. It provides:
156 a minimal framework for X Window desklets seamlessly integrated into the
157 desktop, with an easy to use central management for starting, positioning
160 a generic, rich and easy to use drawing API similar to gDesklets and
161 SuperKaramba regarding its high visual quality, thanks to the Imlib2 library.
163 very limited library dependencies: uses the very good (and lightning fast)
164 Imlib2 library for all graphic-related operations. No window toolkit used
165 whatsoever; the program relies directly on xlib.
167 a light, robust and small interpreter potentially usable with all sorts of
168 scripting languages thanks to a clean, limited and homogenous syntax. As
170 @value{VERSION}, support for Python is provided out of the box. Future support
171 for Perl and Ruby would be fairly possible. Feel free to contribute support
172 for your favorite language (@xref{Extending adesklets}.)!
174 Minimal disk space, memory footprint and CPU usage. Typically, on glibc 2.3.4
175 Linux 2.6 x86, a unique executable is less than 130 KB on disk, takes less than
176 3 MB of virtual memory per desklet right after initialization, and almost no
177 processor cycles (including cycles from a Python interpreted script) when idle.
184 A sophisticated window API, or even access to widgets besides bare, ugly grey
185 menus. You clearly cannot write any GUI application with this--only
188 Convoluted mechanisms (or just plain mechanisms, for that matter) for
189 script configuration. Script developers are free (or doomed, depending on how
190 you see things) to do whatever they see fit.
192 Support for everything that is not a truly POSIX compliant system. For
193 instance, it would be very surprising if this would ever compile on Cygwin.
195 Feature-rich management of user events. @command{adesklets} aims at low
196 resource consumption and reliability; only a small set of events, mainly
197 pointer-related, are exposed through its API.
203 @heading What's new in version 0.4.12
204 This is a bug fix release. It corrects an error with the new distributed
205 documentation makefile that prevented info files and manual pages from
206 installing right on arbitrary, empty directory trees (thanks to
207 Bart Kreska for the patch). It also add support for nautilus and KDE >=3.4.1,
208 as well as preliminary support for xffm-desktop and ROX-Filer. It
209 should rectify a long-standing issue with some desklets failing to
210 complete their initial display. Finally, the documentation FAQ also
211 got slightly expanded.
213 @heading What's new in version 0.4.11
214 This is a bug fix release. Documentation wize, it brings the french
215 documentation up to speed with the english version (thanks to Martin
216 Kirchgessner @email{martin.kirch@@gmail.com} for all his work), and take
217 the whole documentation source and html
218 version out of the main package (thanks to this, adesklets is now about 300 KB
219 lighter). Code wize, this version includes many small fixes for various platforms
220 -- FreeBSD 7 should hopefully be supported unpatched, manuals have been added
221 for desklets submission script to please Debian. Yet, the biggest change is
222 probably the inclusion of an optional shell driver to the interpreter, that
223 ease up the administration of adesklets and the quick adaptation of the code
224 to new windows managers.
226 @heading What's new in version 0.4.10
227 This is a bug fix release. An unwanted partial new feature made is way
228 into previous release: it caused the contextual menu to stop working
229 the advertised way (the control key needed to be pressed for the menu to
230 get fired). This release just revert back the change, and add a
231 configuration-time option, --enable-control-on-context-menu, for
232 those who really wants this behavior.
234 @heading What's new in version 0.4.9
235 This is a bug fix release. It changes the global macro definitions for
236 adesklets to compile without problems on FreeBSD 6.x, corrects an error
237 with debugging flag stripping from the C compiler, and adds a new demo
238 program about threading.
240 @heading What's new in version 0.4.8
241 This is a bug fix release. It changes the global macro definitions for
242 adesklets to compile without problems on FreeBSD 5.x, and it also adds
243 fake root window detection for KDE, thanks to yogi77, from the forum.
245 @heading What's new in version 0.4.7
246 This is a bug fix release. It removes calls to some C99 math routines not
247 available in earlier BSD's, making the code more portable. It also adds
248 two new commands to the API for handling the image caching mechanism better.
250 @heading What's new in version 0.4.6
251 This is a bug fix and documentation update release. It corrects many small
252 bugs inside the desklets submission process scripts, makes portability changes
253 to the autoconf structure, adds a new demo scripts in test (widget.py), corrects
254 the xwindow_move_window routine for a small placement bugs on the screen (thanks
255 to man1ed from the forum from providing the patch), and finally adds a new
256 appendix containing a handy online version of the Imlib2 documentation.
258 @heading What's new in version 0.4.5
259 This is a bug fix and documentation update release. It improves the desklets
260 submission process by releasing the full check-in script used by the maintainer.
261 It also solves a bug with window refresh when using user-defined background
262 image and menus; thanks to ZeroDivide for reporting this. Various updates and
263 corrections have also been made to the documentation.
265 @heading What's new in version 0.4.4
266 This is a documentation update release, principally aimed at desklet
267 authors. It basically includes a new appendix on how to submit a desklet
268 (including scripted support), and a new subsection on system-wide font
269 detection as well. The FAQ was also expanded to cover this topic.
271 @heading What's new in version 0.4.3
272 This is a documentation update release. Most of the work here was made by
273 Mike Pirnat @email{exilejedi@@users.sourceforge.net}, who was kind enough
274 to rectify the base author's deficient english by proofreading this manual
275 from cover to cover. Thanks Mike! The FAQ was also slightly expanded, and
276 a new appendix for desklets writer created.
278 @heading What's new in version 0.4.2
279 This is a new bug fix release. It corrects a bug within the Python package
280 that made it not compile on all versions of Python prior to 2.4.0. Thanks to
281 nucular, from the adesklets forum, for reporting this. It also corrects another
282 minor mmap-related issue in the same package.
284 @heading What's new in version 0.4.1
285 This is a new bug fix release. It secures the use of the optional
286 @code{adesklets.ConfigFile} class by completely changing
287 the way config files are imported, thus removing a potential
288 security exploit. Thanks to Mike Pirnat @email{exilejedi@@users.sourceforge.net}
289 for sharing his concerns on this issue.
291 @heading What's new in version 0.4.0
292 This is a new minor version release. The interpreter now supports
293 internationalization. It can now dynamically work with different
294 character sets on platforms supporting iconv (as standardized in UNIX98), and
295 display them in the right fashion. The Python package was also extended
296 to include an (optional) generic configuration class, hopefully useful
299 @heading What's new in version 0.3.2
300 This is a documentation update release. Documentation was added for Python
301 programmers, and the FAQ was slightly expanded.
303 @heading What's new in version 0.3.1
304 This is new bug fix release. It just adds support for interruption of time gates
305 by events. This is a feature absolutely required to make some timed effects
308 @heading What's new in version 0.3.0
309 This is a new minor version release. Portability has been a big concern for us
310 since the beginning; with this version, the package compiles and runs flawlessly
311 on FreeBSD and NetBSD (@xref{Portability}.). Event handling has also been
312 internally streamlined, and the Python binding was extended to support
313 dynamic modification of caught events (see @file{test/test_events.py}).
315 The interpreter API now exposes everything the author wanted,
316 and will probably not be expanded much further; everything is pretty much
317 in place to write any desklet, including animations.
319 @heading What's new in version 0.2.1
320 This is a minor bug fix release which removes a compatibility bug within
321 the GNU history library usage. Thanks to Mike Pirnat
322 @email{exilejedi@@users.sourceforge.net} for reporting this.
324 @heading What's new in version 0.2.0
325 This is a new minor version release. Support was added for textual variables
326 (string substitution, in fact), and execution of timed preregistered
327 sequences of commands to the interpreter (indirect mode of execution).
328 This gives desklets a way to perform fluid animations. Run the demo script
329 @file{test/fading.py} from the source package to see those features in action.
331 For developers, this version also includes a rewritten, dynamically
332 configurable debug interface to the interpreter able to generate complete
336 See @file{Changelog} for all details.
339 @c Sets up a marker for automated INSTALL file generation
341 @node Installing adesklets
342 @unnumbered Installing adesklets
345 @node Installing adesklets
346 @chapter Installing adesklets
349 @section Compilation Requirements
351 To compile adesklets from source, you will need:
355 A compiler supporting ANSI C plus variadic macros (about every version
356 of @weblink2{gcc,http://gcc.gnu.org} from 2.7.0 will do - or about
357 everything else published in the last ten years, for that matter)
359 @weblink2{X11,http://www.x.org/} libraries and
360 headers@footnote{Except for headless builds, useful
361 for server environments and such; read further for details.}
363 Imlib2 1.1.2 and up (the more recent the better; go and fetch it from
364 @weblink{http://sourceforge.net/projects/enlightenment/})
366 @weblink2{GNU readline,http://cnswww.cns.cwru.edu/php/chet/readline/rltop.html}
368 A reasonably POSIX-compliant system
371 @noindent It can also use, if present in the system:
375 @weblink2{fontconfig,http://www.fontconfig.org/}, for automated detection of
376 all usable fonts present in the system
378 @weblink2{GNU history,http://cnswww.cns.cwru.edu/php/chet/readline/rltop.html},
379 the faithful complement to GNU readline for command history support
381 iconv library and headers (such
382 as @weblink2{libiconv,http://www.gnu.org/software/libiconv/}), for
383 internationalization support (dynamic support of extended character sets)
385 @weblink2{Python,http://www.python.org} 2.3 and up, if you want Python support
386 (you most probably do -- desklets are written in this language)
389 Many systems routinely package ``development'' versions of libraries and
390 tools separately (@command{imlib2-devel}, @command{readline-devel},
391 @command{fontconfig-devel}, @command{python-devel}, etc); if this is the case for
392 the target system, those have to be chosen over the ``regular'' versions.
394 @section Runtime requirements
396 In addition to the compilation requirements, the optional adesklets
397 shell frontend, installed by default, will itself
398 need a few utilities, all expected to minimally comply with POSIX 1003.2 and
399 1003.2a specifications:
402 @item a sh-compatible @command{/bin/sh} shell
403 @item a Streaming EDitor (sed)
404 @item test, mkdir, rmdir, sleep, kill and ls
407 The @command{xwininfo} and @command{xprop} programs can also be used
408 by this frontend, if a given fake-root window detection routine
409 is explicitely invoked. Both XFree86 and X.org implementations
410 of these utilities have been tested. Other programs will eventually be used
411 by specific detection routine: see the frontend source for details.
413 @section Portability Notice
415 This package was built with portability in mind: all vendor-specific
416 extensions were avoided, and specs (ANSI, SVID 3, BSD 4.3, POSIX) were followed
417 in a conservative way. Nevertheless, original development took place on a single
418 Linux system; it is quite probable that adesklets will not compile or work as
419 expected in some cases. Fixing portability issues is an important concern for us.
421 adesklets has been ported and successfully tested by the developers on many
422 systems. As of version @value{VERSION}, it has been verified to compile and run
423 out of the box on a variety of
426 @item @strong{Kernels/Systems}: Linux (2.2, 2.4, 2.6 series), FreeBSD
427 (4.10, 5, 6 and 7), NetBSD (1.6)
428 @item @strong{C Libraries} (when applicable): glibc (2.1.3 and up), uclibc (0.9.28)
429 @item @strong{Compilers}: gcc (2.95.2, whole 3 serie, 4.0.1),
430 icc 7.0 (with tweaking)
433 Moreover, adesklets itself is fully architecture independent, although
434 Imlib2 is further optimized for the x86 and amd64. It is routinely used on
435 x86, amd64 and ppc machines by the author.
437 At the time of writing, adesklets is already integrated in ports collections of
438 many BSD and software libraries of linux distributions. For reference, let's
442 @item Debian package: @weblink{http://packages.debian.org/unstable/x11/adesklets},
443 maintained by Bartosz Fenski @email{fenio@@debian.org}.
444 @item FreeBSD port: @weblink{http://www.freshports.org/deskutils/adesklets/},
445 maintained by Roman Bogorodskiy @email{novel@@freebsd.org}.
448 Did you try to run the package on something not listed here?
449 Let us know, especially if it did not work.
451 @section Software download
453 The current version of the software (as a source bzip'ed tarball) can be found
454 on the SourceForge project page: @weblink{http://sf.net/projects/adesklets/}
456 You can extract it from the console with @command{tar}. As of version
457 @value{VERSION}, the command line would be:
460 tar xvjf adesklets-@value{VERSION}.tar.bz2
463 or, if your installed version of @command{tar} does not support
464 filtering archives through bzip2:
467 bzcat adesklets-@value{VERSION}.tar.bz2 | tar xv
470 @section Verifying Software Integrity (optional)
472 As of adesklets @value{VERSION}, you can also
473 download from @weblink2{SourceForge,http://sf.net/projects/adesklets/} an
474 ascii-armored detached signature named
475 @command{adesklets-@value{VERSION}.tar.bz2.asc}, that you can match
476 against the author's Open PGP public key (@pxref{Open PGP Public Key},
477 in appendix) to assert the package integrity. For instance, with
478 @command{GnuPG} (@weblink{http://www.gnupg.org/}), you would use:
481 gpg --verify adesklets-@value{VERSION}.tar.bz2.asc adesklets-@value{VERSION}.tar.bz2
484 You can also get the public key for @email{syfou@@users.sourceforge.net}
485 from various public key servers such as @weblink{http://www.keyserver.net/} or
486 @weblink{http://pgp.mit.edu/}. Feel free to contact the author directly if you
487 want to authenticate the key further.
489 @section Compilation and Installation:
491 adesklets provides the usual autoconf/automake scripts of GNU packages.
493 Therefore, in most cases, installation follows the normal three steps:
497 `cd' to the directory containing the package's source code and type
498 `./configure' to configure the package for your system. If you're
499 using `csh' on an old version of System V, you might need to type
500 `sh ./configure' instead to prevent `csh' from trying to execute
503 Running `configure' takes awhile. While running, it prints some
504 messages describing which features it is checking for.
506 Type `make' to compile the package.
508 Type `make install' to install the programs and any data files and
512 You can remove the program binaries and object files from the
513 source code directory by typing `make clean'. To also remove the
514 files that `configure' created (so you can compile the package for
515 a different kind of computer), type `make distclean'.
517 @section Compilers and Options:
519 Some systems require unusual options for compilation or linking that
520 the `configure' script does not know about. You can give `configure'
521 initial values for variables by setting them in the environment. Using
522 a Bourne-compatible shell, you can do that on the command line like
526 CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure
529 @noindent Or on systems that have the `env' program, you can do it like this:
532 env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure
535 @section Optional Features:
537 adesklets comes with a few optional features you can select or not
538 from the `configure' script. Type:
544 @noindent for a complete, short description. Here are a few interesting ones:
548 You may choose to compile adesklets without X support at all
549 (@command{--without-x}).
550 You will get a version that is obviously not suited for
551 desklets rendering, but still good for command line image manipulation
553 You can remove support for some others packages as well:
554 @command{--without-history}, @command{--without-fontconfig}
556 The shell frontend can be avoided altogether using:
557 @command{--disable-frontend-shell-driver}
561 @node Using adesklets
564 @chapter Using adesklets
570 @section ... As a desklets container
572 By itself, adesklets does little: it only provides what is needed to
573 do more! You either need to tell it what to do by passing it commands
574 (see the next section) or you need other scripts (the desklets)
575 that will drive it for you.
577 @noindent Right now, many desklets exist:
578 you may find them on adesklets web page as separate downloads:
579 @weblink{http://adesklets.sf.net/desklets.html}.
581 @subsection Add a new desklet to your X display
582 To add a new desklet script, simply:
586 Download its tarball and unpack it somewhere in your home directory
588 Look at the included README file; special requirements or instructions
589 will be given. Usually, all you have to do is to get adesklets installed,
590 your X server running, then launch the executable script file from the
594 From adesklets 0.4.11, Python-based desklets will ask you explicitely if you want
595 to register or to test them. They will also support a @command{--help} switch,
596 that you can use to know the useful options you can pass to the adesklets
597 interpreter when testing (fake root window detection, etc.).
599 @noindent Please note that:
603 Launching the same desklet script more than once will start multiple instances
606 On multi-head displays, scripts will be launched on their inherited default
607 screen. (For instance, if you do nothing special, calling a script from an
608 xterm on screen 1 will launch the desklet on screen 1).
611 @noindent Most of the time, desklets scripts are made to run as long as you
612 do not tell them to quit. The user has total control of starting, stopping,
613 restarting (when possible), and positionning the desklet (using the context menu,
614 always available by right-clicking on the desklet). The desklet has
615 no control over those operations.
617 @noindent Those few user settings are stored in the @file{$HOME/.adesklets}
618 file. Usually, you do not want to edit this file yourself.
619 If you do, make sure no instances of @command{adesklets} are running at
622 @unnumberedsubsubsec Special notes on system fonts
624 @emph{You may safely skip this section if you do not intend to use
625 non-supplied fonts with adesklets.}
627 Provided your system supports fontconfig (@weblink{http://www.fontconfig.org/})
628 and adesklets was compiled without using @code{--without-fontconfig} (compiling
629 with fontconfig support is the default; @xref{Installing adesklets}.), all the
630 TrueType fonts present in your system are available for use with adesklets.
631 At initialization time, adesklets with fontconfig support compiled in will go
632 through all the fonts detected on your system to identify all the TrueType
633 fonts. See your fontconfig documentation on how to set up your application
634 fonts access properly (@xref{Frequently asked questions}, for some fontconfig
635 debugging hints). It's also good to know that adesklets' package includes a
636 copy of Bitstream's Vera font; all users can rely on @command{adesklets}
637 having at least this font available at all time.
639 @unnumberedsubsubsec Special notes on internationalization
641 @emph{You may safely skip this section if you do not intend to use
642 extended charaters within your desklets.}
644 If your system includes @command{iconv} support (@xref{Installing adesklets}.),
645 you should be able to use any character from any charsets your system
646 knows about for displaying text, either inside a desklet or in its menus,
647 provided you have appropriate TrueType fonts (i.e. TrueType fonts containing
648 those character representations)@footnote{For instance, Bitstream's Vera font
649 included with @command{adesklets} contains glyphs for practically all Latin-1
650 (ISO-8859-1) characters.}.
652 Nevertheless, when using extended (outside 7-bit @code{ASCII}) characters,
653 you need to make sure your local GNU readline settings do not interfere. These
654 three parameters should be set as indicated below in the appropriate
655 @file{initrc} file@footnote{Please refer to your GNU readline documentation}:
663 If you do not want to adapt your GNU readline settings, you can also pass the
664 @code{--enable-force-extended-characters-input} switch to the @code{configure}
665 script when configuring the package from source, which will cause those three
666 variables to always be appropriately overriden internally by the interpreter.
668 Of course, you will also need desklets built to use those extended characters.
669 At the time of writing, all non-contributed Python desklets support them; for
670 those, the charset can be set by the user in the configuration file, when it
671 exists@footnote{When it does not exist, it means the desklet does not need
672 internationalization anyway}; users merely have to set the 'coding' line
673 appropriately@footnote{See @weblink{http://python.fyxm.net/peps/pep-0263.html}
674 if you need details.}.
676 For instance, for using ISO Latin-1 characters, one should use something
680 # -*- coding: ISO-8859-1 -*-
683 as the first or second line in the Python desklet configuration file@footnote{
684 Obviously, such a configuration file needs to be saved using ISO Latin-1
685 encoding or any subset of it, such as @code{ASCII}.}.
687 Finally, please note that if your platform does not support iconv,
688 you should always leave the coding parameter to @code{ASCII}, otherwise
689 you will get fatal errors such as @code{charset conversion not compiled in}
692 @subsection Restore previously running desklets on new X session
693 Invoking @command{adesklets} without any arguments@footnote{A word of warning:
694 by default on adesklets 0.4.11 and up, you @emph{need} to employ some flags if
695 your Window Manager uses a fake root window. @xref{Frequently asked questions}.}:
701 @noindent is enough to restart all desklets that were running the
702 last time you killed the X server (in this mode, @command{adesklets}
703 will exit quickly by itself: there is no need to run it in the
704 background. adesklets does not use a daemon; each applet will fork a
705 standalone @command{adesklets} interpreter as a child process).
706 Invoking @command{adesklets} when desklets are already running
707 will cause them to be killed before the creation of new
708 instances@footnote{Both @command{adesklets} process and their immediate parents
709 will be sent a @command{SIGKILL} signal.}.
711 @noindent If you plan on using desklets on a regular basis, you should put
712 the previous @code{adesklets} command somewhere in your X session
713 initialization. I cannot tell you where with precision, as it varies greatly
714 from system to system. Have a look at:
715 @weblink{http://www.google.ca/search?q=''x window''+startup} for general help.
717 Since adesklets 0.4.11, a more complete shell based frontend is available
718 to you, if you installed it (which is the default). It gives you a more
719 feature-complete set of options. Run
725 To see what is at your fingertips. Please note that since adesklets 0.4.11, you
726 usually @strong{must} specify on the command line proper flags if you need
727 fake root window detection (@xref{Frequently asked questions}.).
729 @section ... As a command-line graphic editor
731 You can also use adesklets as a command-oriented graphic editor.
732 If you type, in a console:
738 @noindent You will get something similar to:
742 adesklets 0.1.0 (Fri Jan 28 19:09:13 EST 2005), on Linux 2.6.10
743 [gcc 3.4.3 20041125 (Gentoo Linux 3.4.3-r1, ssp-3.4.3-0, pie-8.7.7)]
748 @noindent The last line is a prompt. It tells you you are ready
749 to enter command number 0. As of adesklets @value{VERSION}, you have around
750 150 commands at your fingertips. Thanks to GNU readline, a lot of
751 autocompletion hooks are present, giving you an easy way to look around.
752 Press TAB while typing a command name or a command's first argument, and
753 useful information will be displayed. @xref{primer,,an adesklets's primer},
756 @node Programming adesklets
757 @chapter Programming adesklets
758 @section An adesklets' primer
761 As previously stated (@xref{About adesklets}.), adesklets is basically an
762 interactive Imlib2 console, with one or two aditionnal features:
766 When an X display is present, automated management of a single window
768 Automated support for pseudo-transparency
770 Management of long-running applets
773 @noindent So let's start a typical interactive session to see what
774 happens. Under X, open a terminal, and type:
780 @noindent As in last section (@xref{prompt,,'Using adesklets as a command-line
782 you will get a prompt. Now, enter the command '@code{images_info}'. You should
787 id 0 width 1 height 1 alpha 1 filename (null)
788 id 1 width 1 height 1 alpha 1 filename (null)
789 command 0 ok: images_info
792 @noindent This tells you that you have two images: image 0 and image 1, each
793 1x1 pixels. Those are the only images you can never destroy nor do any
794 operations you want with (resize them independently, flip them diagonaly, etc.)
799 Image 0 is the foreground image. By default, it is the only image that is
800 displayed on the single window that @command{adesklets} manages.
802 Image 1 is the background image. By default, it always contains the content
803 of the root window (the desktop) directly below the window. Unless we set it
804 to be otherwise, it is always updated when the user moves it, when you resize
805 it, when your wallpaper changes, etc.
808 @noindent But where is this window? Well, right know, it is only 1x1 pixels,
809 and it is not shown@footnote{``Mapped'' in X Window lingo} on the screen.
810 So let's resize it to 100x100 pixels: type '@code{window_resize 100 100}'.
811 Now, if you re-enter the command '@code{images_info}', you will get:
815 id 0 width 100 height 100 alpha 1 filename (null)
816 id 1 width 100 height 100 alpha 1 filename (null)
817 command 2 ok: images_info
820 @noindent The foreground and background images have been resized to
821 100x100 pixels. Moreover, the background image has been updated to contain
822 a new image of the background. Now, let's make this window visible. Type two
823 commands: '@code{window_reset managed}' and then '@code{window_show}'.
825 @noindent The first command tell adesklets to let your window manager
826 ``manage'' your window (the default is not to); it means the window gets
827 decorated, and you can interactively change its visibility@footnote{An
828 ``unmanaged'' window is very useful for scripted desklets: it looks like
829 it is part of the root window as it can be made to never go on top, and to stay
830 mapped when workspaces are switched.}. The second command shows our 100x100
831 window. So far, it's nothing too impressive--just a black 100x100 square with a
832 titlebar and fixed-size borders.
834 @noindent As mentioned above, only image 0 (the foreground) is displayed by
835 default. Now, type: '@code{window_set_transparency 1}'. Wow! We see the
836 root window below! With ``window transparency'' on, the image 1 (background)
837 is first copied onto the window, then image 0 (foreground) which is purely
838 transparent black, is blended onto it@footnote{Well...Not quite. Actually,
839 there is a buffer involved for performance, but the operation is logically
840 equivalent to this description.}.
842 @noindent It is time to say a word about colors. Remember, adesklets is an
843 Imlib2 console. Thus, as with Imlib2@footnote{Keep your Imlib2 documentation
844 nearby; it is very handy! @xref{Imlib2 documentation}.}, colors are
845 always true 32 colors, RGBA encoded, with eight bits (0 to 255) per channel,
846 including an alpha channel for transparency. Palette conversion and such will
847 automatically take place if your screen depth is less than that, so you do not
848 need to bother with that. If you type: '@code{context_get_color}', you will get:
851 command 0 ok: context color 255 255 255 255
854 @noindent Imlib2 is a kind of state machine; as such, it comes with a
855 ``context'' that remembers a series of attributes it will use in its future
856 operations. For instance, we now know the color it will use as long as we do not
857 modify it is opaque pure white (red=255, blue=255, green=255, alpha=255).
858 If we type: '@code{context_get_image}', it returns:
861 command 0 ok: context image 0
864 @noindent Which means all window operations we perform are made directly on
865 the forgeground image. So, let's draw a filled semi-transparent magenta
866 rectangle on the foreground. Commands could be:
867 '@code{context_set_color 255 0 0 200}' and
868 '@code{image_fill_rectangle 25 25 50 50}'. Neat, isn't it?
870 @noindent If you are used to Imlib2 programming, you will have noticed
871 by now those last few commands look quite familiar. This is pretty normal;
872 most of Imlib2 C functions are presented as corresponding 'commands' in
873 adesklets. This way, adesklets' command '@code{image_fill_rectangle}'
874 follows the same semantic as Imlib2's '@code{imlib_image_fill_rectangle()}'
875 function, the command '@code{context_set_color}' functions just like
876 '@code{imlib_context_set_color()}', etc. The only two significant (and
877 systematic) differences are that whenever you would use an
878 '@code{Imlib_Something}' object in C, you use an integer ID with adesklets,
879 and on the semantic of the '@code{imlib_free_something()}' functions that need
880 to be given an ID instead of freeing the context selected object of this type.
882 @noindent This is pretty easy to illustrate. Let's load the ``Vera'' font
883 included with adesklets at a 20pt size, set it as default font, and write in
884 pure opaque white ``Hello'' diagonally on the foreground image from the top left
885 corner before unloading the font. It would look like:
888 6 >>> load_font Vera/20
889 command 6 ok: new font 0
890 7 >>> context_set_font 0
891 command 7 ok: context_set_font 0
892 8 >>> context_set_direction text_to_angle
893 command 8 ok: context_set_direction text_to_angle
894 9 >>> context_set_angle 45
895 command 9 ok: context_set_angle 45
896 10 >>> context_set_color 255 255 255 255
897 command 10 ok: context_set_color 255 255 255 255
898 11 >>> text_draw 0 0 Hello
899 command 11 ok: text_draw 0 0 Hello
901 command 12 ok: free_font 0
904 @noindent If you look at your imlib2 documentation, you will immediatly notice
905 the two differences we just talked about: all references to the font Vera/20
906 are made through an integer ID (0 here), and the '@code{free_font}' command,
907 unlike the corresponding '@code{imlib_free_font()}' function, is called with
908 the font ID as an argument instead of the context font.
910 @noindent Now let's say you want to save you resulting image; not a problem!
911 Let us type: '@code{save_image out.png}', and the foreground is saved in the
912 file ``out.png'' in the current working directory@footnote{For this to work,
913 you need to have your Imlib2 installation properly configured for using libpng,
914 or you could receive a ``no loader for file format'' error.}. Now, just for
915 the sake of it, let us exit adesklets, and start another interactive session
916 to see if we can reload this image. Just type in the ``@code{quit}'' command or
917 press ^D (Control D: end of file). Then your new session should look
921 0 >>> window_resize 100 100
922 command 0 ok: window_resize 100 100
923 1 >>> window_reset managed
924 command 1 ok: window_reset managed
925 2 >>> window_set_transparency 1
926 command 2 ok: window_set_transparency 1
927 3 >>> load_image out.png
928 command 3 ok: new image 2
929 4 >>> blend_image_onto_image 2 1 0 0 100 100 0 0 100 100
930 command 4 ok: blend_image_onto_image 2 1 0 0 100 100 0 0 100 100
932 command 5 ok: window_show
934 command 6 ok: free_image 2
937 @noindent Of course, we wanted to visualize the result; this is why we
938 emitted commands '@code{window_reset}', '@code{window_set_transparency}'
939 and '@code{window_show}'; they are not otherwise useful. The command
940 '@code{blend_image_onto_image}' comes straight from Imlib2 once again;
941 it takes the newly created image 2 from the third command and blends it
942 onto the context image (image 0, foreground by default), for its coordinates
943 (0,0) to 100x100 pixels farther, and puts it on the rectangle starting at (0,0)
944 of size 100x100 pixels of image 0. It is finally good to note that, with
945 adesklets, there is always an image in Imlib2 context: whenever you try to
946 free the current image, the image context is always reset to the foreground
949 @noindent OK, so it is almost the end of this primer... From there you should
950 play around with adesklets. It is pretty straightforward to use if you are
951 already familiar with Imlib2. If you are not, your best resource is certainly
952 having Imlib2 documentation not far away. :-)
954 @noindent Some last tips:
958 If you get tired of typing, and typing, do not forget you have autocompletion:
959 'TAB' your problems away!
961 If you want to have hints on how to do something, you have a built-in
962 '@code{help}' command.
964 If you are working out a series of commands, things are not working
965 and all this interactive usage it getting tiresome:
968 Use the '@code{history}' command to output your current session to a
969 file@footnote{For this to work, you need to have GNU history when
970 building adesklets.}.
972 Use the '-f' switch with adesklets to get commands from a file instead
975 If you try to visualise something, insert a '@code{pause}' command at the
976 end of the script to freeze the interpreter.
978 All strings from a pound sign '#' to the end of a line will get discarded,
979 allowing you to write comments.
983 @noindent Here is an example:
986 #!/usr/bin/env adesklets -f
988 # Make the window 'managed'
992 # Resize the window to 100x100 pixels
994 window_resize 100 100
996 # Show the window, then freeze for 10 seconds before exiting
1002 @noindent You will just have to make this script executable and run it. As
1003 usual, output from the commands will get printed to stdout.
1006 @item You could also use the @code{play} command. This two-arguments command
1007 gives you a way to replay any sequence of commands from history, using the
1008 command number of the first and last command as parameters.
1011 @section Real programming with adesklets: writing desklet scripts
1013 When you are ready for real work@footnote{:-)}, you might want to use
1014 a real scripted language instead of the raw @command{adesklets} interpreter we
1015 used in the primer; you never know when just having variables could come in
1018 At the time of this writing (@value{UPDATED}), the Python package is included
1019 @footnote{adesklets was written to be easily used from a variety of interpreted
1020 languages -- do not hesitate to propose your help if you want to bring support
1021 for your language of choice!}.
1023 @subsection General tips for programmers
1025 A really useful feature of the @command{adesklets} interpreter
1026 is its ability to produce a full trace of its session (commands, events and
1027 special messages), either on @code{stdeerr} or as a log file, independently
1028 of what is driving it. To have access to this feature, one must:
1031 @item Configure the package from source, passing along the @code{--enable-debug}
1032 switch to @code{configure}.
1033 @item Export the @code{ADESKLETS_LOG} variable in the environment if
1034 the session's output should to be stored in files instead of printed
1035 to @code{stderr}@footnote{Printing to @code{stderr} will break most bindings,
1036 and should therefore be used mainly when invoking the interpreter directly
1037 from the console.}. It should be an absolute filename prefix which the
1038 interpreter, inheriting from the environment, can use to create complete file
1041 From there, it is possible to read complete chronological session logs;
1042 used correcly, it is very useful for debugging purposes. You can use
1043 it in conjunction with the @code{echo} command to set easy to find log points.
1045 @subsection adesklets and Python
1046 @unnumberedsubsubsec Python usage example
1047 From Python, things are not very different than from the interpreter.
1048 Commands have been wrapped into Python functions, and an @code{Events_handler}
1049 class has been made public to handle asynchronous feedback from the
1050 interpreter. Let's have a look at the @file{test/test.py} script from the
1051 source tarball of version @value{VERSION}:
1053 @verbatiminclude ../test/test.py
1055 That's it! Twenty-six lines of Python code, and we have a perfectly functionnal
1056 desklet. I think things are pretty self-explanatory; have a look at the
1057 Python online help for @code{adesklets}, @code{adesklets.commands} and
1058 @code{adesklets.Events_handler} for a good, complete explanation
1060 (@xref{Python package documentation}.)
1062 . All we do here is:
1066 Import the @code{adesklets} package:
1067 this automatically instantiates a child @command{adesklets} process and sets up
1068 all communications. When the package initialization returns without raising
1069 any exception, it means the interpreter is up and ready to accept commands.
1071 Subclass @code{adesklets.Events_handler} and redefine the methods invoked
1072 for the events we are interested in (all other events are not just ignored,
1073 they are not generated).
1075 Instantiate an object of this class, and put it on hold indefinitely
1076 @footnote{This last step is not mandatory; the script may very well continue,
1077 but it should be written so that it supports signal interruptions. See
1078 @code{help(adesklets.Events_handler)} for further explanations}.
1081 @unnumberedsubsubsec Gotchas: a bit more about object IDs
1083 All adesklets objects (fonts, images, color ranges, polygons, etc), are stored
1084 in stacks (one stack per object type). Python's ID's are nothing more than the
1085 initial position of given objects inside the relevant stack, and therefore
1086 will become invalid if an object of the same type below them gets freed.
1088 For instance, if we start with a clean state, all we have in the stack of
1089 images is the window's foreground (ID 0) and background (ID 1).
1090 When someone creates two other images from Python like so:
1092 im_1 = adesklets.create_image(10,10)
1093 im_2 = adesklets.create_image(10,10)
1095 @noindent We get @code{im_1==1}, and @code{im_2==2}. Whenever someones does:
1097 adesklets.free_image(im_1)
1099 @noindent The stack starts collapsing, and what was once image 3 (@code{im_1})
1100 is now image 2, and @code{im_2} is now an invalid reference. This clearly means
1103 adesklets.free_image(im_2)
1105 @noindent would generate an @code{image out of range} error message.
1107 @unnumberedsubsubsec Special subject: animations
1109 @command{adesklets} now includes an indirect mode of execution and textual
1110 variables (non-recursive textual replacements, to be precise) as well.
1111 This means desklets writers have what is needed to create precisely-timed
1112 animations. You can find an easy-to-follow example in @file{test/fading.py}.
1113 A somewhat more involved use of these features is also made in the @code{yab}
1114 desklet. To realize an animation from Python, one should:
1117 @item @strong{Record} a sequence of commands
1118 (we will call it a macro command, or macro for now on). From Python, this
1119 involves toggling on indirect mode using the @code{adesklets.start_recording()}
1120 function, emitting an undetermined number of @command{adesklets} commands,
1121 then toggling back into normal mode (direct execution) with
1122 @code{adesklets.stop_recording()}. Of course, no command is ever evaluated
1123 while the interpreter is in indirect mode; commands are only stored in the
1124 history for future replay.
1125 @item @strong{Set up} whether the to-be-replayed sequence of commands can be
1126 interrupted by events or not, using the @code{adesklets.play_set_abort_on_events()}
1127 function. The high-level @code{adesklets.Events_handler::set_events()} method
1128 can also be used to dynamicaly change what events are caught. See
1129 @file{test/test_events.py} for an example.
1130 @item @strong{Set up} the variables used within the recorded macro using the
1131 @code{adesklets.set()} function, very similar to its Bourne shell homonym.
1132 @item @strong{Play} the macro using the @code{adesklets.play()} function.
1135 Here are a few additional remarks:
1137 @item Precise timing during replay is achieved through the @code{time_gate}
1138 command. This works very simply: every time a macro replays, adesklets
1139 records its starting time, and whenever a @code{time_gate} command is
1140 encountered during the replay, it waits for the number of seconds given as
1141 an argument to @code{time_gate} to run out. For instance, specifing
1142 @code{time_gate 0.1} in a macro will make any subsequent commands within the
1143 macro not execute before the macro has run for at least a tenth of second.
1144 @item Variable expansion always occurs just before command execution, regardless
1145 of current interpreter mode (direct or indirect). All sequences of characters
1146 not containing spaces directly following a single '$' will get replaced with
1147 the corresponding variable content (previously configured using @code{set}).
1148 If no matching variable is found, the sequence is simply discarded.
1149 @item All macro commands replayed through the @code{play} command are always
1150 atomic for the driving desklet, as are any other non-macro commands.
1151 Simply put, it means no event will ever get generated while a macro is replayed;
1152 they will all get issued right after the @code{play} command returns.
1153 @item As usual, the adesklets interpreter is stateful for indirect mode related
1154 states and variables. You do not have to set up the @code{set_abort_on_events}
1155 flags or variable every time you want to call a macro, only if something
1156 needs to be changed since the last call.
1157 @item The main use of high-level @code{adesklets.Events_handler::set_events()}
1158 is to stop the catching of specific events during macro playback, so the macro
1159 can be interrupted only in specific circumstances. Of course, all events
1160 generated before the call to the method will not be lost but queued, and
1161 appropriate event methods will be called later, provided the handlers are set
1162 back once the macro playback completes.
1163 @item Did we mention that it is a bad idea to do any of this from an unprotected
1164 place? Well, it is. Don't forget to use @code{adesklets.Events_handler::block()}
1165 and @code{adesklets.Events_handler::unblock()} around all animation-related code
1166 if you have an object of a child class of @code{adesklets.Events_handler}
1170 @unnumberedsubsubsec Configuration and internationalization
1172 Let us just mention here that from @command{adesklets} 0.4.0, the
1173 @code{adesklets.utils} module now includes an optional
1174 @code{ConfigFile} class that can be easily reused by desklets authors
1175 to add an easily extendable configuration facility to their
1176 code@footnote{You can look at any non-contributed configurable desklet for
1179 (@xref{Python package documentation}.)
1181 . The class also handles internationalization automatically by default,
1182 setting the charsets according to users' needs. Charset usage can of course
1183 be determined or changed at any time using the @code{adesklets.get_charset()}
1184 and @code{adesklets.set_charset()} functions. The
1185 @code{adesklets.utils.ConfigFile} class also has a @code{charset} attribute one
1186 can examine to determine the user's preference. When using this class, one
1187 should note that an 'ASCII' charset is considered the default, and will not
1188 toggle any conversion. This way, users on platforms not supporting iconv will
1189 always be able to use @command{adesklets} without internationalization support.
1191 @unnumberedsubsubsec Final words
1193 @noindent Finally, let us mention you may want to take a look at the
1194 @file{weather} desklet source code from the
1195 @weblink2{SourceForge project web site,http://sourceforge.net/projects/adesklets/}
1196 for a more substantial piece of Python code using adesklets. There are also a
1197 few other test desklets under @file{test/} that may give you some ideas.
1199 You could also have a look at pydoc's autogenerated
1200 @command{adesklets} package help, included with this document
1201 (@xref{Python package documentation}.). Whenever you are happy enough with
1202 your desklet, feel free to share it with the rest of us (this would be
1203 much appreciated)--package it (@xref{Packaging GNU Makefile for desklets}.),
1204 and then submit it (@xref{Submitting a desklet}.).
1207 @node Extending adesklets
1208 @chapter Using adesklets from other language environments
1210 adesklets was made to be easily usable from a variety of langage
1211 environments@footnote{We use the term ``langage environment'' because the
1212 problem is not the syntax or the paradigm used (should it be imperative,
1213 functional, or anything else); it is the way you can handle basic POSIX-related
1214 operations with files, signals, etc. (@xref{Requirements}.). Thus, a Perl 5
1215 user should use adesklets easily, while a Linux JDK user would probably
1216 encounter more difficulties (no flames intended).}. This chapter explains
1217 to programmers how the adesklets interpreter hooks itself into the system
1218 in a language-neutral fashion.
1220 @noindent If you are not minimally used to POSIX systems or do not have basic
1221 notions on operating system programming, this chapter is probably of no
1224 @noindent Please note that the Python package under
1225 @file{scripting/python/adesklets}
1226 is a good complement for what you are about to read.
1228 @section Requirements
1229 @anchor{Requirements}
1230 If you want to use the adesklets interpreter from your favorite language
1231 but it is not supported out of the box@footnote{As of adesklets
1232 @value{VERSION}, only Python is supported out of the box.}, you can still do
1233 it, provided your langague supports one of these features:
1236 @item Reading and writing in pipes; or
1237 @item Reading and writing from/to files unbuffered
1240 @noindent It should also be able to either@footnote{This said, having both IPC
1241 support and poll/select will make things both simplier and cleaner. Being able
1242 to block signals is also very useful.}:
1245 @item Catch IPC reliable signals; or
1246 @item Read files in non-blocking mode; or
1247 @item Be able to perform a poll/select on files
1250 @noindent Finally, it should also be able to start a child process.
1252 @noindent Those a pretty light requirements from a POSIX point of view, but let
1253 us mention for the sake of completeness that if your language environment does
1254 not meet these requirements, you could still use it provided you can get your
1255 application to talk reliably with another program@footnote{This would be a
1256 wrapper, basically.} that meets them. Of course, this is not an ideal situation
1257 and it should be avoided as much as possible.
1259 @section Initialization mechanism
1261 As you probably know (@xref{Using adesklets}.), there are two modes of operation
1262 for @command{adesklets}, as it can be called:
1265 @item as a desklets launcher--whenever you call @command{adesklets} without
1267 @item as an interpreter--in all other cases (interactive command line use
1268 or a child process from a desklet).
1271 @subsection adesklets called as a desklets launcher - restarting all desklets
1272 @noindent On a new X session, the typical startup sequence is:
1275 @item @command{adesklets} gets called without arguments, somewhere
1276 from the X session initialization scripts.
1277 @item From there, the new adesklets instance acts as a desklets launcher.
1278 It parses the @file{$HOME/.adesklets file}, then forks as many times as there
1279 are desklets to start. The original launcher process then exits as there is
1280 no need for a daemon here.
1281 @item All forked processes set up the @code{ADESKLETS_ID} environment variable
1282 with a string representation of the proper integer ID, then execute
1283 @footnote{With a call from the execve* family; see @code{man 2 execve}.}
1284 the associated script.
1285 @item Each desklet launches itself an @command{adesklets} instance as a child
1286 process, passing along the @code{ADESKLETS_ID} variable without altering it.
1287 It is the desklet's duty to make sure that:
1289 @item the adesklets interpreter standard streams,
1290 @code{stdin}, @code{stdout} and @code{stderr}, get separately redirected,
1291 in a way that parent process can easily write to adesklets' @code{stdin},
1292 and read from @code{stdout} and @code{stderr}. Use of pipes, FIFOs or event
1293 regular files are all possible.
1294 @item the writes to @code{stdin} and reads to the two other streams are
1296 @item the first command argument given to @command{adesklets} is the absolute
1297 file name of the desklet script.
1299 @item Each newly created @command{adesklets} interpreter process initializes
1300 itself using the environment @code{ADESKLETS_ID} variable and the command
1301 line absolute desklet name given as its first argument to lookup its
1302 unscriptable characteristics@footnote{They are, namely, its screen and
1303 coordinates.} from @file{$HOME/.adesklets}. When this operation is over,
1304 the @code{ready!} event is generated (@xref{Events}.), and the interpreter is
1305 ready to process commands.
1308 @subsection adesklets called as an interpreter - registration of a new desklet
1310 When a new desklet gets called directly, the startup sequence described in
1311 the previous subsection is the same, except for the first, second and third
1312 steps which simply don't occur. This means that the environment
1313 @code{ADESKLETS_ID} is not set; the new @command{adesklets} interpreter uses
1314 this fact to detect this is a new desklet, parse the @file{$HOME/.adesklets}
1315 configuration file and allocate the first free ID to the desklet.
1317 @noindent It should be noted that if the desklet file name given as the first
1318 argument to the child @command{adesklets} instance is relative or is not both
1319 readable and executable by the current user, the desklet will not get registered
1320 in @file{$HOME/.adesklets}, and therefore not automatically restarted in
1321 subsequent new X sessions by the launcher. In case @code{stdin} is a
1322 terminal@footnote{Which means the session is interactive}, the registration
1323 does not take place either.
1325 @subsection Consequences
1326 This way, from the scripted desklet perspective, both cases are identical, and
1327 no conditionnal treatment is needed. All the desklet initialization job
1328 is synthesized in the fourth point in the subsection above.
1330 @noindent If needed later on, the desklet can use the @code{get_id} command
1331 to determine its ID.
1333 @section Using streams
1335 As explained previously, a desklet communicates with its private adesklets
1336 interpreter via redirected unbuffered streams. Here, let us see what information
1339 @subsection stdin: the commands
1341 On the interpreter's @code{stdin}, the desklet outputs the commands it wants to
1342 execute in the order in which it wants them to be executed, one command per
1343 line@footnote{A '\n' character should be emitted after each command.}. Since
1344 reading this stream is suspended while a command is processed, a desklet should
1345 generally wait for a command to be processed before emitting
1346 another@footnote{This is to avoid process blocking by overflowing the stream
1347 with arbitrarily long commands; of course, there is no problem sending three
1348 commands of a few hundred bytes in one shot!} (See the next section).
1350 @noindent The command format is pretty simple: it is a command name, followed
1351 by arguments separated by spaces, all in plain text representation, including
1352 numbers. adesklets does not care about the number of spaces between arguments,
1353 as long as there is at least one. In the special case of commands where the
1354 last argument is a string (@code{text_draw}, for instance), adesklets will
1355 choose its first non-space characters to be its beginning; the rest of the
1356 line, including spaces, are considered to be part of the string.
1358 @noindent Two files, automatically kept in sync with the source
1359 (@file{scripting/prototypes} and @file{scripting/enums}) from the base source
1360 distribution, provide in tab-separated plain text format the description of all
1361 the commands and numeric constants that can be made available to the
1362 desklets@footnote{See @file{scripting/protoize.sh.in} and
1363 @file{scripting/enums.sh} for details on the format of the two files.}. A good
1364 binding for a specific language should come with some automation to
1365 auto-generate pertinent parts of its own codebase based on those files; for
1366 instance, the Python binding adds a @code{protoize} action to its
1367 @file{setup.py} @code{distutils} script to do so. Ideally, this automation code
1368 should be redacted in the target language with a reasonable set of
1369 libraries@footnote{The key idea being that most users of your binding should be
1370 able to run it more or less from their base installation of the language.};
1371 if it is not well suited to this task, you need to limit yourself to use:
1374 @item Portable Bourne shell, conforming to POSIX 1003.2 and 1003.2a, scripts
1375 @item A recent sed (Streaming Editor), compatible with GNU
1376 sed@footnote{Nowadays, there is no problem running GNU sed on practically any
1378 @item Portable use of any bc for arithmetic
1381 @noindent if you want your work to become part of the official package.
1383 @subsection stdout: the command results
1385 The @command{adesklets} interpreter frequently polls its @code{stdin}
1386 for new characters, and reads from it as needed. Whenever it receives an
1387 End-Of-Line ('\n'), it stops reading from it and tries executing the command.
1388 Once the command has been carried out (possibly emitting a few lines on
1389 @code{stdout}), it sends as its last entry on it a status message of the form:
1392 command RANK ok: MESSAGE_STRING
1395 @noindent if the command was successful, or:
1398 command RANK error: ERROR_STRING
1401 @noindent if an error occurred.
1403 @noindent @code{RANK} is the numerical ID of the command (an unsigned integer)
1404 that starts at zero when the interpreter is created, and then is automatically
1405 incremented by one for every subsquent line it receives. All commands are
1406 guaranteed to be processed in the order they were submitted.
1407 @code{ERROR_STRING} is a free-form message in human-readable form explaining the
1408 source of the error. @code{MESSAGE_STRING} is also in human-readable form, but
1409 is formatted in such a way that it can be used to retrieve algorithmically
1410 useful return values for any commands. Those return values can be:
1413 @item an integer--the return value ID (@code{create_image} and such)
1414 @item a tuple of integers--the numerical command output
1415 (for @code{context_get_color} and the like)
1416 @item a list of strings--the ordered list of output strings
1417 (for @code{images_info} and the like) for commands that output multiple lines
1418 on @code{stdout}, with the last line being the status message
1419 @item a description string--a one-line textual answer from the command
1420 @item nothing at all
1423 @noindent Algorithmically, your "return value retrieving routine" should first
1424 try to retrieve integers from
1425 @code{MESSAGE_STRING}@footnote{All parameters from the @code{MESSAGE_STRING}
1426 are separated by single spaces.}. If there is one or more integers present,
1427 it should verify that the message is not a mere copy of an emitted command;
1428 if it is, the return value follows the fifth case (see above); otherwise,
1429 if only one integer is found, this is the first case; if more than one is
1430 found, the second one. If no integers are found and there was a list of lines
1431 sent to stdout before the status message of the command, and after the status
1432 message of the previous command, it then returns according to third case.
1433 In what's left, if the status message is different from the emitted command, it
1434 is the fourth case. All remaining conditions should be mapped to the fifth
1435 case. This retrieving algorithm is working for all commands listed in
1436 @file{scripting/prototypes}.
1438 @subsection stderr: the events
1441 All remaining asynchronous event reports are sent to the interpreter's
1442 @code{stderr}. They are asynchronous regarding the processing of commands;
1443 if they will never occur while a command is processed (in the time interval
1444 between the submission of the complete command on @code{stdin} and the output
1445 of its message status line on @code{stdout}), they can be sent at any other
1446 time@footnote{No event is ever lost anyway; its report is only delayed.}.
1448 @noindent Event reports are single lines of the form@footnote{All other outputs
1449 on @code{stderr} can safely be discarded.}:
1452 event: EVENT_MESSAGE
1455 @noindent In a stylized Backus Naur form, the grammar for EVENT_MESSAGE would
1459 EVENT_MESSAGE :: ready! |
1461 menufire MENU_ID MENU_STR |
1465 buttonpress X Y BUTTON_ID |
1466 buttonrelease X Y BUTTON_ID
1470 @noindent where @code{MENU_ID}, @code{X}, @code{Y}, and @code{BUTTON_ID} are
1471 all integers greater than or equal to zero, and @code{MENU_STR} is a string of
1472 characters, possibly including spaces. Let us detail things a bit further:
1475 @item Ready event: sent only once, whenever the @command{adesklets} interpreter
1476 becomes ready to process commands.
1477 @item BackgroundGrab event: sent every time the background image (image 1) gets
1479 @item MenuFire event: sent every time the user select an item in a menu not
1480 managed internally by adesklets.
1481 @item MotionNotify event: sent whenever the pointer moves inside the adesklets
1483 @item EnterNotify, LeaveNotify: sent whenever the cursor passes over a visible
1484 border of the interpreter window, either going in or out.
1485 @item ButtonPress, ButtonRelease: sent when a pointer button is clicked inside
1486 the interpreter window.
1489 @noindent All events but Ready! (namely: MotionNotify, EnterNotify,
1490 LeaveNotify, ButtonPress, ButtonRelease, BackgroundGrab and MenuFire) are
1491 masquable by the desklet. In fact, @command{adesklets} provides the desklet
1492 with commands for specifically handling the generation and output of events.
1494 @code{event_catch}, @code{events_get_send_sigusr1}, @code{events_reset_all},
1495 @code{event_uncatch}, @code{events_info}, @code{events_set_echo},
1496 @code{events_get_echo}, @code{events_purge} and @code{events_set_send_sigusr1}.
1497 It should be noted that those functions are not listed in
1498 @file{scripting/prototypes} as you most probably do not want your users having
1499 access to them. You should probably start an interactive session and play with
1500 them to make sure you fully understand this. This is also the right time to
1501 mention the @file{src/adesklets_debug.sh} script, which comes in handy when
1502 interactively experimenting with events.
1504 @noindent Two last things are worth mentionning about events:
1507 @item By default, events are not echoed, but stored internally, waiting
1508 to be purged with @code{events_purge}. You can change this with
1509 @code{events_set_echo}.
1510 @item You can set the adesklet interpreter to send a SIGUSR1 signal every time
1511 an event is printed out to its parent process (the desklet). It is a very
1512 useful IPC, since the signal can be trapped, allowing the event management
1513 routine to run only when necessary. This is what the Python package uses within
1514 its @code{Events_handler} class.
1517 @section SIGCHLD signal handler
1519 Whenever your language allows it, you should install some kind of SIGCHILD
1520 handler, so you can at least be notified if the adesklets interpreter ever
1521 exists without a reason (child zombies notwithstanding)@footnote{@code{man 2
1522 signal} is a very good reference on signals.}.
1524 @section Textual variables
1526 @command{adesklets} also supports differed execution (indirect mode)
1527 and textual replacement of variables. Here how variables work in indirect mode:
1530 @item Once a command is entered, it is stored untouched into the commands
1531 history list, if applicable (in non-interactive usage of the interpreter,
1532 when the command lies bethween calls to @code{start_recording}
1533 and @code{stop_recording})
1534 @item When a macro command is played back (using the @code{play} command,
1535 @xref{Programming adesklets}.), variables get expanded in a single pass, and no
1536 indirect reference is possible. Expansion is pretty straightforward. The stored
1537 command line is scanned for any non-empty sequence of non-space characters
1538 beginning with a single '$'. Each such sequence is replaced with the
1539 corresponding @code{$variable} value, or removed if no variable is found.
1540 @item Expanded command get executed.
1543 The same expansion mechanism also applies to the direct mode of execution. All
1544 this leads to the fact that, using the Python package for instance, these two
1545 code snippets are equivalent:
1548 adesklets.window_resize(100,100)
1554 adesklets.set('dim',100)
1555 adesklets.window_resize('$dim','$dim')
1558 This did not require any alteration of our Python code, since Python is a
1559 dynamic language, but some other languages will require further thinking.
1561 @section Final words
1563 You should now know pretty much everything needed for integrating adesklets with
1564 your language environment. It may appear to be a daunting task, but a very
1565 clean binding can be produced by one programmer in only a few days. Once again,
1566 have a look at @file{src/adesklets_debug.sh}; it is a (very lame) Bourne shell
1567 binding for adesklets written in only fifty lines, including comments.
1569 If you ever need assistance, you are encouraged to post on the
1570 @weblink2{adesklets-devel mailing list,https://lists.sourceforge.net/lists/listinfo/adesklets-devel}...
1576 @chapter Contributing to adesklets
1578 Your help is wanted! You can valuably contribute to adesklets by:
1582 @strong{Posting your adesklets screenshots online}. You use adesklets and think
1583 you have a pretty cool desktop? Share it with the world by posting it online,
1584 and send us a link! This way, you will help people learn about the project.
1586 @strong{Contribute to the documentation}. You have very good written
1587 knowledge of German, Spanish, Portugese, Arab or Swahili? Translators are always
1588 welcomed, proofreaders too, for all languages.
1590 @strong{Writing new desklets}. adesklets is still young: we crave
1591 talented desklets writers, and we would be more than willing to post or link
1592 to your work. Do not worry too much about interface changes; the author spent
1593 considerable effort to ensure that the interface would be fairly stable even
1594 in the earliest releases. It's not frozen forever, but it shouldn't break your
1595 desklets without some warning. At this point, the API is predominantly getting
1596 internal bug fixes and portability improvements.
1598 @strong{Adding bindings for your language of choice}. Contact the developers
1599 beforehand so that you don't waste time on something that is already written;
1600 they will be glad to share code. Subscribe to the
1601 @weblink2{adesklets-devel mailing
1602 list,https://lists.sourceforge.net/lists/listinfo/adesklets-devel} on
1603 SourceForge for quick access to them.
1606 @noindent Contact me by email at @email{syfou@@users.sourceforge.net}.
1608 @node Frequently asked questions
1609 @appendix Frequently asked questions
1611 Last update: @value{UPDATED}
1612 @appendixsection Compiling adesklets
1614 @subheading The adesklets configure script says my Python install is too old, but it's not. What's the problem?
1616 Some platforms (NetBSD, Ubuntu Linux, probably others too) sometimes alter
1617 the Python version, appending letters, prefixing minor numbers, etc., thus
1618 preventing the configuration script from detecting it properly. If you know
1619 @strong{for sure} that what you have installed is at least 2.3.0,
1620 you can pass the @code{--with-python-force-detection} switch to
1621 @code{configure}; this will make the configuration script skip the version
1624 @appendixsection Starting and stopping desklets
1626 @subheading 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?
1628 It means what is written: @command{python} cannot find the @code{adesklets}
1629 package; maybe it did not get installed, or it did get installed in the wrong
1633 @item Restart from the beginning the installation procedure
1634 (@xref{Installing adesklets}.). Make sure you @strong{do not} select
1635 the @code{--without-python-support} configuration option.
1636 @item Retry starting the desklet. If it still does not work, verify that the
1637 installation directory, given by:@example
1638 sed -n '/PYTHON_SITE_PKG/p' Makefile
1640 @noindent is included in :@example
1641 echo 'import sys; print sys.path' | python
1644 @noindent If not, you can still manually move the adesklets directory
1645 from @code{PYTHON_SITE_PKG} to any path displayed by this last command.
1648 @subheading When I try to start a new desklet, I get an @code{ADESKLETSError: adesklets process exited} error from the Python interpreter. What is this?
1650 This is a generic error telling you something is off with the low-level
1651 interpreter, critical enough to cause it to exit. If you are lucky,
1652 you will have at the end of the line a dash, followed by
1653 a descriptive message telling you what went wrong. In that case, if you have
1654 difficulty understanding it, just seek help online. If no clue is given to you regarding the error origin, try this from a pseudo-terminal under X:
1656 echo x_status | adesklets :
1658 You should normally get something similar to:
1661 command 0 ok: x_status 1 (connected to ':0.0')
1664 If you do, you are probably using a system
1665 (@weblink2{archlinux,http://www.archlinux.org/} for instance),
1666 on which the @code{PATH} variable for the Python interpreter differs from
1667 what is inherited from standard environment, which causes the Python package to
1668 fail to launch adesklets as a child process. On such systems, make sure
1669 to install @command{adesklets} using an appropriate @code{--prefix} switch at
1670 the configuration stage. For instance, on most recent Linux platforms, you
1674 ./configure --prefix=/usr
1677 @subheading I cannot run any Python-based desklet: I get garbage collection errors!
1678 If you get errors similar to:
1681 python: Modules/gcmodule.c:275: visit_decref: Assertion `gc->gc.gc_refs != 0' failed.
1685 It means your installment of Python has a corrupted garbage collector; it is
1686 often caused by incorrect or aggressive optimization during the compilation.
1687 Just recompiling a stock python environment from
1688 @weblink{http://python.org/} usually solves this.
1690 @subheading Everything worked fine but then I tried upgrading a desklet, and I couldn't ever see the new one. What is wrong?
1692 There is a built-in lock mechanism in the interpreter that prevents a user from
1693 simultaneously running more than one desklet with the same @code{ID} and name,
1694 regardless of version. Whenever you upgrade a given desklet, you should first
1695 cleanly quit the desklet (by using @code{Quit} from the context menu), then
1696 install the updated desklet by following the instructions provided in the
1699 @subheading 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!
1701 This is most probably related to the way you started the desklet
1702 (Please @pxref{Using adesklets}.). You need to invoke the desklet script
1703 @strong{only once}. Afterwards you just need to run the command:
1709 and it will remember where you placed your desklets and which desklets
1710 you had running. Do not forget the pass flags to @command{adesklets},
1713 @subheading This is exactly what I did, but the darn thing wouldn't restart anyway.
1715 Did you store the desklets under a @file{$HOME/.adesklets} directory?
1717 @command{adesklets} need a @file{$HOME/.adesklets} file to store the various
1718 user settings on running desklets; setting up a directory of the same name
1719 prevents it from doing its job right, so just move your directory some place
1720 else (@file{$HOME/.desklets}, for instance).
1722 @subheading Starting the desklets works fine, but they continue running when I terminate the X session.
1724 Normally, the desklets are supposed to be automatically terminated on the dead of
1725 the session. If you have the frontend shell server installed (the default),
1726 you can also kill them manually by invoking the
1732 command somewhere from the session exit.
1734 @appendixsec Displaying desklets
1736 @subheading Where are my desklets? @command{adesklets} interpreters seem to be running fine, but I just cannot see anything on my desktop (the so-called flickering problem)!
1744 @noindent from the base source directory. If a 100x100 window appears when
1745 testing the desklet, it most probably means you are using a window manager
1746 that draws a big window (so called ``fake'' root window) over the root window;
1747 your desklets are just drawn below it. Such window managers include Nautilus,
1748 KDE, Xfce4, CDE or E17. As on adesklets @value{VERSION}, supported window
1749 managers in that category are:
1752 @item @strong{KDE}: for versions >= 3.4.1 (earlier versions untested).
1753 You need to turn on ``Control Center -> Desktop -> Show icons on desktop ->
1754 Allow programs in desktop window'', or to turn off the ``Show icons on desktop''
1755 altogether@footnote{Thanks to Stefan Jungcurt for the hint.}.
1756 @item @strong{Nautilus}
1757 @item @strong{ROX-Filter}: only preliminary support for now
1758 @item @strong{Xfce4}
1759 @item @strong{xffm-desktop}: only preliminary support for now
1762 From adesklets 0.4.11 and onward, the fake root window detection method had
1763 changed: it is no longer part of the C code by
1764 default@footnote{Although you can get back
1765 the old behavior if you wish by using
1766 @command{--enable-legacy-fake-root-window-detection} at configuration time.
1767 @xref{Installing adesklets}.}. The interpreter now expects
1768 the ADESKLETS_ROOT environment variable to contain the correct fake root
1769 window hexadecimal ID, if any. You can of course set it manually,
1770 but a shell frontend will be handling most common window managers for you
1771 (see list above), as long as you instruct it to. Try invoking:
1777 If the shell frontend is installed, you will get many options, including how to
1778 trigger window managers specific fake root window detection routines.
1779 You also have a ``generic'' fake root window detection under
1780 the switch @command{--user}: it could work (or not) for you, depending on
1781 the structure of your window manager. Finally, please note the frontend
1782 is a simple sh-compatible script, installed by default under
1783 @command{$prefix/share/adesklets} -- it should be pretty
1784 straighforward to modify by anyone wishing to implement other detection schemes.
1786 It is also good to remember that fake root window detection obviously requires
1787 such windows to exist. It is therefore important to invoke
1788 @command{adesklets} @emph{after}
1789 the window manager is reasonably initialized.
1791 @subheading Now I see the desklets, but the transparency is screwed!
1793 Proper pseudo-transparency relies on the capacity to grab the background image
1794 as well as getting notified when it changes. There is no entirely reliable
1795 or even well established method to do this on anything but the real
1796 root window using the core X11 protocol. Hence, even when using a
1797 pseudo root window, adesklets always grab the background from
1798 the real root window. adesklets does its best, when portably possible,
1799 to synchronize the background of the real root window with the one of the
1800 fake root window. In some supported cases (ROX-Filer, xffm-desktop), you will
1801 have to synchronize it yourself, using @command{xsetroot} or similar programs.
1803 @subheading I cannot see smaller desklets such as xmms_bar or asimpleclock, while others work. What gives?
1805 New desklets are always started in the leftmost, upper corner of the screen, at
1806 the very bottom of the windows stack. Make sure you do not have some elements
1807 (gnomebar, engage, etc) already masking this zone of the screen. Beware! Some
1808 applications use pseudo-transparency, and can mask the root window seamlessly.
1810 @subheading 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!
1812 Go see the Fvwm faq: @weblink{http://www.fvwm.org/documentation/faq/#5.11}.
1813 This @code{BugOpts RaiseOverUnmanaged on} option was reported to work for many
1816 @section Running desklets
1817 @subheading The 'Configure' item from the context menu of many desklets doesn't work!
1818 For this to work--at least for all the demo desklets--you need to have
1819 @command{xterm} installed, and the @code{EDITOR} variable properly set in
1820 your environment, as it is customary in UNIX. Please note this only launches a
1821 text editor in a terminal. Editing the desklet's configuration file
1822 (usually @file{config.txt} from base desklet directory) has the same effect.
1824 @subheading Do you plan including SVG support? I would like to use a SVG image in one of my desklets.
1825 No we do not, sorry. It is not
1826 that @weblink2{SVG,http://www.w3.org/Graphics/SVG/} is a bad format; in fact
1827 it is quite good. But it is also a vector-oriented one (and rather complex),
1828 while Imlib2, on which @command{adesklets} relies heavily, is completely
1829 raster-oriented, and using Imlib2 is the main reason for @command{adesklets}'
1830 simplicity, relatively good speed and low resource usage.
1832 That said, there is no reason for you not using SVG's with desklets, since
1833 it is quite easy to convert images in SVG to high quality PNG's,
1834 using programs such as @weblink2{sodipodi,http://www.sodipodi.com/},
1835 @weblink2{inkscape,http://www.inkscape.org/} or @weblink2{xsvg,http://xsvg.org/}.
1836 In a directory full of SVG's, on a GNU system you can use a command such as:
1838 ls *.svg | sed 's/\(.*\).svg/-z --file=& --export-png=\1.png --export-width=128 --export-height=128/' | xargs --max-lines=1 sodipodi
1840 to convert them all to 128x128 semi-transparent PNG's.
1842 @subheading 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?
1844 First, you need to have fontconfig support enabled in adesklets. See the
1845 config.log from the configuration phase to verify it. If you did not keep the
1846 log, you can also look at the dynamic libraries linked against the interpreter.
1847 On a system with GNU binutils, you can do something like:
1849 ldd `which adesklets` | grep fontconfig
1851 If you get output similar to:
1853 libfontconfig.so.1 => /usr/lib/libfontconfig.so.1 (0x45c75000)
1855 it means everything is fine. Otherwise, you should recompile
1856 @command{adesklets} from source. From there, you can use the line:
1858 echo 'list_font_path' | adesklets :
1860 to see all the font directories that adesklets will into look for TrueType
1861 fonts. Consult your fontconfig documentation to learn how to change this
1862 (on up-to-date systems, @code{man 5 fonts-conf} is a good starting point).
1865 echo 'list_fonts' | adesklets :
1867 Will give you all the fonts that are currently found... Keep in mind when
1868 typing them that font names are case-sensitive.
1870 Alternatively, if you just cannot get fontconfig to work, a way to get around
1871 the problem would be to create symbolic links to the fonts you want to use
1872 inside any absolute font paths listed by the command
1873 @code{echo 'list_font_path' ...} above.
1875 @node Python package documentation
1876 @appendix Python package documentation
1878 Here are links to significant sections of the Python package documentation:
1881 @item @weblink2{adesklets,../pydoc/adesklets.html}
1882 @item @weblink2{adesklets.events_handler,../pydoc/adesklets.events_handler.html}
1883 @item @weblink2{adesklets.commands,../pydoc/adesklets.commands.html}
1884 @item @weblink2{adesklets.utils,../pydoc/adesklets.utils.html}
1885 @item @weblink2{adesklets.configfile,../pydoc/adesklets.configfile.html}
1890 @node Imlib2 documentation
1891 @appendix Imlib2 documentation
1893 Carsten Haitzler (@email{raster@@rasterman.com}) took the time to produce very
1894 nice cross-referenced documentation for Imlib2, but for some reason (size
1895 considerations most probably), it is not included in the Imlib2 source
1896 tarball@footnote{Although it can be quite easily regenerated using doxygen.}.
1899 have it @weblink2{here,../imlib2}.
1903 find it online at @weblink{http://adesklets.sf.net/doc/imlib2/}.
1906 Most functions of the Imlib2 API have corresponding, homonymic commands
1907 in @command{adesklets}. @xref{Programming adesklets}, for specific details
1908 on the transition from direct Imlib2 programming in C to adesklets.
1910 @node Packaging GNU Makefile for desklets
1911 @appendix Packaging GNU Makefile for desklets
1913 Here is a convenient Makefile that automates the packaging of new or
1914 existing desklets on a GNU system. Just copy the Makefile below
1915 into @file{GNUmakefile} from your base desklet directory to use it.
1916 There is nothing at all to edit, provided you named your base directory
1917 in a proper 'NAME-MAJOR.MINOR.REVISION' fashion, such as @code{beast-0.666.0}.
1919 @verbatiminclude ../utils/GNUmakefile.desklet
1921 @node Submitting a desklet
1923 @appendix Submitting a desklet
1925 @section Desklet package requirements
1926 Requirements for ``official'' desklets packages are scarce; authors are free to
1927 do as they wish. There are only two things that should be enforced:
1929 @item A meaningful @file{README} file should exist in the base source directory
1930 of the desklet archive and be kept up to date. It should at least contain:
1932 @item the name and contact email adress of the author@footnote{It is probably
1933 not a good idea to give away your private email adress here;
1934 for spam-related reasons, you should probably open an account
1935 on @weblink2{SourceForge,http://sourceforge.net/}, or at another similar place
1936 with a serious spam containment infrastructure.}
1937 @item a short description of the desklet
1938 @item the requirements for running it
1941 @item The package should be a bzip'ed tarball containing a single source
1942 directory of the form @code{NAME-MAJOR.MINOR.REVISION}, where @code{NAME} is
1943 the desklet base name, and @code{MAJOR.MINOR.REVISION} the version. Please note
1944 that a makefile (@xref{Packaging GNU Makefile for desklets}.) is also provided
1945 to automate creation of such an archive on GNU systems.
1948 @section The @command{adesklets_submit} script
1950 Starting in @command{adesklets} 0.4.4, desklet authors are provided with a
1951 Python script to automate the submission of their desklets:
1952 @file{utils/adesklets_submit} from the source package. Use the
1953 @code{--with-python-install-submission-scripts} option at configuration time
1954 to place it in your @code{bindir} directory upon installation.
1956 @file{adesklets_submit} can be used to:
1958 @item Submit a new or updated desklet description for inclusion on the
1959 @weblink2{adesklets web site,http://adesklets.sf.net/desklets.html};
1960 @item Submit a bzip'ed desklet archive for inclusion in SourceForge's desklets
1961 package (this is optional--you may choose to host it yourself).
1964 @section Invoking @command{adesklets_submit}
1965 Desklet submission is initiated by sending a specially crafted email to
1966 @email{adesklets@@mailworks.org}@footnote{It is useless to send anything else
1967 to this address; all messages that cannot be parsed by the automatic reception
1968 script are just silently dropped. Write to @email{syfou@@users.sourceforge.net}
1969 instead if you want to get in touch with the maintainer.}.
1970 The @command{adesklets_submit} script assits you in the construction of
1971 such an email using the user configuration file @file{$HOME/.adesklets_submit}
1972 and the command line switches. Here is an example of a valid
1973 @file{$HOME/.adesklets_submit} configuration:
1975 @verbatiminclude ../utils/adesklets_submit.example
1977 This is pretty self-explanatory, but here are a few less obvious points:
1981 Try to avoid using pseudonyms and nicknames for the @code{author_name} as much
1982 as possible, unless, of course, you already have a pretty well-established
1983 online identity under this name.
1985 @code{send_confirmation} specifies if an email should be sent back to your
1986 @code{author_email} address whenever your desklet is succesfully published.
1987 If the submitted entry is rejected, you will always be written back anyway
1988 with an explanation. Usually, the maintainer will not try to make changes to
1989 problematic entries; it will only summarize back to the author what was not OK.
1991 @emph{Double check} your @code{author_email} address, since this is the only
1992 one the maintainer will try to use when contacting you, regardless of what
1993 the headers say. Failing to supply a valid address will cause all messages to
1994 fail to be sent to you, and all new desklet entries will be rejected.
1996 You can very well use adesklets_submit without any prior contact with the adesklets
1997 maintainer (either via email, within the forum using this adress for
1998 registration, or through the mailing list), but some back and forth will be
1999 needed before publication just to assert your identity and its effective
2000 relation to the provided email address.
2002 @code{desklets} is a dictionary of dictionaries (one dictionary per desklet,
2003 desklets' names being the keys); all the items referring to files (thumbnail,
2004 screenshot and download) could either be publicly accessible URI's (this is the
2005 preferred method), or local files, either absolute or relative to your $HOME
2006 directory. In that case, needed files will be attached to the generated
2009 All images will always be fetched and integrated on the adesklets.sf.net
2010 web site; you can safely remove them from your online location afterwards
2011 if you provided live URI's.
2013 When updating already included desklets, there is no need to submit back
2014 the @code{thumbnail} or @code{screenshot} images if they did not change;
2015 you can just as easily reference the already installed images on SourceForge:
2017 @item The @code{thumbnail} is always stored under
2018 @code{http://adesklets.sf.net/images/NAME_thumb.[jpg|png]}
2019 @item The @code{screenshot} is always stored under
2020 @code{http://adesklets.sf.net/images/NAME_screen.[jpg|png]}
2021 where @code{NAME} is the name of the desklet.
2024 Using the @code{host_on_sourceforge} value, you can choose to have
2025 your desklet package either hosted on SourceForge or just referenced
2026 on your site if you provided a URI. Of course, choosing this last
2027 alternative also means you will need to keep it in place.
2029 The @code{thumbnail} image should be a JPG (preferably) or PNG (if you
2030 @emph{really} need higher resolutions) of dimensions lying between 190x35 and
2033 The @code{screenshot} image should be a 640x480 JPG (preferably) or PNG.
2034 It should put your desklet in evidence, and thus contain no other ones.
2036 You can choose not to submit thumbnails and/or screenshots. In that case,
2037 default, generic images will be used instead.
2039 @code{Category} is unused for now, and just ignored.
2041 All emails weighing more than 300 KB will be rejected by the maintainer's
2042 email server; thus, adesklets_submit will refuse to generate them. Instead of
2043 submitting such big entries, use the URI facility described above to trim
2045 @item @command{adesklets_submit} does not enforce the requirements above; it only
2046 checks what is strictly required to build a compliant submission email:
2047 the existence of dictionary entries, availability of files, the validity
2048 of file types if they are local... It is your duty to make sure the entries
2049 meet the other requirements if you want to avoid rejection.
2052 For example, Belial Leviathan would fisrt check his @code{beast} desklet's
2053 entry by doing something similar to:
2055 adesklets_submit beast
2058 If everything goes fine, it will output the resulting submission email
2059 on @code{stdout}. From there, Belial can either:
2061 @item Pipe it to his favorite MTA (mail transfert agent) to send it to
2062 @email{adesklets@@mailworks.org}.
2063 @item Make @command{adesklets_submit} send it itself by SMTP, using the
2064 @code{smtp_host} and @code{smtp_port} parameters in its
2065 @file{$HOME/.adesklets_submit}. For this, Belial would use:
2068 adesklets_submit --send beast
2071 One last thing: you should try to avoid sending minor corrections multiple
2072 times, especially if you use local files. It both adds to the workload of the
2073 maintainer's email server and to the management work. Please try to create a
2074 valid entry @emph{then} send it, not the other way around.
2076 @appendixsubsec Further submission validation using @command{adesklets_checkin}
2077 From @command{adesklets} 0.4.5, you now have access to the
2078 @command{adesklets_checkin} script as well. This is the Python
2079 script that the maintainer uses for checking in all submissions.
2080 @emph{Be aware that this script is only provided to desklet authors as a
2081 convenience, to lower their submission rejection count--developers are in no
2082 way forced to use it, and may even be unable to do so, since the script was not
2083 written with portability in mind as adesklets_submit was. Look at the script
2084 header for a complete list of requirements.}
2086 @command{adesklets_checkin} has two modes of operation: interactive and
2087 non-interactive. Only the non-interactive mode will interest desklet authors.
2088 In this mode, usage is fairly simple. Belial, for instance, would do:
2090 adesklets_submit beast | adesklets_checkin
2093 If everything goes fine, an output similar to this will be produced:
2095 Validation started. Please wait.
2096 Everything seems fine, but keep in mind a few things cannot be
2097 verified without human intervention. See documentation for details.
2100 If not, you will get an exception trace with some (hopefully) meaningful
2103 @appendixsubsec Limitations of @command{adesklets_checkin} in non-interactive mode
2105 Here are the remaining problems that @command{adesklets_checkin}
2106 cannot detect and thus must absolutely be solved manually
2107 (the maintainer would interactively catch most of them, and you would have to
2111 Incomplete README file in base directory (Does it contain all the details
2114 Out-of-date README file (Does its content reflect the current state
2117 Desklet fails to run out-of-the-box (i.e. with or without minimal
2118 configuration) when requirements in the README file are met and special
2119 instructions are followed.
2122 @node Copying This Manual
2123 @appendix Copying This Manual
2126 * GNU General Public License:: License for copying this manual.
2131 @node Open PGP Public Key
2132 @appendix Open PGP Public Key
2134 @verbatiminclude syfou.asc
2136 @noindent You can also get this certificate from many public key servers on
2137 the internet, such as @weblink{http://www.keyserver.net/}, or
2138 @weblink{http://pgp.mit.edu/}. Contact its rightful owner,
2139 Sylvain Fourmanoit, by email at @email{syfou@@users.sourceforge.net}
2140 to arrange further key validation if you need any.