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. Some additional settings and
9 user attributes are explained in Sections \ref{sec:grmisc}.
12 \section{Drawing engines, style specifications and sub-styles}
14 \index{style}\index{drawing engine}
16 Ion's drawing routines are abstracted into so-called drawing engine
17 modules that can, again depending on the system, be dynamically
18 loaded as needed. The drawing engine modules provide ``brushes''
19 that objects can use to draw some high-level primitives such
20 as borders and text boxes (in addition to simple text and rectangle
21 drawing) on their windows and configure e.g. the shape and
22 background of the window. While the drawing engines therefore
23 do not directly implement looks for each possible object (that
24 would hardly be maintainable), different brush styles can be
25 used to give a distinctive look to different objects and engines
26 could interpret some styles as special cases. Style specifications
27 are strings of the form
30 element1-element2-...-elementn
33 An example of such a style specification is \codestr{tab-frame};
34 see the table in subsection \ref{sec:styles} for more styles.
36 When an object asks for a brush of certain style, the selected
37 drawing engine will attempt to find the closest match to this
38 specification. The styles/brushes defined by the drawing engines
39 may have asterisks (\codestr{*}) as some of the elements indicating
40 a match to anything. Exact matches are preferred to asterisk
41 matches and longer matches to shorter. For example, let a brush
42 for style \codestr{foo-bar-baz} be queried, then the following
43 brushes are in order of preference:
52 Some of the drawing primitives allow extra attributes to be
53 specified, also in the form
57 These extra attributes are called \emph{substyles}\index{substyle}
58 and allow, for example, the state of the object to be indicated
59 by different colour sets while keeping the interface at an
60 abstract level and the drawing engine completely ignorant
61 of the semantics -- only the writer of the drawing engine
62 configuration file has to know them. However the drawing
63 engine can again interpret known substyles as special cases
64 and the default engine indeed does so with frame tab
68 \subsection{Known styles and substyles}
71 \subsubsection{Frames}
73 \begin{tabularx}{\linewidth}{lX}
74 \tabhead{Style name & Description}
75 \codestr{frame} & Style for frames.
76 Substyle attributes: \codestr{active}/\codestr{inactive}
77 (mutually exclusive) and
78 \codestr{quasiactive}/\codestr{not\_quasiactive}.
79 A frame is ``quasiactive'' when an active region
80 has a back-link to it, such as a detached window. \\
81 \codestr{frame-tiled} & A more specific style for tiled frames.
82 Substyle attributes as for \codestr{frame}. \\
83 \codestr{frame-tiled-alt} & An alternative style for tiled frames.
84 Often used to disable the tab-bar. \\
85 \codestr{frame-floating} & A more specific style for floating
87 \codestr{frame-transient} & A more specific style for frames
88 containing transient windows. \\
91 \subsubsection{Tabs and menu entries}
93 \begin{tabularx}{\linewidth}{lX}
94 \tabhead{Style name & Description}
95 \codestr{tab} & Style for frames' tabs and menu entries.
97 \codestr{active}/\codestr{inactive} and
98 \codestr{selected}/\codestr{unselected} \\
99 \codestr{tab-frame} & A more specific style for frames' tabs.
100 Additional substyle attributes include:
101 \codestr{tagged}/\codestr{not\_tagged},
102 \codestr{dragged}/\codestr{not\_dragged},
103 \codestr{activity}/\codestr{no\_activity},
104 \codestr{quasiactive}/\codestr{not\_quasiactive}. \\
105 \codestr{tab-frame-tiled}, & \\
106 \codestr{tab-frame-tiled-alt}, & \\
107 \codestr{tab-frame-floating}, & \\
108 \codestr{tab-frame-transient} & More specific styles for frames in the
110 \codestr{tab-menuentry} & A more specific style for entries in \type{WMenu}s.
111 Additional substyle attributes include \codestr{submenu} and
112 occasionally also \codestr{activity} is used.\\
113 \codestr{tab-menuentry-bigmenu} &
114 An alternate style for entries in \type{WMenu}s. \\
117 \subsubsection{The rest}
119 \begin{tabularx}{\linewidth}{lX}
120 \tabhead{Style name & Description}
121 \codestr{input} & A style for \type{WInput}s. \\
122 \codestr{input-edln} & A more specific style for \type{WEdln}s.
123 Substyle attributes: \codestr{selection} for selected text and
124 \codestr{cursor} for the cursor indicating current editing point. \\
125 \codestr{input-message} & A more specific style for \type{WMessage}s. \\
126 \codestr{input-menu} & A more specific style for \type{WMenu}s. \\
127 \codestr{input-menu-bigmenu} & An alternate style for \type{WMenu}s. \\
128 \codestr{moveres\_display} & The box displaying position/size when
129 moving or resizing frames. \\
130 \codestr{stdisp} & Any status display. \\
131 \codestr{stdisp-dock} & The dock. \\
132 \codestr{stdisp-statusbar} & The statusbar. Substyles include:
133 the name of any monitor/meter (such as \codestr{date}), and
134 the supplied hint. Typical hints are: \codestr{normal},
135 \codestr{important}, and \codestr{critical}. \\
139 \section{Defining styles for the default drawing engine}
140 \label{sec:defaultde}
142 Drawing engine style files are usually named
143 \file{look\_foo.lua} where \file{foo} is the name of the
144 style. The file that Ion loads on startup or when
145 \fnref{gr.read_config} is called, however, is \file{look.lua}
146 and should usually be symlinked to or a copy of of some
147 \file{look\_foo.lua}.
149 \subsection{The structure of the configuration files}
151 The first thing to do in a style file is to choose the drawing
152 engine, possibly loading the module as well. This is done
153 with the following chunk of code.
156 if not gr.select_engine("de") then
161 The \fnref{gr.select_engine} function sees if the engine
162 given as argument is registered (the default drawing engine is
163 simply called ``de''). If the engine could not be found, it
164 tries to load a module of the same name. If the engine still
165 is not registered, \fnref{gr.select_engine} returns \codestr{false}
166 and in this case we also exit the style setup script.
167 If the engine was found, \fnref{gr.select_engine} sees that
168 further requests for brushes are forwarded to that engine
169 and returns \codestr{true}.
171 Before defining new styles it may be a good idea to clear old
172 styles from memory so if the old configuration defines more
173 specific styles than the new, the old styles don't override
174 those specified by the new configuration. That can be done by
181 After this the new styles can be defined with \fnref{de.defstyle}
182 as explained in the next subsection. Finally, after the styles have
183 been defined we must ask objects on the screen to look up new brushes
184 to reflect the changes in configuration. This is done with
190 \subsection{Defining the styles}
192 Styles for the default drawing engine are defined with the
193 function \fnref{de.defstyle}. It has two arguments the first being
194 a style specification as explained in previous sections and the second
195 a table whose fields describe the style:
198 de.defstyle("some-style", {
204 The supported attributes are described in tables below. The different
205 border elements and styles referred to there are explained in Figure
210 \docode % Kludge to make latex2html interpret contents instead of
214 Elevated: Inlaid: Ridge: Groove:
215 hhhhhhhhhhhs ............ hhhhhhhhhhhs sssssssssssh
216 h..........s .sssssssssh. h..........s s..........h
217 h. .s .s h. h.sssssssh.s s.hhhhhhhs.h
218 h. .s .s h. h.s h.s s.h s.h
219 h. .s .s h. h.shhhhhhh.s s.hsssssss.h
220 h..........s .shhhhhhhhh. h..........s s..........h
221 hsssssssssss ............ hsssssssssss shhhhhhhhhhh
223 h = highlight, s = shadow, . = padding
225 \caption{Sketch of different border styles and elements}
229 \subsubsection{Colours}
231 Each of these fields a string of the form that can be
232 passed to \code{XAllocNamedColor}. Valid strings are e.g.
233 hexadecimal RGB specifications of the form
234 \code{#RRGGBB} and colour names as specified
235 in \file{/usr/X11R6/lib/X11/rgb.txt} (exact path varying).
237 \begin{tabularx}{\linewidth}{lX}
238 \tabhead{Field & Description}
239 \var{highlight_colour} &
240 Colour for the ``highlight'' part of a border. \\
241 \var{shadow_colour} &
242 Colour for the ``shadow'' part of a border. \\
243 \var{foreground_colour} &
244 Colour for the normal drawing operations, e.g. text. \\
245 \var{background_colour} &
246 Window background colour (unless transparency is enabled) and
247 background colour boxes. \\
248 \var{padding_colour} &
249 Colour for the ``padding'' part of a border border. Set to
250 \var{background_colour} if unset. \\
254 \subsubsection{Borders and widths}
256 All other fields below except \var{border_style} are non-negative integers
257 indicating a number of pixels.
259 \begin{tabularx}{\linewidth}{lX}
260 \tabhead{Field & Description}
261 \var{border_style} & A string indicating the style of border; one of
262 \codestr{elevated}/\codestr{inlaid}/\codestr{ridge}/\codestr{groove}
263 as seen in the above sketch. \\
264 \var{border_sides} & A string indicating which sides of the border
265 to draw: \codestr{all}/\codestr{tb}/\codestr{lr} for all,
266 top and bottom, and left and right. To control between
267 left/right and top/bottom, use the pixel options below. \\
268 \var{highlight_pixels} &
269 Width of the highlight part of the border in pixels. \\
270 \var{shadow_pixels} &
271 Width of the shadow part of the border in pixels. \\
272 \var{padding_pixels} &
273 Width of the padding part of the border in pixels. \\
275 Space to be left between all kinds of boxes. \\
281 \begin{tabularx}{\linewidth}{lX}
282 \tabhead{Field & Description}
283 \var{font} & Font to be used in text-drawing operations; standard X font
285 \var{text_align} & How text is to be aligned in text boxes/tabs; one of
286 the strings \codestr{left}/\codestr{right}/\codestr{center}. \\
290 \subsubsection{Miscellaneous}
293 \begin{tabularx}{\linewidth}{lX}
294 \tabhead{Field & Description}
295 \var{transparent_background} & Should windows' that use this style
296 background be transparent? true/false. \\
297 \var{based_on} & The name of a previously defined style that this
298 style should be based on. \\
302 \subsubsection{Substyles}
304 As discussed in previous sections, styles may have substyles to e.g.
305 indicate different states of the object being drawn. The ``de'' engine
306 limits what can be configured in substyles to the set of colours in the
307 first table above, but also specifically interprets for the main style
308 \codestr{tab-frame} the substyles \codestr{*-*-tagged} and \codestr{*-*-*-dragged}
309 by, respectively, drawing a right angle shape at the top right corner
310 of a tab and by shading the tab with a stipple pattern. Also for
311 menus the substyles \codestr{*-*-submenu} are handled as a special case.
313 Substyles are defined with the function \fnref{de.substyle} within the
314 table defining the main style. The parameters to this function are
315 similar to those of \fnref{de.defstyle}.
318 de.defstyle("some-style", {
320 de.substyle("some-substyle", {
328 \subsection{An example}
330 The following shortened segment from \file{look\_cleanviolet.lua}
331 should help to clarify the matters discussed in the previous
337 highlight_colour = "#eeeeee",
338 shadow_colour = "#eeeeee",
339 background_colour = "#aaaaaa",
340 foreground_colour = "#000000",
343 highlight_pixels = 1,
346 border_style = "elevated",
348 font = "-*-helvetica-medium-r-normal-*-12-*-*-*-*-*-*-*",
349 text_align = "center",
352 de.defstyle("tab-frame", {
355 de.substyle("active-selected", {
357 highlight_colour = "#aaaacc",
358 shadow_colour = "#aaaacc",
359 background_colour = "#666699",
360 foreground_colour = "#eeeeee",
363 -- More substyles would follow ...
368 \section{Miscellaneous settings}
372 \subsection{Frame user attributes}
374 The function \fnref{WFrame.set_grattr} may be used to give frames
375 (and their tabs) arbitrary extra attributes to be passed to the
376 drawing engine. Hence, by configuring such substyles in the style
377 configuration files, and turning on the attribute when needed,
378 scripts may display visual cues related to the frame. There is
379 also one extra attribute specially interpreted by the default
380 drawing engine: the \codestr{numbered} attribute, which causes
381 numbers to be displayed on the tabs.
384 \subsection{Extra fields for style \codestr{frame}}
386 The following style fields are independent of the drawing engine used,
387 but are related to objects' styles and therefore configured in the drawing
388 engine configuration file.
390 \begin{tabularx}{\linewidth}{lX}
391 \tabhead{Field & Description}
392 \code{bar} & Controls the style of the tab-bar. Possible values
393 are the strings \codestr{none}, \codestr{inside}, \codestr{outside}
394 and \codestr{shaped}, with the last providing the PWM-style
395 tab-bars for floating frames. \\
396 \code{floatframe_tab_min_w} & Minimum tab width in pixels for
397 the shaped style, given that this number times number of tabs
398 doesn't exceed frame width. \\
399 \code{floatframe_bar_max_w_q} & Maximum tab-bar width quotient of
400 frame width for the shaped styles. A number in the
406 \subsection{Extra fields for style \codestr{dock}}
408 \begin{tabularx}{\linewidth}{lX}
409 \tabhead{Field & Description}
410 \code{outline_style} & How borders are drawn:
411 \codestr{none} -- no border,
412 \codestr{all} -- border around whole dock,
413 \codestr{each} -- border around each dockapp. \\
414 \code{tile_size} & A table with entries \codestr{width} and \codestr{height},
415 indicating the width and height of tiles in pixels.
419 Hopefully that's enough to get you started in writing new style
420 configuration files for Ion. When in doubt, study the existing
421 style configuration files.