4 Graphical styles
This chapter first gives in section 4.1 a general outline
of how drawing engines are used, of style specifications and then
in section 4.2 describes how to specify styles
for the default drawing engine.
4.1 Drawing engines, style specifications and sub-styles
Ion's drawing routines are abstracted into so-called drawing engine
modules that can, again depending on the system, be dynamically
loaded as needed. The drawing engine modules provide ”brushes”
that objects can use to draw some high-level primitives such
as borders and text boxes (in addition to simple text and rectangle
drawing) on their windows and configure e.g. the shape and
background of the window. While the drawing engines therefore
do not directly implement looks for each possible object (that
would hardly be maintainable), different brush styles can be
used to give a distinctive look to different objects and engines
could interpret some styles as special cases. Style specifications
are strings of the form
element1-element2-...-elementn
An example of such a style specification is tab-frame;
see the table in subsection 4.1.1 for more styles.
When an object asks for a brush of certain style, the selected
drawing engine will attempt to find the closest match to this
specification. The styles/brushes defined by the drawing engines
may have asterisks (*
) as some of the elements indicating
a match to anything. Exact matches are preferred to asterisk
matches and longer matches to shorter. For example, let a brush
for style foo-bar-baz be queried, then the following
brushes are in order of preference:
foo-bar-baz
foo-*-baz
foo-bar
*
foo-baz -- Doesn't match, not selected!
Some of the drawing primitives allow extra attributes to be
specified, also in the form
attr1-attr2-...-attrn
These extra attributes are called substyles
and allow, for example, the state of the object to be indicated
by different colour sets while keeping the interface at an
abstract level and the drawing engine completely ignorant
of the semantics – only the writer of the drawing engine
configuration file has to know them. However the drawing
engine can again interpret known substyles as special cases
and the default engine indeed does so with frame tab
tag and drag states.)
4.1.1 Known styles and substyles
Frames
|
Style name |
Description |
|
frame |
Style for frames.
Substyles: active, inactive. |
frame-tiled-ionws |
A more specific style for frames on tiled
workspaces. Substyles as for frame. |
frame-floating-floatws |
A more specific style for frames on
floating workspaces. Substyles as for frame. |
Tabs and menu entries
|
Style name |
Description |
|
tab |
Style for frames' tabs and menu entries.
Substyles: combinations of the form a-s where
a is one of active/inactive and
s is one of selected/unselected |
tab-frame |
A more specific style for frames' tabs.
Substyles: combinations of the form a-s-t-d-u where
a and s are as above and
t is one of tagged/not_tagged,
d is one of dragged/not_dragged and
u is one of activity/no_activity. |
tab-frame-tiled-ionws |
A more specific tab style for
frame-tiled-ionws frames. |
tab-frame-floating-floatws |
A more specific style for
frame-floating-floatws frames. |
tab-menuentry |
A more specific style for entries in WMenus. |
tab-menuentry-bigmenu |
An alternate style for entries in WMenus. |
The rest
|
Style name |
Description |
|
input |
A style for WInputs. |
input-edln |
A more specific style for WEdlns.
Substyles: selection for selected text and
cursor for the cursor indicating current editing point. |
input-message |
A more specific style for WMessages. |
input-menu |
A more specific style for WMenus. |
input-menu-bigmenu |
An alternate style for WMenus. |
moveres_display |
The box displaying position/size when
moving or resizing frames. |
dock |
The dock. |
|
4.2 Defining styles for the default drawing engine
Drawing engine style files are usually named
look_foo.lua where foo is the name of the
style. The file that Ion loads on startup or when
gr.read_config is called, however, is look.lua
and should usually be symlinked to or a copy of of some
look_foo.lua.
4.2.1 The structure of the configuration files
The first thing to do in a stylefile is to choose the drawing
engine, possibly loading the module as well. This is done
with the following chunk of code.
if not gr.select_engine("de") then
return
end
The gr.select_engine function sees if the engine
given as argument is registered (the default drawing engine is
simply called ”de”). If the engine could not be found, it
tries to load a module of the same name. If the engine still
is not registered, gr.select_engine returns false
and in this case we also exit the style setup script.
If the engine was found, gr.select_engine sees that
further requests for brushes are forwarded to that engine
and returns true.
Before defining new styles it may be a good idea to clear old
styles from memory so if the old configuration defines more
specific styles than the new, the old styles don't override
those specified by the new configuration. That can be done by
calling
de.reset()
After this the new styles can be defined with de.defstyle
as explained in the next subsection. Finally, after the styles have
been defined we must ask objects on the screen to look up new brushes
to reflect the changes in configuration. This is done with
gr.refresh()
4.2.2 Defining the styles
Styles for the default drawing engine are defined with the
function de.defstyle. It has two arguments the first being
a style specification as explained in previous sections and the second
a table whose fields describe the style:
de.defstyle("some-style", {
attribute = value,
...
})
The supported attributes are described in tables below. The different
border elements and styles referred to there are explained in Figure
4.1.
Elevated: Inlaid: Ridge: Groove:
hhhhhhhhhhhs ............ hhhhhhhhhhhs sssssssssssh
h..........s .sssssssssh. h..........s s..........h
h. .s .s h. h.sssssssh.s s.hhhhhhhs.h
h. .s .s h. h.s h.s s.h s.h
h. .s .s h. h.shhhhhhh.s s.hsssssss.h
h..........s .shhhhhhhhh. h..........s s..........h
hsssssssssss ............ hsssssssssss shhhhhhhhhhh
h = highlight, s = shadow, . = padding
Figure 4.1: Sketch of different border styles and elements
Colours
Each of these fields a string of the form that can be
passed to XAllocNamedColor. Valid strings are e.g.
hexadecimal RGB specifications of the form
#RRGGBB and colour names as specified
in /usr/X11R6/lib/X11/rgb.txt (exact path varying).
|
Field |
Description |
|
highlight_colour |
Colour for the ”highlight” part of a border. |
shadow_colour |
Colour for the ”highlight” part of a border. |
foreground_colour |
Colour for the normal drawing operations, e.g. text. |
background_colour |
Window background colour (unless transparency is enabled) and
background colour boxes. |
padding_colour |
Colour for the ”padding” part of a border border. Set to
background_colour if unset. |
Borders and widths
All other fields below except border_style are non-negative integers
indicating a number of pixels.
|
Field |
Description |
|
border_style |
A string indicating the style of border; one of
elevated/inlaid/ridge/groove as seen in the
above sketch. |
highlight_pixels |
Width of the highlight part of the border in pixels. |
shadow_pixels |
Width of the shadow part of the border in pixels. |
padding_pixels |
Width of the padding part of the border in pixels. |
spacing |
Space to be left between all kinds of boxes. |
Text
|
Field |
Description |
|
font |
Font to be used in text-drawing operations; standard X font
name. |
text_align |
How text is to be aligned in text boxes/tabs; one of
the strings left/right/center. |
Miscellaneous
|
Field |
Description |
|
transparent_background |
Should windows' that use this style
background be transparent? true/false. |
based_on |
The name of a previously defined style that this
style should be based on. |
Substyles
As discussed in previous sections, styles may have substyles to e.g.
indicate different states of the object being drawn. The ”de” engine
limits what can be configured in substyles to the set of colours in the
first table above, but also specifically interprets for the main style
tab-frame the substyles *-*-tagged and *-*-*-dragged
by, respectively, drawing a right angle shape at the top right corner
of a tab and by shading the tab with a stipple pattern. Also for
menus the substyles *-*-submenu are handled as a special case.
Substyles are defined with the function de.substyle within the
table defining the main style. The parameters to this function are
similar to those of de.defstyle.
de.defstyle("some-style", {
...
de.substyle("some-substyle", {
...
}),
...
})
4.2.3 An example
The following shortened segment from look_cleanviolet.lua
should help to clarify the matters discussed in the previous
subsection.
de.defstyle("*", {
-- Gray background
highlight_colour = "#eeeeee",
shadow_colour = "#eeeeee",
background_colour = "#aaaaaa",
foreground_colour = "#000000",
shadow_pixels = 1,
highlight_pixels = 1,
padding_pixels = 1,
spacing = 0,
border_style = "elevated",
font = "-*-helvetica-medium-r-normal-*-12-*-*-*-*-*-*-*",
text_align = "center",
})
de.defstyle("tab-frame", {
based_on = "*",
de.substyle("active-selected", {
-- Violet tab
highlight_colour = "#aaaacc",
shadow_colour = "#aaaacc",
background_colour = "#666699",
foreground_colour = "#eeeeee",
}),
-- More substyles would follow ...
})
4.3 Miscellaneous settings
The following style fields are independent of the drawing engine used,
but are related to objects' styles and therefore configured in the drawing
engine configuration file.
4.3.1 Extra fields for style frame-tiled-ionws
|
Field |
Description |
|
ionframe_bar_inside_border |
Controls whether the tab-bar
appears inside or outside of the frame's borders. true/false. |
4.3.2 Extra fields for style frame-floating-floatws
|
Field |
Description |
|
floatframe_tab_min_w |
Minimum tab width in pixels, given
that this number times number of tabs doesn't exceed frame width. |
floatframe_bar_max_w_q |
Maximum tab-bar width quotient of
frame width. A number in the interval (0, 1]. |
4.3.3 Extra fields for style dock
|
Field |
Description |
|
outline_style |
How borders are drawn:
"none" – no border,
"all" – border around whole dock,
"each" – border around each dockapp. |
tile_size |
A table with entries width and height,
indicating the width and height of tiles in pixels. |
Hopefully that's enough to get you started in writing new style
configuration files for Ion. When in doubt, study the existing
style configuration files.