2 \chapter{Graphical styles}
5 This chapter first gives in section \ref{sec:engines} a general outline
6 of how drawing engines are used, of style specifications and then
7 in section \ref{sec:defaultde} describes how to specify styles
8 for the default drawing engine.
10 \section{Drawing engines, style specifications and sub-styles}
12 \index{style}\index{drawing engine}
14 Ion's drawing routines are abstracted into so-called drawing engine
15 modules that can, again depending on the system, be dynamically
16 loaded as needed. The drawing engine modules provide ''brushes''
17 that objects can use to draw some high-level primitives such
18 as borders and text boxes (in addition to simple text and rectangle
19 drawing) on their windows and configure e.g. the shape and
20 background of the window. While the drawing engines therefore
21 do not directly implement looks for each possible object (that
22 would hardly be maintainable), different brush styles can be
23 used to give a distinctive look to different objects and engines
24 could interpret some styles as special cases. Style specifications
25 are strings of the form
28 element1-element2-...-elementn
31 An example of such a style specification is \code{tab-frame};
32 see the table in subsection \ref{sec:styles} for more styles.
34 When an object asks for a brush of certain style, the selected
35 drawing engine will attempt to find the closest match to this
36 specification. The styles/brushes defined by the drawing engines
37 may have asterisks (\verb!*!) as some of the elements indicating
38 a match to anything. Exact matches are preferred to asterisk
39 matches and longer matches to shorter. For example, let a brush
40 for style \code{foo-bar-baz} be queried, then the following
41 brushes are in order of preference:
48 foo-baz -- Doesn't match, not selected!
51 Some of the drawing primitives allow extra attributes to be
52 specified, also in the form
56 These extra attributes are called \emph{substyles}\index{substyle}
57 and allow, for example, the state of the object to be indicated
58 by different colour sets while keeping the interface at an
59 abstract level and the drawing engine completely ignorant
60 of the semantics -- only the writer of the drawing engine
61 configuration file has to know them. However the drawing
62 engine can again interpret known substyles as special cases
63 and the default engine indeed does so with frame tab
67 \subsection{Known styles and substyles}
70 \subsubsection{Frames}
72 \begin{tabularx}{\linewidth}{lX}
73 \tabhead{Style name & Description}
74 \code{frame} & Style for frames.
75 Substyles: \code{active}, \code{inactive}. \\
76 \code{frame-tiled} & A more specific style for tiled frames.
77 Substyles as for \code{frame}. \\
78 \code{frame-tiled-alt} & An alternative style for tiled frames.
79 Often used to disable the tab-bar. \\
80 \code{frame-floating} & A more specific style for floating
82 \code{frame-transient} & A more specific style for frames
83 containing transient windows. \\
86 \subsubsection{Tabs and menu entries}
88 \begin{tabularx}{\linewidth}{lX}
89 \tabhead{Style name & Description}
90 \code{tab} & Style for frames' tabs and menu entries.
91 Substyles: combinations of the form \code{a-s} where
92 \code{a} is one of \code{active}\nobreak/\code{inactive} and
93 \code{s} is one of \code{selected}\nobreak/\code{unselected} \\
94 \code{tab-frame} & A more specific style for frames' tabs.
95 Substyles: combinations of the form \code{a-s-t-d-u} where
96 \code{a} and \code{s} are as above and
97 \code{t} is one of \code{tagged}\nobreak/\code{not_tagged},
98 \code{d} is one of \code{dragged}\nobreak/\code{not_dragged} and
99 \code{u} is one of \code{activity}\nobreak/\code{no_activity}. \\
100 \code{tab-frame-tiled}, & \\
101 \code{tab-frame-tiled-alt}, & \\
102 \code{tab-frame-floating}, & \\
103 \code{tab-frame-transient} & More specific styles for frames in the
105 \code{tab-menuentry} & A more specific style for entries in \type{WMenu}s. \\
106 \code{tab-menuentry-bigmenu} & An alternate style for entries in \type{WMenu}s. \\
109 \subsubsection{The rest}
111 \begin{tabularx}{\linewidth}{lX}
112 \tabhead{Style name & Description}
113 \code{input} & A style for \type{WInput}s. \\
114 \code{input-edln} & A more specific style for \type{WEdln}s.
115 Substyles: \code{selection} for selected text and
116 \code{cursor} for the cursor indicating current editing point. \\
117 \code{input-message} & A more specific style for \type{WMessage}s. \\
118 \code{input-menu} & A more specific style for \type{WMenu}s. \\
119 \code{input-menu-bigmenu} & An alternate style for \type{WMenu}s. \\
120 \code{moveres_display} & The box displaying position/size when
121 moving or resizing frames. \\
122 \code{dock} & The dock. \\
126 \section{Defining styles for the default drawing engine}
127 \label{sec:defaultde}
129 Drawing engine style files are usually named
130 \file{look\_foo.lua} where \file{foo} is the name of the
131 style. The file that Ion loads on startup or when
132 \fnref{gr.read_config} is called, however, is \file{look.lua}
133 and should usually be symlinked to or a copy of of some
134 \file{look\_foo.lua}.
136 \subsection{The structure of the configuration files}
138 The first thing to do in a stylefile is to choose the drawing
139 engine, possibly loading the module as well. This is done
140 with the following chunk of code.
143 if not gr.select_engine("de") then
148 The \fnref{gr.select_engine} function sees if the engine
149 given as argument is registered (the default drawing engine is
150 simply called ''de''). If the engine could not be found, it
151 tries to load a module of the same name. If the engine still
152 is not registered, \fnref{gr.select_engine} returns \code{false}
153 and in this case we also exit the style setup script.
154 If the engine was found, \fnref{gr.select_engine} sees that
155 further requests for brushes are forwarded to that engine
156 and returns \code{true}.
158 Before defining new styles it may be a good idea to clear old
159 styles from memory so if the old configuration defines more
160 specific styles than the new, the old styles don't override
161 those specified by the new configuration. That can be done by
168 After this the new styles can be defined with \fnref{de.defstyle}
169 as explained in the next subsection. Finally, after the styles have
170 been defined we must ask objects on the screen to look up new brushes
171 to reflect the changes in configuration. This is done with
177 \subsection{Defining the styles}
179 Styles for the default drawing engine are defined with the
180 function \fnref{de.defstyle}. It has two arguments the first being
181 a style specification as explained in previous sections and the second
182 a table whose fields describe the style:
185 de.defstyle("some-style", {
191 The supported attributes are described in tables below. The different
192 border elements and styles referred to there are explained in Figure
197 \docode % Kludge to make latex2html interpret contents instead of
201 Elevated: Inlaid: Ridge: Groove:
202 hhhhhhhhhhhs ............ hhhhhhhhhhhs sssssssssssh
203 h..........s .sssssssssh. h..........s s..........h
204 h. .s .s h. h.sssssssh.s s.hhhhhhhs.h
205 h. .s .s h. h.s h.s s.h s.h
206 h. .s .s h. h.shhhhhhh.s s.hsssssss.h
207 h..........s .shhhhhhhhh. h..........s s..........h
208 hsssssssssss ............ hsssssssssss shhhhhhhhhhh
210 h = highlight, s = shadow, . = padding
212 \caption{Sketch of different border styles and elements}
216 \subsubsection{Colours}
218 Each of these fields a string of the form that can be
219 passed to \code{XAllocNamedColor}. Valid strings are e.g.
220 hexadecimal RGB specifications of the form
221 \code{#RRGGBB} and colour names as specified
222 in \file{/usr/X11R6/lib/X11/rgb.txt} (exact path varying).
224 \begin{tabularx}{\linewidth}{lX}
225 \tabhead{Field & Description}
226 \var{highlight_colour} &
227 Colour for the ''highlight'' part of a border. \\
228 \var{shadow_colour} &
229 Colour for the ''highlight'' part of a border. \\
230 \var{foreground_colour} &
231 Colour for the normal drawing operations, e.g. text. \\
232 \var{background_colour} &
233 Window background colour (unless transparency is enabled) and
234 background colour boxes. \\
235 \var{padding_colour} &
236 Colour for the ''padding'' part of a border border. Set to
237 \var{background_colour} if unset. \\
241 \subsubsection{Borders and widths}
243 All other fields below except \var{border_style} are non-negative integers
244 indicating a number of pixels.
246 \begin{tabularx}{\linewidth}{lX}
247 \tabhead{Field & Description}
248 \var{border_style} & A string indicating the style of border; one of
249 elevated/inlaid/ridge/groove as seen in the
251 \var{highlight_pixels} &
252 Width of the highlight part of the border in pixels. \\
253 \var{shadow_pixels} &
254 Width of the shadow part of the border in pixels. \\
255 \var{padding_pixels} &
256 Width of the padding part of the border in pixels. \\
258 Space to be left between all kinds of boxes. \\
264 \begin{tabularx}{\linewidth}{lX}
265 \tabhead{Field & Description}
266 \var{font} & Font to be used in text-drawing operations; standard X font
268 \var{text_align} & How text is to be aligned in text boxes/tabs; one of
269 the strings left\nobreak/right\nobreak/center. \\
273 \subsubsection{Miscellaneous}
276 \begin{tabularx}{\linewidth}{lX}
277 \tabhead{Field & Description}
278 \var{transparent_background} & Should windows' that use this style
279 background be transparent? true/false. \\
280 \var{based_on} & The name of a previously defined style that this
281 style should be based on. \\
285 \subsubsection{Substyles}
287 As discussed in previous sections, styles may have substyles to e.g.
288 indicate different states of the object being drawn. The ''de'' engine
289 limits what can be configured in substyles to the set of colours in the
290 first table above, but also specifically interprets for the main style
291 \code{tab-frame} the substyles \code{*-*-tagged} and \code{*-*-*-dragged}
292 by, respectively, drawing a right angle shape at the top right corner
293 of a tab and by shading the tab with a stipple pattern. Also for
294 menus the substyles \code{*-*-submenu} are handled as a special case.
296 Substyles are defined with the function \fnref{de.substyle} within the
297 table defining the main style. The parameters to this function are
298 similar to those of \fnref{de.defstyle}.
301 de.defstyle("some-style", {
303 de.substyle("some-substyle", {
311 \subsection{An example}
313 The following shortened segment from \file{look\_cleanviolet.lua}
314 should help to clarify the matters discussed in the previous
320 highlight_colour = "#eeeeee",
321 shadow_colour = "#eeeeee",
322 background_colour = "#aaaaaa",
323 foreground_colour = "#000000",
326 highlight_pixels = 1,
329 border_style = "elevated",
331 font = "-*-helvetica-medium-r-normal-*-12-*-*-*-*-*-*-*",
332 text_align = "center",
335 de.defstyle("tab-frame", {
338 de.substyle("active-selected", {
340 highlight_colour = "#aaaacc",
341 shadow_colour = "#aaaacc",
342 background_colour = "#666699",
343 foreground_colour = "#eeeeee",
346 -- More substyles would follow ...
351 \section{Miscellaneous settings}
353 The following style fields are independent of the drawing engine used,
354 but are related to objects' styles and therefore configured in the drawing
355 engine configuration file.
357 \subsection{Extra fields for style \code{frame}}
359 \begin{tabularx}{\linewidth}{lX}
360 \tabhead{Field & Description}
361 \code{bar} & Controls the style of the tab-bar. Possible values
362 are the strings \code{"none"}, \code{"inside"}, \code{"outside"}
363 and \code{"shaped"}, with the last providing the PWM-style
364 tab-bars for floating frames. \\
365 \code{floatframe_tab_min_w} & Minimum tab width in pixels for
366 the shaped style, given that this number times number of tabs
367 doesn't exceed frame width. \\
368 \code{floatframe_bar_max_w_q} & Maximum tab-bar width quotient of
369 frame width for the shaped styles. A number in the
373 \subsection{Extra fields for style \code{dock}}
375 \begin{tabularx}{\linewidth}{lX}
376 \tabhead{Field & Description}
377 \code{outline_style} & How borders are drawn:
378 \code{"none"} -- no border,
379 \code{"all"} -- border around whole dock,
380 \code{"each"} -- border around each dockapp. \\
381 \code{tile_size} & A table with entries \code{width} and \code{height},
382 indicating the width and height of tiles in pixels.
386 Hopefully that's enough to get you started in writing new style
387 configuration files for Ion. When in doubt, study the existing
388 style configuration files.