This is the root element of every display file. It represents the display window on the screen. Apart from being a toplevel window, it is similar to a <group>. and inherits all of its properties.
Name | Type | Default Value | Description |
---|---|---|---|
bg-color | color | #00000000 | The background color of the display. You may use the alpha channel for color values to achieve translucency. |
bg-uri | URI | The background image of the display. Overrides bg-color. If the image does not fit the window, it gets tiled over it. | |
desktop-borders | unit list | The desktop borders settings, if the window manager supports desktop struts. This property takes a list of two unit values, horizontal and vertical. Each value specifies the distance of the border from the desklet window. See below for details and examples. | |
icon | URI | The window icon. | |
shape | URI | The shape of the window. Images with an alpha channel can be used for changing the shape. All completely transparent parts result in holes in the window. | |
title | string | The window title. | |
window-flags | string list | decorated, managed | Attribute flags for the window. See below for a list of the supported flags. above, below, decorated, managed, sticky. |
Window flags can change the appearance and the behavior of a window. The following flags are recognized by gDesklets:
![]() |
|
The ideal combination for desktop applets is sticky, below. |
Desktop borders define areas on the desktop which cannot be covered by maximized windows. Panels (i.e. gnome-panel, pypanel) use this feature, for example.
Display windows take two arguments for the border settings. One for a horizontal border and one for a vertical border. The values specify the distance of the border from the display window. For example, a desklet at the bottom edge of the screen with a vertical border value set to 0 (i.e. desktop-borders=",0" will set a "virtual desktop border" along the desklet's top edge. If the desklet, however, is nearer towards the top edge of the screen, the border will be along its bottom edge.
When increasing the border value (greater than 0), the border will be shifted away from the screen's edge by that amount. Negative values pull the border towards the screen's edge. If you unset the value (leave it empty) the border will be turned off. You can do this with the unit constructor Unit() in an inline script.
![]() |
|
Desktop borders might by annoying sometimes. So if your desklet supports desktop borders, please also provide an option to turn off that behavior! |
<display window-flags="sticky, below" bg-color="white" width="100" height="100" desktop-borders=",0"> <!-- This sets the height and width of the desklet to 100 pixels, puts the desklet below all other windows and on every virtual desktop, and sets the top or bottom "virtual border" of the desktop to be exactly at the edge of the desklet. --> ... </display> <display id="win" window-flags="sticky, above" desktop-borders="-20,"> <!-- This sets the left or right "virtual border" of the desktop to be 20 pixels below or above the top or bottom of the desklet, respectively. --> ... <prefs> <!-- Add a configuration option so the user can set how much of a space between the desklet's side and a maximized window he or she would like. --> <integer label="Side Border Placement:" min="-500" bind="tb_border" callback="border_chg"/> </prefs> ... <script> <![CDATA[ tb_border = -20 def border_chg(key, value): # desktop-borders expects a list of Unit types # so that's what we have to give it. The # second argument is just the Unit constructor, # which is like leaving the second argument blank # in the <display> tag above. Dsp.win.desktop_borders = [Unit(value,PX),Unit()] </display>