1
<section id="dsp-tag-display" xmlns:xi="http://www.w3.org/2001/XInclude">
2
<title><display></title>
4
<para>This is the root element of every display file. It represents the
5
display window on the screen. Apart from being a toplevel window, it is
7
<link linkend="dsp-tag-group"><group>.</link> and inherits all of its
11
<section><title>Attributes</title>
12
<informaltable frame="topbot">
18
<entry>Default Value</entry>
19
<entry>Description</entry>
24
<entry>bg-color</entry>
26
<entry>#00000000</entry>
27
<entry>The background color of the display. You may use the
28
alpha channel for color values to achieve translucency.</entry>
34
<entry valign="top">The background image of the display. Overrides
35
<property>bg-color</property>. If the image does not fit the
36
window, it gets tiled over it.</entry>
39
<entry>desktop-borders</entry>
40
<entry>unit list</entry>
42
<entry valign="top">The desktop borders settings, if the window manager
43
supports desktop struts.
44
This property takes a list of two unit values, horizontal and
45
vertical. Each value specifies the distance of the border from the
46
desklet window. See below for details and examples.</entry>
52
<entry valign="top">The window icon.</entry>
58
<entry valign="top">The shape of the window. Images with an alpha
59
channel can be used for changing the shape. All completely
60
transparent parts result in holes in the window.</entry>
66
<entry valign="top">The window title.</entry>
69
<entry valign="top">window-flags</entry>
70
<entry valign="top">string list</entry>
71
<entry valign="top">decorated, managed</entry>
72
<entry valign="top">Attribute flags for the window. See below for a
73
list of the supported flags.
74
<literal>above, below, decorated, managed, sticky</literal>.
84
<section><title>Window Flags</title>
86
<para>Window flags can change the appearance and the behavior of a window.
87
The following flags are recognized by
88
<application>gDesklets</application>:</para>
91
<listitem><literal>above</literal> - The window appears above all normal
92
windows and cannot be lowered.</listitem>
93
<listitem><literal>below</literal> - The window appears below all normal
94
windows and cannot be raised.</listitem>
95
<listitem><literal>decorated</literal> - A decorated window has a titlebar
96
and a window frame.</listitem>
97
<listitem><literal>managed</literal> - A managed window is controlled by
98
the window manager, not by <application>gDesklets</application>.
100
<listitem><literal>sticky</literal> - The window appears on all
101
workspaces.</listitem>
105
<para>The ideal combination for desktop applets is <literal>sticky,
106
below</literal>.</para>
112
<section><title>Desktop Borders <emphasize>[new in 0.35]</emphasize></title>
114
<para>Desktop borders define areas on the desktop which cannot be covered
115
by maximized windows. Panels (i.e. gnome-panel, pypanel) use this
116
feature, for example.</para>
118
<para>Display windows take two arguments for the border settings. One for
119
a horizontal border and one for a vertical border. The values specify the
120
distance of the border from the display window. For example, a desklet at
121
the bottom edge of the screen with a vertical border value set to
122
<literal>0</literal> (i.e. <literal>desktop-borders=",0"</literal> will
123
set a "virtual desktop border" along the desklet's top edge. If the
124
desklet, however, is nearer towards the top edge of the screen, the border
125
will be along its bottom edge.</para>
127
<para>When increasing the border value (greater than <literal>0</literal>),
128
the border will be shifted away from the screen's edge by that amount.
129
Negative values pull the border towards the screen's edge. If you unset
130
the value (leave it empty) the border will be turned off. You can do this
131
with the unit constructor <literal>Unit()</literal> in an inline script.
135
<para>Desktop borders might by annoying sometimes. So if your desklet supports
136
desktop borders, please also provide an option to turn off that behavior!
144
<section><title>Examples</title>
146
<programlisting><![CDATA[
147
<display window-flags="sticky, below" bg-color="white"
148
width="100" height="100"
149
desktop-borders=",0">
151
<!-- This sets the height and width of the desklet to
152
100 pixels, puts the desklet below all other
153
windows and on every virtual desktop, and sets
154
the top or bottom "virtual border" of the desktop
155
to be exactly at the edge of the desklet.
164
window-flags="sticky, above"
165
desktop-borders="-20,">
167
<!-- This sets the left or right "virtual border"
168
of the desktop to be 20 pixels below or above
169
the top or bottom of the desklet, respectively.
175
<!-- Add a configuration option so the user can
176
set how much of a space between the desklet's
177
side and a maximized window he or she would
180
<integer label="Side Border Placement:"
182
bind="tb_border" callback="border_chg"/>
192
def border_chg(key, value):
194
# desktop-borders expects a list of Unit types
195
# so that's what we have to give it. The
196
# second argument is just the Unit constructor,
197
# which is like leaving the second argument blank
198
# in the <display> tag above.
199
Dsp.win.desktop_borders = [Unit(value,PX),Unit()]
added
removed
doc/book/dsp-tag-display.xml
