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 contain 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 important. 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 supports. Besides this pictures with a alpha mask should be used. Otherwise 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 vanishes 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 second 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 parameters 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 window shrinks in size respectively.

kbdillu.image2=image file
    Right image of the keyboard illumination popup. If this parameter 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 parameters 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 follow 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', 'semicondensed',

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 documentation 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 missing, 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 missing, 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 missing, 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.