Using adesklets - adesklets 0.6.1
Description: adesklets 0.6.1

Next: Programming adesklets, Previous: Installing adesklets, Up: Top

## 4 Using adesklets

### 4.1 ... As a desklets container

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

Right now, many desklets exist: you may find them on adesklets web page as separate downloads: http://adesklets.sf.net/desklets.html.

#### 4.1.1 Add a new desklet to your X display

To add a new desklet script, simply:

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

From adesklets 0.4.11, Python-based desklets will ask you explicitely if you want to register or to test them. They will also support a `--help` switch, that you can use to know the useful options you can pass to the adesklets interpreter when testing (fake root window detection, etc.). Same goes for Perl-based desklets.

Please note that:

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

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

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

##### Alternative to manually downloading the desklets

Since adesklets 0.5.0, you have a new `adesklets_installer` script available if you installed the package with Python support: it provides you with automated management of your desklets under `$HOME/.desklets` through a simple interactive interface. From a real or pseudo-terminal, invoke:

         adesklets_installer

Or, if you have the adesklets shell frontend:

         adesklets -i

It is able to detect what desklets you have, and to download, check integrity and unpack new ones based on the information contained in the official desklets atom feed (http://adesklets.sf.net/desklets.atom). Of course, it is still your duty to manually configure and launch them from there.

The `adesklets_installer` script comes with three user interfaces: a Tk interface (the default, based on the Tkinter module), a curses interface as well as a raw interface, that just assumes a trivial terminal is present (characters-based `stdin` and `stdout` streams). By default, the script will try to present to the user the first it can in the given order, then fallback to the next if it doesn't work 1, but you can select one as well from the command line. See:

         adesklets_installer --help

for the invocation details.

##### Special notes on system fonts

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

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

##### Special notes on internationalization

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

If your system includes `iconv` support (See Installing adesklets.), you should be able to use any character from any charsets your system knows about for displaying text, either inside a desklet or in its menus, provided you have appropriate TrueType fonts (i.e. TrueType fonts containing those character representations)2.

Nevertheless, when using extended (outside 7-bit `ASCII`) characters, you need to make sure your local GNU readline settings do not interfere. These three parameters should be set as indicated below in the appropriate `initrc` file3:

         set input-meta on
         set convert-meta off
         output-meta on

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

Of course, you will also need desklets built to use those extended characters. At the time of writing, all non-contributed Python desklets support them; for those, the charset can be set by the user in the configuration file, when it exists4; users merely have to set the 'coding' line appropriately5.

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

         # -*- coding: ISO-8859-1 -*-

as the first or second line in the Python desklet configuration file6.

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

#### 4.1.2 Restore previously running desklets on new X session

Invoking `adesklets` without any arguments7:

         adesklets

is enough to restart all desklets that were running the last time you killed the X server (in this mode, `adesklets` will exit quickly by itself: there is no need to run it in the background. adesklets does not use a daemon; each applet will fork a standalone `adesklets` interpreter as a child process). Invoking `adesklets` when desklets are already running will cause them to be killed before the creation of new instances8.

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

Since adesklets 0.4.11, a more complete shell based frontend is available to you, if you installed it (which is the default). It gives you a more feature-complete set of options. Run

         adesklets --help

To see what is at your fingertips. Please note that since adesklets 0.4.11, you usually must specify on the command line proper flags if you need fake root window detection (See Frequently asked questions.).

### 4.2 ... As a command-line graphic editor

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

         adesklets :

You will get something similar to:

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

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

#### Footnotes

[1] The raw interface should always work at the end of the day.

[2] For instance, Bitstream's Vera font included with `adesklets` contains glyphs for practically all Latin-1 (ISO-8859-1) characters.

[3] Please refer to your GNU readline documentation

[4] When it does not exist, it means the desklet does not need internationalization anyway

[5] See http://python.fyxm.net/peps/pep-0263.html

if you need details.

[6] Obviously, such a configuration file needs to be saved using ISO Latin-1 encoding or any subset of it, such as `ASCII`.

[7] A word of warning: by default on adesklets 0.4.11 and up, you need to employ some flags if your Window Manager uses a fake root window. See Frequently asked questions.

[8] Both `adesklets` process and their immediate parents will be sent a `SIGKILL` signal.