Bmpanel2 theme reference
========================

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 a filename and an optional rectangle. The
rectangle defines which part of the image should be rendered.

---------------------------------
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 a font name, its parameters and other
drawing parameters. The font itself is specified by a 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 a 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.
+
image:separator.png[]

background::
	Defines a background image of the panel.
+
image: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
	# paint_replace
	# ...
---------------------------------

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.
+
image:widget_separator.png[]

paint_replace::
	If the *paint_replace* parameters presents in a widget, the
	widget uses different drawing mode replacing background
	instead of trying to draw itself over it. Useful for
	transparent themes.

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
~~~~~~~~~~~~~~~~
image: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.
+
image:desktops_left_corner.png[]

idle/left::
	Defines an appearance of the left part of the button if it
	isn't in the corner.
+
image:desktops_left.png[]

idle/center::
	Defines a background of the button.
+
image:desktops_center.png[]

idle/right::
	Defines an appearance of the right part of the button if it
	isn't in the corner.
+
image:desktops_right.png[]

idle/right_corner::
	Defines an appearance of the right part of a button located in
	the right corner of the widget.
+
image: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.
+
image:desktops_separator.png[]

Taskbar
~~~~~~~
image: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:
+
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:
+
[valign="center",cols="1%,99%"]
|==========
| image:stretched_no_center_offsets.png[] | stretched, no
center_offsets
| image:stretched_overlap_no_center_offsets.png[] | stretched_overlap,
no center_offsets +
or +
stretched, center_offsets -26 -26
| image:stretched_center_offsets_5_5.png[] | stretched, center_offsets
5 5
| image:stretched_center_offsets_m5_0.png[] | stretched,
center_offsets -5 0
| image: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.
+
image:taskbar_left.png[]

idle/center::
	Defines a background of the button.
+
image:taskbar_center.png[]

idle/right::
	Defines an appearance of the right part of a button on a
	taskbar.
+
image: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::
	If specified this image is being drawn between tasks in the taskbar
	widget.
+
image:taskbar_separator.png[]

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
~~~~~~~
image: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
~~~~~
image: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.
+
image:clock_left.png[]
	
background/center::
	Defines an appearance of the middle part of the clock
	background.
+
image:clock_center.png[]
	
background/right::
	Defines an appearance of the right part of the clock
	background.
+
image: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: link: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
~~~~~~~~~
image: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
bmpanel2rc file (*TODO*: add link to the man page (which doesn't exist
yet)).

---------------------------------
launchbar
	icon_size 16 16
	#icon_offset 0 -1
	#icon_spacing 5

	background
		left launchbar_left_img.png
		center launchbar_tile_img.png
		right launchbar_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.

// vim: set syntax=asciidoc:

