This reference covers most of the bmpanel2 theme elements.

Common parameters

There are two types of mostly common parameters. The image and the font.

Image

The image is specified using filename and optional rectangle. The rectangle defines which part of the image should be used.

image file.png
        xywh 0 0 50 30
xywh

Defines the rectangle. Origin (X, Y) and width, height respectively.

Font

The font is specified using font name, its parameters and other drawing parameters. The font itself is specified by the string: "[FAMILY-LIST] [STYLE-OPTIONS] [SIZE]". STYLE-OPTIONS are optional.

font DejaVuSans bold 14
        color 20 20 20
        offset 0 1
        align center
        shadow_color 220 220 220
        shadow_offset 0 1
color

Three numbers for red, green and blue color components respectively. From 0 (min intensity) to 255 (max intensity).

offset

An offset for drawing text. Two numbers - horizontal and vertical offset respectively.

align

Text alignment. This parameter use is limited, since not all elements may align text differently. Possible values are: left, center, right. The default is center.

shadow_color

The color of the shadow. Three numbers just like in color. Only useful if shadow_offset values aren’t zero.

shadow_offset

An offset for drawing a shadow (relative to text position). Two numbers - horizontal and vertical offset respectively. If both values are zero, then the shadow isn’t drawn.

General parameters

Parameters that are essential for each theme.

Panel section

Each theme must contain a panel section.

panel
        position bottom
        separator separator_img.png
        background tile_img.png
        #transparent
        #align center
        #width 70%
position

Defines a position of the panel. Possible values are: bottom, top.

separator

Defines a tiny image which is drawn between widgets.

separator.png

background

Defines a background image of the panel.

background.png

transparent

This is a boolean parameter. If it presents, then bmpanel2 uses pseudo-transparent renderer. Useful for transparent themes.

align

Defines an alignment of the panel. Useful only with non-default width parameter. Possible values are: left, center, right. The default is center.

width

Defines a width of the panel. The width may be presented in pixels or in percents. Examples: 300, 800, 80%, 30%. The default value is 100%.

Theme section

There is also an optional theme section.

theme
        name Native
        author nsf <no.smile.face@gmail.com>

This section is used for displaying info about theme and its author in "--list" command listing. It looks like this:

[nsf @ ~]$ bmpanel2 --list
listing themes in "/home/nsf/.local/share/bmpanel2/themes":
 - none
listing themes in "/usr/share/bmpanel2/themes":
 * transpy (name: Transpy, author: nsf <no.smile.face@gmail.com>)
 * xsocam_dark
 * native (name: Native, author: nsf <no.smile.face@gmail.com>)
 * xsocam
 * noir
listing themes in "/usr/local/share/bmpanel2/themes":
 - none

As you can see, additional info is displayed. I’m not sure why I need this, but why not. :D

name

Name of the theme.

author

Information about the author of the theme. I prefer mail-like convention: NAME <EMAIL>.

Common widget parameters

These parameters may be applied to each of the following widgets. Currently there is only one parameter.

desktop_switcher
        no_separator
        # ...

taskbar
        # ...

systray
        no_separator
        # ...
no_separator

If the no_separator parameter presents in a widget, the panel/separator will not be drawn near that widget. Each widget controls only one separator and it depends on a relative position to the taskbar widget. I hope the image will help you understand the idea.

widget_separator.png

Specific widget parameters

Parameters for built-in widgets. Also few general moments:

  1. Widget placement order in theme defines widget placement order on the panel. From top to bottom in theme means from left to right on the panel.

Desktop switcher

desktops.png

The desktop switcher is a widget that helps you to switch between desktops (aka workspaces).

desktop_switcher
        idle
                left_corner ds_left_corner_idle_img.png
                left ds_left_idle_img.png
                center tb_tile_idle_img.png
                right ds_right_idle_img.png
                right_corner ds_right_corner_idle_img.png
                font DejaVuSans 8
                        color 255 255 255
                        offset 0 1
                        #shadow_offset 0 1
                        #shadow_color 200 200 200

        pressed
                left_corner ds_left_corner_pressed_img.png
                left ds_left_pressed_img.png
                center tb_tile_pressed_img.png
                right ds_right_pressed_img.png
                right_corner ds_right_corner_pressed_img.png
                font DejaVuSans 8
                        color 255 255 255
                        offset 0 1
                        #shadow_offset 0 1
                        #shadow_color 200 200 200

        separator ds_separator_img.png

The idle, idle_highlight, pressed and pressed_highlight subsections are descriptions of how button states are drawn.

idle/left_corner

Defines an appearance of the left part of a button located in the left corner of the widget.

desktops_left_corner.png

idle/left

Defines an appearance of the left part of the button if it isn’t in the corner.

desktops_left.png

idle/center

Defines a background of the button.

desktops_center.png

idle/right

Defines an appearance of the right part of the button if it isn’t in the corner.

desktops_right.png

idle/right_corner

Defines an appearance of the right part of a button located in the right corner of the widget.

desktops_right_corner.png

idle/font

Defines a font of the text (button labels). This parameter is optional. If it’s not defined, then the center part of the background isn’t drawn and the desktop name isn’t drawn also. But due to unknown reasons (hacks) the center parameter should be set even if there is no font.

idle_hightlight/*

Idle_highlight state parameters are the same as idle.

pressed/*

Pressed state parameters are the same as idle.

pressed_highlight/*

Pressed_highlight state parameters are the same as idle.

separator

Defines a tiny image which is drawn between the desktop switcher buttons.

desktops_separator.png

Taskbar

taskbar.png

The taskbar is a widget that allows you to switch between tasks (windows) on a current workspace. And currently this widget defines a placement for other widgets, because it takes all free space in the panel. Taskbar presence is required in a theme.

taskbar
        idle
                left tb_left_idle_img.png
                center tb_tile_idle_img.png
                right tb_right_idle_img.png
                font DejaVuSans 8
                        color 0 0 0
                        align left
                        offset 5 1
                        shadow_offset 0 1
                        shadow_color 220 220 220
                icon_offset 0 0

        pressed
                left tb_left_pressed_img.png
                center tb_tile_pressed_img.png
                right tb_right_pressed_img.png
                font DejaVuSans 8
                        color 0 0 0
                        align left
                        offset 5 2
                        shadow_offset 0 1
                        shadow_color 200 200 200
                icon_offset 0 1

        default_icon default_icon.png
        task_max_width 230
        #separator separator_img.png

The idle, idle_highlight, pressed and pressed_highlight subsections are descriptions of how button states are drawn.

idle/stretched

If you want to have gradient-style taskbar buttons like on this image:

stretched_example.png

You’ll need to use this boolean value. If it presents, the idle/center image is being stretched while drawing a taskbar button instead of being repeated.

idle/stretched_overlap

This is also a boolean representing another drawing mode. It’s almost like the idle/stretched, except that it makes idle/center stretched under the corner (left and right) images. It is useful when you want to make some magic with partial transparency. For better explanation see table in idle/center_offsets.

idle/center_offsets

This is a pair of offsets represented by two integers. Actually by manipulating these values you can turn idle/stretched into idle/stretched_overlap. To do that you need this: 

        stretched
        center_offsets -[idle/left width] -[idle/right width]

OK, if you still doesn’t get it, let me show you few examples:

stretched_no_center_offsets.png

stretched, no center_offsets

stretched_overlap_no_center_offsets.png

stretched_overlap, no center_offsets
or
stretched, center_offsets -26 -26

stretched_center_offsets_5_5.png

stretched, center_offsets 5 5

stretched_center_offsets_m5_0.png

stretched, center_offsets -5 0

stretched_overlap_center_offsets_0_5.png

stretched_overlap, center_offsets 0 5

I hope you get it now. If not, let me know.

idle/left

Defines an appearance of the left part of a button on a taskbar.

taskbar_left.png

idle/center

Defines a background of the button.

taskbar_center.png

idle/right

Defines an appearance of the right part of a button on a taskbar.

taskbar_right.png

idle/font

Defines a font of the text (button labels).

idle/icon_offset

Defines an offset (in pixels) for an icon on a button. Only makes sense if the default_icon is defined. The value is presented as two numbers. An offset for X and Y axis respectively.

idle_hightlight/*

Idle_highlight state parameters are the same as idle.

pressed/*

Pressed state parameters are the same as idle.

pressed_highlight/*

Pressed_highlight state parameters are the same as idle.

separator

(Not implemented) It was in bmpanel 0.9.x, does anyone need this?

default_icon

Defines an icon to show for the task which has no icon. Also the size of this image implicitly defines a size of all icons. And its presence defines whether icons are drawn or not.

task_max_width

By default all tasks share all available taskbar space equally. This parameter may restrict task width to some value (in pixels).

Systray

systray.png

The system tray widget. Also known as notification area. Some applications can place tiny interactive icons to that area.

systray
        icon_size 24 24
        #icon_offset 0 -1
        #icon_spacing 5

        background
                left systray_left_img.png
                center systray_tile_img.png
                right systray_right_img.png
icon_size

Defines a size of an icon. Two numbers - width and height respectively (in pixels).

icon_offset

An offset for placing icons. Two numbers - horizontal and vertical offset in pixels. Usually only the vertical offset is useful.

icon_spacing

Space between icons in pixels. If you don’t like that the icons are too close to each other, you should increment this parameter definitely.

background/*

See clock widget below. The meaning is the same.

Clock

clock.png

Clock widget. Shows time.

clock
        background
                left clock_left_img.png
                center clock_tile_img.png
                right clock_right_img.png

        font DejaVuSans bold 14
                color 20 20 20
                offset 0 1
                align center
                shadow_offset 0 1
                shadow_color 220 220 220

        time_format %H:%M:%S
background/left

Defines an appearance of the left part of the clock background.

clock_left.png

background/center

Defines an appearance of the middle part of the clock background.

clock_center.png

background/right

Defines an appearance of the right part of the clock background.

clock_right.png

font

Defines a font of the text.

time_format

Defines a format of the time. The default is: %H:%M:%S. For format reference see man strftime. Or if you don’t have a man page for strftime, just google it (first google match for lazy bastards: http://www.manpagez.com/man/3/strftime).

Decor

Decor widget. Basicly it’s just an image.. aka decoration. No functionality.

decor sweet_image.png

Empty

Empty. Abyss of nothingness. If you need to skip some space between widgets, you should definitely use empty. Just don’t forget to specify the amount of pixels you need to skip.

empty 25

Launchbar

launchbar.png

Launch bar. This widget contains clickable icons with user defined programs to run. The actual content of this widget is defined in the bmpane2rc file (TODO: add link to the man page (which doesn’t exist yet)).

launchbar
        icon_size 16 16
icon_size

Defines a size of an icon. Two numbers - width and height respectively (in pixels).