GTKPBBUTTONS.THEMES(5)GTKPBBUTTONS.THEMES(5)NAME
gtkpbbuttons.themes - description of theme creation
GENERAL
Themes for gtkpbbuttons are placed each in a separate directory in name
of the theme.
Inside of each theme directory a file named theme.desc must exist. All
other files could get names of choice. Usually a theme directory con‐
tain beside the file theme.desc only graphic and sound files. No other
files are useful for gtkpbbuttons themes.
The file theme.desc contain the theme description and is very impor‐
tant. A theme without this file won't be accepted as valid theme.
Picture files are limited to those formats that GTK+ 2.0 or later sup‐
ports. Besides this pictures with a alpha mask should be used. Other‐
wise some effects couldn't be realised or give strange results. So the
usage of png picture format is recommended.
The Audio files are handles by libaudiofile version 1.9 or later. All
formats this library supports could be used.
THEME.DESC
As already mentioned this file describes the theme. The structure is
very easy and mostly known from various configuration files.
Lines starting with # are comments. Comments could also places after ;
often used behind parameters. The text after those characters until the
end of the line will be ignored.
Empty lines will be ignored.
Parameters follow the structure
parameter = argument
Gtkpbbuttons supports seven popup windows. For each of them a couple of
parameters exist.
The parameters are divided in two section: global parameters and layout
dependent parameters. Global parameters would be explained in the next
paragraph and layout dependent parameters in the layout section of this
man page.
GLOBAL PARAMETERS OF THEME.DESC
Global parameters describe preferences of the main popup window and
some administrative parameters of each popup. A full list of global
parameters are described below:
layout=classic or macosx
Layout engine
bgimage=image file
Background image for the window.
brightness.active=true or false
Should brightness popup be displayed or not?
brightness.timeout=value
Time how long the brightness popup should be shown in 10th of a
second before it vanishes again.
volume.active=true or false
Should sound popups be displayed or not? This include the mute
and the noaudio popup so that this popups doesn't have the
active parameter by their own.
volume.timeout=value
Time how long the brightness popup should be shown in 10th of a
second before it vanishes again. This value will also be used
for the mute popup window.
noaudio.timeout=value
Time how long the warning should be shown if no audio device was
found. The value must be given in 10th of a second.
mouse.active=true or false
Should the trackpad configuration popup be displayed or not?
mouse.timeout=value
Time how long the mouse/trackpad popup should be shown in 10th
of a second before it vanishes again.
battery.active=true or false
Should the battery warning popup be displayed or not?
battery.timeout=value
Time how long the battery warning should be shown before is van‐
ishes again. The value must be given in 10th of a second.
sleep.active=true or false
Should the sleep popup be displayed or not?
sleep.timeout=value
Time how long the sleep popup should be shown in 10th of a sec‐
ond before it vanishes again.
kbdillu.active=true or false
Should keyboard illumination popup be displayed or not?
kbdillu.timeout=value
Time how long the keyboard illumination popup should be shown in
10th of a second before it vanishes again.
cdrom.active=true or false
Should ejecting CDROMs shown as popup or not?
cdrom.timeout=value
Time how long the eject cdrom popup content be shown in 10th of
a second before it vanishes again.
crtmirror.active=true or false
Should activating external video shown as popup or not?
crtmirror.timeout=value
Time how long the external video popup content be shown in 10th
of a second before it vanishes again.
LAYOUTS
A layout is a basic structure for gtkpbbuttons themes. They define how
the popup windows are structured. The content of this structures could
be changed but the layout is a fix part of the code. New layouts
require a little bit of coding and a new version of gtkpbbuttons.
Currently two layout engines are implemented: Classic and MacOSX. Each
theme must chose one of this engines or the theme will be rejected.
LAYOUT CLASSIC
The classic layout is well known because it is used by gtkpbbuttons in
the past. It uses standard GTK windows and widgets.
Orientation: horizontal
Structure: image1 - progress bar or text - image2
All Global parameters and the following list of layout dependent param‐
eters are supported:
brightness.image1=image file
Left image of the brightness popup. If this parameter is empty
or missing, no image will be displayed. The popup window shrinks
in size respectively.
brightness.image2=image file
Right image of the brightness popup. If this parameter is empty
or missing, no image will be displayed. The popup window shrinks
in size respectively.
volume.image1=image file
Left image of the volume popup. If this parameter is empty or
missing, no image will be displayed. The popup window shrinks in
size respectively.
volume.image2=image file
Right image of the volume popup. If this parameter is empty or
missing, no image will be displayed. The popup window shrinks in
size respectively.
volume.sample=sound file
Audio sample to play if the volume popup occur. This will help
to adjust the right volume. Only short samples should be used
for best performance. If this option is empty or missing the
volume popup will be quiet.
mute.image1=image file
Left image of the mute popup. If this parameter is empty or
missing, no image will be displayed. The popup window shrinks in
size respectively.
mute.image2=image file
Right image of the mute popup. If this parameter is empty or
missing, no image will be displayed. The popup window shrinks in
size respectively.
noaudio.image1=image file
Left image of the noaudio popup. If this parameter is empty or
missing, no image will be displayed. The popup window shrinks in
size respectively.
noaudio.image2=image file
Right image of the noaudio popup. If this parameter is empty or
missing, no image will be displayed. The popup window shrinks in
size respectively.
mouse.image1=image file
Left image of the mouse/trackpad popup. If this parameter is
empty or missing, no image will be displayed. The popup window
shrinks in size respectively.
mouse.image2=image file
Right image of the mouse/trackpad popup. If this parameter is
empty or missing, no image will be displayed. The popup window
shrinks in size respectively.
battery.image1=image file
Left image of the battery popup. If this parameter is empty or
missing, no image will be displayed. The popup window shrinks in
size respectively.
battery.image2=image file
Right image of the battery popup. If this parameter is empty or
missing, no image will be displayed. The popup window shrinks in
size respectively.
battery.sample=sound file
Audio sample to play if the battery warning popup occur. This is
could be used as an additional alarm signal. Only short samples
should be used for best performance. If this option is empty or
missing the battery warning popup will be quiet.
sleep.image1=image file
Left image of the sleep popup. If this parameter is empty or
missing, no image will be displayed. The popup window shrinks in
size respectively.
sleep.image2=image file
Right image of the sleep popup. If this parameter is empty or
missing, no image will be displayed. The popup window shrinks in
size respectively.
kbdillu.image1=image file
Left image of the keyboard illumination popup. If this parameter
is empty or missing, no image will be displayed. The popup win‐
dow shrinks in size respectively.
kbdillu.image2=image file
Right image of the keyboard illumination popup. If this parame‐
ter is empty or missing, no image will be displayed. The popup
window shrinks in size respectively.
cdrom.image1=image file
Left image of the eject cdrom popup. If this parameter is empty
or missing, no image will be displayed. The popup window shrinks
in size respectively.
cdrom.image2=image file
Right image of the eject cdrom popup. If this parameter is empty
or missing, no image will be displayed. The popup window shrinks
in size respectively.
crtmirror.image1=image file
Left image of the external video popup. If this parameter is
empty or missing, no image will be displayed. The popup window
shrinks in size respectively.
crtmirror.image2=image file
Right image of the external video popup. If this parameter is
empty or missing, no image will be displayed. The popup window
shrinks in size respectively.
LAYOUT MACOSX
This layout is sympathized with MacOS X. It displays an translucent
window with rounded edges. The main area of this window is occupied by
an descriptive image. The appropriate object in the lower area could be
a progress bar,
a text or another image.
Orientation: vertical
Structure: image - progress bar or text or tpmode image
All Global parameters and the following list of layout dependent param‐
eters are supported:
pbarempty=image file
Image for an empty progress bar. This is globally used for all
popup windows.
pbarfull=image file
Image for a full progress bar. This is globally used for all
popup windows.
pbarsteps=value
This parameter defines for discrete progress bars how many steps
it has. For example you design a progress bar image with five
discrete blocks and you want that the progress bar change its
value only in full blocks. In this example specify pbarsteps =
5.
If you specified pbarsteps = 0, the progress bar wouldn't be
split up into blocks. The highest possible resolution for the
progress bar is used.
textfmt=pango format string
Some popup windows uses small text messages. This option defines
the text format used for all text messages in pango style. Pango
is a part of GTK 2 responsible for text rendering. It uses a tag
structure similar but not identical to HTML. Each Parameter fol‐
low the structure: <keyword>="<value>". The values must always
be embraced by double quotation marks. Single quotation marks
must border the whole string because the parameters have to be
separated with spaces.
example: textfmt='foreground="white" weight="bold"'
The following parameter will be understood by pango up to now:
font_desc
A font description string, such as "Sans Italic 12"; note that
any other span attributes will override this description. So if
you have "Sans Italic" and also a style="normal" attribute, you
will get Sans normal, not italic.
font_family
A font family name
face
Synonym for font_family
size
Font size in 1000ths of a point, one of the absolute sizes 'xx-
small', of the relative sizes 'smaller' or 'larger'.
style
One of 'normal', 'oblique', 'italic'
weight
One of 'ultralight', 'light', 'normal', 'bold', 'ultrabold',
'heavy', or a numeric weight
variant
One of 'normal' or 'smallcaps'
stretch
One of 'ultracondensed', 'extracondensed', 'condensed', 'semi‐
condensed',
foreground
An RGB color specification such as '#00FF00' or a color name
such as 'red'
background
An RGB color specification such as '#00FF00' or a color name
such as 'red'
underline
One of 'single', 'double', 'low', 'none'
rise
Vertical displacement, in 10000ths of an em. Can be negative for
subscript, positive for superscript.
strikethrough
Either 'true' or 'false' whether to strike through the text
lang
A language code, indicating the text language
This list might be extended in future. Please see GTK documenta‐
tion for full list.
brightness.image=image file
Image of the brightness popup. If this parameter is empty or
missing, no image will be displayed.
volume.image=image file
Image of the volume popup. If this parameter is empty or miss‐
ing, no image will be displayed.
volume.sample=sound file
Audio sample to play if the volume popup occur. This will help
to adjust the right volume. Only short samples should be used
for best performance. If this option is empty or missing the
volume popup will be quiet.
mute.image=image file
Image of the mute popup. If this parameter is empty or missing,
no image will be displayed.
noaudio.image=image file
Image of the noaudio popup. If this parameter is empty or miss‐
ing, no image will be displayed.
mouse.image=image file
Image of the mouse/trackpad popup. If this parameter is empty or
missing, no image will be displayed.
mouse.mode0=image file
mouse.mode1=image file
mouse.mode2=image file
mouse.mode3=image file
Image files to visualize the different trackpad modes. If one of
this parameters is empty or missing, the corresponding image
will not be displayed.
battery.image=image file
Image of the battery popup. If this parameter is empty or miss‐
ing, no image will be displayed.
battery.sample=sound file
Audio sample to play if the battery warning popup occur. This is
could be used as an additional alarm signal. Only short samples
should be used for best performance. If this option is empty or
missing the battery warning popup will be quiet.
sleep.image=image file
Image of the sleep popup. If this parameter is empty or missing,
no image will be displayed.
kbdillu.image=image file
Image of the keyboard illumination popup. If this parameter is
empty or missing, no image will be displayed.
cdrom.image=image file
Image of the eject cdrom popup. If this parameter is empty or
missing, no image will be displayed.
crtmirror.image=image file
Image of the external video popup. If this parameter is empty or
missing, no image will be displayed.
AUTHOR
Matthias Grimm.
February 22, 2004 GTKPBBUTTONS.THEMES(5)