Next: 5. Scripting Up: Configuring and extending Ion3 Previous: 3. Basic configuration Contents Index
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.
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-...-attrnThese 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.)
| Style name | Description |
| frame | Style for frames. Substyles: active, inactive. |
| frame-tiled | A more specific style for tiled frames. Substyles as for frame. |
| frame-tiled-alt | An alternative style for tiled frames. Often used to disable the tab-bar. |
| frame-floating | A more specific style for floating frames. |
| frame-transient | A more specific style for frames containing transient windows. |
| 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, | |
| tab-frame-tiled-alt, | |
| tab-frame-floating, | |
| tab-frame-transient | More specific styles for frames in the different modes. |
| tab-menuentry | A more specific style for entries in WMenus. |
| tab-menuentry-bigmenu | An alternate style for entries in WMenus. |
| 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. |
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.
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()
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 |
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. |
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. |
| 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. |
| 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. |
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", {
...
}),
...
})
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 ...
})
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.
| Field | Description |
| bar | Controls the style of the tab-bar. Possible values are the strings "none", "inside", "outside" and "shaped", with the last providing the PWM-style tab-bars for floating frames. |
| floatframe_tab_min_w | Minimum tab width in pixels for the shaped style, 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 for the shaped styles. A number in the interval . |
| 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.