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:
50 Some of the drawing primitives allow extra attributes to be
51 specified, also in the form
55 These extra attributes are called \emph{substyles}\index{substyle}
56 and allow, for example, the state of the object to be indicated
57 by different colour sets while keeping the interface at an
58 abstract level and the drawing engine completely ignorant
59 of the semantics -- only the writer of the drawing engine
60 configuration file has to know them. However the drawing
61 engine can again interpret known substyles as special cases
62 and the default engine indeed does so with frame tab
66 \subsection{Known styles and substyles}
69 \subsubsection{Frames}
71 \begin{tabularx}{\linewidth}{lX}
72 \tabhead{Style name & Description}
73 \code{frame} & Style for frames.
74 Substyle attributes: \code{active}/\code{inactive}
75 (mutually exclusive) and
76 \code{quasiactive}\nobreak/\code{not_quasiactive}.
77 A frame is ``quasiactive'' when an active region
78 has a backlink to it, such as a detached window. \\
79 \code{frame-tiled} & A more specific style for tiled frames.
80 Substyle attributes as for \code{frame}. \\
81 \code{frame-tiled-alt} & An alternative style for tiled frames.
82 Often used to disable the tab-bar. \\
83 \code{frame-floating} & A more specific style for floating
85 \code{frame-transient} & A more specific style for frames
86 containing transient windows. \\
89 \subsubsection{Tabs and menu entries}
91 \begin{tabularx}{\linewidth}{lX}
92 \tabhead{Style name & Description}
93 \code{tab} & Style for frames' tabs and menu entries.
95 \code{active}\nobreak/\code{inactive} and
96 \code{selected}\nobreak/\code{unselected} \\
97 \code{tab-frame} & A more specific style for frames' tabs.
98 Additional substyle attributes include:
99 \code{tagged}\nobreak/\code{not_tagged},
100 \code{dragged}\nobreak/\code{not_dragged},
101 \code{activity}\nobreak/\code{no_activity} and
102 \code{quasiactive}\nobreak/\code{not_quasiactive}. \\
103 \code{tab-frame-tiled}, & \\
104 \code{tab-frame-tiled-alt}, & \\
105 \code{tab-frame-floating}, & \\
106 \code{tab-frame-transient} & More specific styles for frames in the
108 \code{tab-menuentry} & A more specific style for entries in \type{WMenu}s.
109 Additional substyle attributes include \code{submenu} and
110 occasionally also \code{activity} is used.\\
111 \code{tab-menuentry-bigmenu} &
112 An alternate style for entries in \type{WMenu}s. \\
115 \subsubsection{The rest}
117 \begin{tabularx}{\linewidth}{lX}
118 \tabhead{Style name & Description}
119 \code{input} & A style for \type{WInput}s. \\
120 \code{input-edln} & A more specific style for \type{WEdln}s.
121 Substyle attributes: \code{selection} for selected text and
122 \code{cursor} for the cursor indicating current editing point. \\
123 \code{input-message} & A more specific style for \type{WMessage}s. \\
124 \code{input-menu} & A more specific style for \type{WMenu}s. \\
125 \code{input-menu-bigmenu} & An alternate style for \type{WMenu}s. \\
126 \code{moveres_display} & The box displaying position/size when
127 moving or resizing frames. \\
128 \code{dock} & The dock. \\
132 \section{Defining styles for the default drawing engine}
133 \label{sec:defaultde}
135 Drawing engine style files are usually named
136 \file{look\_foo.lua} where \file{foo} is the name of the
137 style. The file that Ion loads on startup or when
138 \fnref{gr.read_config} is called, however, is \file{look.lua}
139 and should usually be symlinked to or a copy of of some
140 \file{look\_foo.lua}.
142 \subsection{The structure of the configuration files}
144 The first thing to do in a style file is to choose the drawing
145 engine, possibly loading the module as well. This is done
146 with the following chunk of code.
149 if not gr.select_engine("de") then
154 The \fnref{gr.select_engine} function sees if the engine
155 given as argument is registered (the default drawing engine is
156 simply called ''de''). If the engine could not be found, it
157 tries to load a module of the same name. If the engine still
158 is not registered, \fnref{gr.select_engine} returns \code{false}
159 and in this case we also exit the style setup script.
160 If the engine was found, \fnref{gr.select_engine} sees that
161 further requests for brushes are forwarded to that engine
162 and returns \code{true}.
164 Before defining new styles it may be a good idea to clear old
165 styles from memory so if the old configuration defines more
166 specific styles than the new, the old styles don't override
167 those specified by the new configuration. That can be done by
174 After this the new styles can be defined with \fnref{de.defstyle}
175 as explained in the next subsection. Finally, after the styles have
176 been defined we must ask objects on the screen to look up new brushes
177 to reflect the changes in configuration. This is done with
183 \subsection{Defining the styles}
185 Styles for the default drawing engine are defined with the
186 function \fnref{de.defstyle}. It has two arguments the first being
187 a style specification as explained in previous sections and the second
188 a table whose fields describe the style:
191 de.defstyle("some-style", {
197 The supported attributes are described in tables below. The different
198 border elements and styles referred to there are explained in Figure
203 \docode % Kludge to make latex2html interpret contents instead of
207 Elevated: Inlaid: Ridge: Groove:
208 hhhhhhhhhhhs ............ hhhhhhhhhhhs sssssssssssh
209 h..........s .sssssssssh. h..........s s..........h
210 h. .s .s h. h.sssssssh.s s.hhhhhhhs.h
211 h. .s .s h. h.s h.s s.h s.h
212 h. .s .s h. h.shhhhhhh.s s.hsssssss.h
213 h..........s .shhhhhhhhh. h..........s s..........h
214 hsssssssssss ............ hsssssssssss shhhhhhhhhhh
216 h = highlight, s = shadow, . = padding
218 \caption{Sketch of different border styles and elements}
222 \subsubsection{Colours}
224 Each of these fields a string of the form that can be
225 passed to \code{XAllocNamedColor}. Valid strings are e.g.
226 hexadecimal RGB specifications of the form
227 \code{#RRGGBB} and colour names as specified
228 in \file{/usr/X11R6/lib/X11/rgb.txt} (exact path varying).
230 \begin{tabularx}{\linewidth}{lX}
231 \tabhead{Field & Description}
232 \var{highlight_colour} &
233 Colour for the ''highlight'' part of a border. \\
234 \var{shadow_colour} &
235 Colour for the ''highlight'' part of a border. \\
236 \var{foreground_colour} &
237 Colour for the normal drawing operations, e.g. text. \\
238 \var{background_colour} &
239 Window background colour (unless transparency is enabled) and
240 background colour boxes. \\
241 \var{padding_colour} &
242 Colour for the ''padding'' part of a border border. Set to
243 \var{background_colour} if unset. \\
247 \subsubsection{Borders and widths}
249 All other fields below except \var{border_style} are non-negative integers
250 indicating a number of pixels.
252 \begin{tabularx}{\linewidth}{lX}
253 \tabhead{Field & Description}
254 \var{border_style} & A string indicating the style of border; one of
255 elevated/inlaid/ridge/groove as seen in the
257 \var{highlight_pixels} &
258 Width of the highlight part of the border in pixels. \\
259 \var{shadow_pixels} &
260 Width of the shadow part of the border in pixels. \\
261 \var{padding_pixels} &
262 Width of the padding part of the border in pixels. \\
264 Space to be left between all kinds of boxes. \\
270 \begin{tabularx}{\linewidth}{lX}
271 \tabhead{Field & Description}
272 \var{font} & Font to be used in text-drawing operations; standard X font
274 \var{text_align} & How text is to be aligned in text boxes/tabs; one of
275 the strings left\nobreak/right\nobreak/center. \\
279 \subsubsection{Miscellaneous}
282 \begin{tabularx}{\linewidth}{lX}
283 \tabhead{Field & Description}
284 \var{transparent_background} & Should windows' that use this style
285 background be transparent? true/false. \\
286 \var{based_on} & The name of a previously defined style that this
287 style should be based on. \\
291 \subsubsection{Substyles}
293 As discussed in previous sections, styles may have substyles to e.g.
294 indicate different states of the object being drawn. The ''de'' engine
295 limits what can be configured in substyles to the set of colours in the
296 first table above, but also specifically interprets for the main style
297 \code{tab-frame} the substyles \code{*-*-tagged} and \code{*-*-*-dragged}
298 by, respectively, drawing a right angle shape at the top right corner
299 of a tab and by shading the tab with a stipple pattern. Also for
300 menus the substyles \code{*-*-submenu} are handled as a special case.
302 Substyles are defined with the function \fnref{de.substyle} within the
303 table defining the main style. The parameters to this function are
304 similar to those of \fnref{de.defstyle}.
307 de.defstyle("some-style", {
309 de.substyle("some-substyle", {
317 \subsection{An example}
319 The following shortened segment from \file{look\_cleanviolet.lua}
320 should help to clarify the matters discussed in the previous
326 highlight_colour = "#eeeeee",
327 shadow_colour = "#eeeeee",
328 background_colour = "#aaaaaa",
329 foreground_colour = "#000000",
332 highlight_pixels = 1,
335 border_style = "elevated",
337 font = "-*-helvetica-medium-r-normal-*-12-*-*-*-*-*-*-*",
338 text_align = "center",
341 de.defstyle("tab-frame", {
344 de.substyle("active-selected", {
346 highlight_colour = "#aaaacc",
347 shadow_colour = "#aaaacc",
348 background_colour = "#666699",
349 foreground_colour = "#eeeeee",
352 -- More substyles would follow ...
357 \section{Miscellaneous settings}
359 The following style fields are independent of the drawing engine used,
360 but are related to objects' styles and therefore configured in the drawing
361 engine configuration file.
363 \subsection{Extra fields for style \code{frame}}
365 \begin{tabularx}{\linewidth}{lX}
366 \tabhead{Field & Description}
367 \code{bar} & Controls the style of the tab-bar. Possible values
368 are the strings \code{"none"}, \code{"inside"}, \code{"outside"}
369 and \code{"shaped"}, with the last providing the PWM-style
370 tab-bars for floating frames. \\
371 \code{floatframe_tab_min_w} & Minimum tab width in pixels for
372 the shaped style, given that this number times number of tabs
373 doesn't exceed frame width. \\
374 \code{floatframe_bar_max_w_q} & Maximum tab-bar width quotient of
375 frame width for the shaped styles. A number in the
379 \subsection{Extra fields for style \code{dock}}
381 \begin{tabularx}{\linewidth}{lX}
382 \tabhead{Field & Description}
383 \code{outline_style} & How borders are drawn:
384 \code{"none"} -- no border,
385 \code{"all"} -- border around whole dock,
386 \code{"each"} -- border around each dockapp. \\
387 \code{tile_size} & A table with entries \code{width} and \code{height},
388 indicating the width and height of tiles in pixels.
392 Hopefully that's enough to get you started in writing new style
393 configuration files for Ion. When in doubt, study the existing
394 style configuration files.