THEMES
In golem, a 'theme' is simply a portion of the golemrc file that is included by the main rcfile in ~/.golem/golemrc. The basis of the theme's rc file is the golemrc style block, which contains pixmap declarations and declarations of decoration units, and finally (and most importantly) the grouping of those decoration units.
theme rc files are included in user's golemrc file (preferably at the top) with a line like
.include "path/to/theme/rc"
generally the user's rcfile will include the prepacked distribution themes from
.include "themes/ThemeName/rc"
and the ones that they have made or downloaded themselves from
.include "mythemes/ThemeName/rc"
but it's not enforced: a theme may be included from anywhere you want to put it, just specify the path with the .include directive
A good way to get familiar with writing a golem theme is to look at the distributed themes and learn how they work. If you understand BNF and/or have written yacc grammers you can look at the file rcfile.y that is part of the source distribution. Either way, you should read the following.
A typical golem theme rc file has the following structure:
#
# forplug includes. these are used to specify an rcfile that should be parsed when
# a plugin named "pluginname" is loaded. The rcfile can contain anything a normal
# golemrc can contain except loads of other plugins. There is one special block that
# may only appear in a forplug file, called 'plugdata'. This block works just like
# the inside of a load block (see the file PLUGINS included with this distribution)
# and all the parameters made there are merged with the ones defined where the plugin
# is loaded. A look at the example themes should clarify this.
#
forplug "pluginname" "rcfile";
# comment
style {
#
# as a hack, in the current implementation, the font/color for title text is
# the same across all dgroups (see below), and is defined here. This
# will change in the future.
#
title_font "-*-courier-*-*-*-*-*-*-*-*-*-*-*-*";
title_color "red";
#
# pixmap declations
#
# IDENTIFIER filename
#
pixmaps {
SOMEPMAP "file.xpm";
FSOMEPMAP "file_foc.xpm";
# the identifier (on the left) must be uppercase and unique
PIXMAP2 "pixmap2.xpm";
FPIXMAP2 "pixmap2_foc.xpm";
BUTTON "button.xpm";
FBUTTON "button_foc.xpm";
BPRESSED "pressed.xpm";
# usually a lot more pixmaps are declared than this, of course
}
#
# syntax for declaration of a decoration unit is as such
# (as with all of the golemrc stuff, whitespace is nonimportant)
#
# IDENTIFIER type edge offset lenmod soffset offsetmult lenmult
# isshaped isbutton
# lclick_action rclick_action
# pixmap focusedpixmap [pressedpixmap];
#
# type
# dec_full the decor unit streches the entire length
# of it's edge
# dec_near the decor unit is aligned to the lower
# numbers of the edge (further up or further
# left)
# dec_far the decor unit is aligned to the higher
# numbers of the edge (further down or to
# the right)
#
# edge dec_top, dec_right, dec_left or dec_bottom
# +----------------------------------+
# | top | Note that the top
# +---+--------------------------+---+ and bottom edges go over the
# | l | | r | corner areas, not the left
# | e | | i | and right edges.
# | f | | g |
# | t | | h |
# | | | t |
# +---+--------------------------+---+
# | bottom |
# +----------------------------------+
#
#
# offset an integer value that modifies the position
# of the unit along it's edge; for instance,
# a unit of type dec_near edge dec_top with
# offset of 10 will be placed 10 pixels from the
# left of the top edge.
#
# lenmod an integer modifier on the length of the decoration
# unit: the base size is the length (width/height depending
# on which edge) of the pixmap. Currently the only way
# the pixmap is used is by tiling it.
#
# soffset integer value offset in the secondary direction for the
# decoration unit: this allows moving decor units partially
# over the client window.
#
# offsetmult a decimal multiplier on the total length of the
# edge that the unit is on, and then added to the
# offset of the unit. This allows you to offset a
# a unit a distance relative to the size of the edge:
# for instance, make it halfway in, or a third in, etc.
#
# lenmult a decimal multiplier on the total length of the
# edge that the unit is on, and then added to the
# length of the unit. So you can make a unit that
# is half as long as the edge, or so forth.
#
# isshaped should this window be shaped: for optimization you set
# this to false if the pixmap you are using for this window
# has no transparency
#
# isbutton does this behave as a button? i.e., does it perform it's
# click actions when the button is released instead of when
# it is pressed, and does it use a pressedpixmap.
#
# lclick_action,
# mclick_action,
# rclick_action
# act_none nothing happens
# act_move interactively move the window when clicked
# act_resize interactively resize the window when clicked
# act_delete send the client WM_DELETE_WINDOW
# act_iconify iconify the window
# act_zoom zoom the window (maximize)
#
# pixmap the identifier of a pixmap defined in the pixmaps section
# to use for the decoration unit (tiled), when the client it's
# on is not focused
#
# focusedpixmap same as above, but for when the window is focused
#
# pressedpixmap if isbutton this should be set to the pixmap to use for
# when the button is pressed.
#
# for example, to make something half as long as the edge, but indented by 1/8 of the size
# of the edge plus 10 pixels, you would set lenmult to .5, offsetmult to .125, offset to 10
# and lenmod to 0. (you'd use dec_near for type in this case)
#
# it should be noted that it is sometimes a good idea to overlap adjacent units that use the
# multipliers at any value other than 0 by 1 pixel: this will prevent small gaps inbetween
# units (1-pixel gaps) when a result from a multiplication is rounded down, etc.
#
decoration {
#
# some normal decor units
#
D1 dec_full dec_top 0 0 0 0
false false
act_move act_resize
SOMEPMAP FSOMEPMAP;
D2 dec_near dec_left 0 0 0 0
true false
act_resize act_resize
PIXMAP2 FPIXMAP2;
#
# an example button unit
#
BUT1 dec_near dec_top 10 0 0 0
true true
act_delete act_delete
BUTTON FBUTTON PRESSED;
#
# this is where everything gets tied together. you define a set of
# decoration groups (dgroups), and then specify the default dgroup to
# use for a few common things, such as for normal windows, and for
# transient windows.
#
# syntax to define a group is:
#
# DGROUPIDENTIFIER <list of decoration units, seperated by whitespace>
#
# the only other thing is a unit may be specified as containing the
# window's store_name (title) by putting :title:x:y after it's ident,
# where x and y are the offset of the upper left corner for the title
# text. the font for the text, and it's color are currently hackishly
# global across all dgroups, and is defined in the root of the style
# block (above)
#
groups {
DEFAULT
D1:title:5:5 D2 BUT1;
#
# we leave buttons and title off of transients as
# an example
#
TRANSIENTS
D1 D2;
#
# declare default usages of these groups, groups without
# default usage definitions here can still be used through
# the key_dgroup_switch keybind, or with certain plugins,
# such as wmclass_defs.
#
default DEFAULT;
transient TRANSIENTS;
internal TRANSIENTS;
}
}
}