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}.
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 those of
101 the \codestr{frame} style, as well as tab-specific
102 \codestr{tagged}/\codestr{not\_tagged},
103 \codestr{dragged}/\codestr{not\_dragged}, and
104 \codestr{activity}/\codestr{no\_activity}. \\
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. \\
116 Extra information tab (displayed e.g. for tagged workspaces). \\
119 \subsubsection{The rest}
121 \begin{tabularx}{\linewidth}{lX}
122 \tabhead{Style name & Description}
123 \codestr{input} & A style for \type{WInput}s. \\
124 \codestr{input-edln} & A more specific style for \type{WEdln}s.
125 Substyle attributes: \codestr{selection} for selected text and
126 \codestr{cursor} for the cursor indicating current editing point. \\
127 \codestr{input-message} & A more specific style for \type{WMessage}s. \\
128 \codestr{input-menu} & A more specific style for \type{WMenu}s. \\
129 \codestr{input-menu-bigmenu} & An alternate style for \type{WMenu}s. \\
130 \codestr{moveres\_display} & The box displaying position/size when
131 moving or resizing frames. \\
132 \codestr{actnotify} & Actification notification box. \\
133 \codestr{stdisp} & Any status display. \\
134 \codestr{stdisp-dock} & The dock. \\
135 \codestr{stdisp-statusbar} & The statusbar. Substyles include:
136 the name of any monitor/meter (such as \codestr{date}), and
137 the supplied hint. Typical hints are: \codestr{normal},
138 \codestr{important}, and \codestr{critical}. \\
142 \section{Defining styles for the default drawing engine}
143 \label{sec:defaultde}
145 Drawing engine style files are usually named
146 \file{look\_foo.lua} where \file{foo} is the name of the
147 style. The file that Ion loads on startup or when
148 \fnref{gr.read_config} is called, however, is \file{look.lua}
149 and should usually be symlinked to or a copy of of some
150 \file{look\_foo.lua}.
152 \subsection{The structure of the configuration files}
154 The first thing to do in a style file is to choose the drawing
155 engine, possibly loading the module as well. This is done
156 with the following chunk of code.
159 if not gr.select_engine("de") then
164 The \fnref{gr.select_engine} function sees if the engine
165 given as argument is registered (the default drawing engine is
166 simply called ``de''). If the engine could not be found, it
167 tries to load a module of the same name. If the engine still
168 is not registered, \fnref{gr.select_engine} returns \codestr{false}
169 and in this case we also exit the style setup script.
170 If the engine was found, \fnref{gr.select_engine} sees that
171 further requests for brushes are forwarded to that engine
172 and returns \codestr{true}.
174 Before defining new styles it may be a good idea to clear old
175 styles from memory so if the old configuration defines more
176 specific styles than the new, the old styles don't override
177 those specified by the new configuration. That can be done by
184 After this the new styles can be defined with \fnref{de.defstyle}
185 as explained in the next subsection. Finally, after the styles have
186 been defined we must ask objects on the screen to look up new brushes
187 to reflect the changes in configuration. This is done with
193 \subsection{Defining the styles}
195 Styles for the default drawing engine are defined with the
196 function \fnref{de.defstyle}. It has two arguments the first being
197 a style specification as explained in previous sections and the second
198 a table whose fields describe the style:
201 de.defstyle("some-style", {
207 The supported attributes are described in tables below. The different
208 border elements and styles referred to there are explained in Figure
213 \docode % Kludge to make latex2html interpret contents instead of
217 Elevated: Inlaid: Ridge: Groove:
218 hhhhhhhhhhhs ............ hhhhhhhhhhhs sssssssssssh
219 h..........s .sssssssssh. h..........s s..........h
220 h. .s .s h. h.sssssssh.s s.hhhhhhhs.h
221 h. .s .s h. h.s h.s s.h s.h
222 h. .s .s h. h.shhhhhhh.s s.hsssssss.h
223 h..........s .shhhhhhhhh. h..........s s..........h
224 hsssssssssss ............ hsssssssssss shhhhhhhhhhh
226 h = highlight, s = shadow, . = padding
228 \caption{Sketch of different border styles and elements}
232 \subsubsection{Colours}
234 Each of these fields a string of the form that can be
235 passed to \code{XAllocNamedColor}. Valid strings are e.g.
236 hexadecimal RGB specifications of the form
237 \code{#RRGGBB} and colour names as specified
238 in \file{/usr/X11R6/lib/X11/rgb.txt} (exact path varying).
240 \begin{tabularx}{\linewidth}{lX}
241 \tabhead{Field & Description}
242 \var{highlight_colour} &
243 Colour for the ``highlight'' part of a border. \\
244 \var{shadow_colour} &
245 Colour for the ``shadow'' part of a border. \\
246 \var{foreground_colour} &
247 Colour for the normal drawing operations, e.g. text. \\
248 \var{background_colour} &
249 Window background colour (unless transparency is enabled) and
250 background colour boxes. \\
251 \var{padding_colour} &
252 Colour for the ``padding'' part of a border border. Set to
253 \var{background_colour} if unset. \\
257 \subsubsection{Borders and widths}
259 All other fields below except \var{border_style} are non-negative integers
260 indicating a number of pixels.
262 \begin{tabularx}{\linewidth}{lX}
263 \tabhead{Field & Description}
264 \var{border_style} & A string indicating the style of border; one of
265 \codestr{elevated}/\codestr{inlaid}/\codestr{ridge}/\codestr{groove}
266 as seen in the above sketch. \\
267 \var{border_sides} & A string indicating which sides of the border
268 to draw: \codestr{all}/\codestr{tb}/\codestr{lr} for all,
269 top and bottom, and left and right. To control between
270 left/right and top/bottom, use the pixel options below. \\
271 \var{highlight_pixels} &
272 Width of the highlight part of the border in pixels. \\
273 \var{shadow_pixels} &
274 Width of the shadow part of the border in pixels. \\
275 \var{padding_pixels} &
276 Width of the padding part of the border in pixels. \\
278 Space to be left between all kinds of boxes. \\
284 \begin{tabularx}{\linewidth}{lX}
285 \tabhead{Field & Description}
286 \var{font} & Font to be used in text-drawing operations; standard X font
288 \var{text_align} & How text is to be aligned in text boxes/tabs; one of
289 the strings \codestr{left}/\codestr{right}/\codestr{center}. \\
293 \subsubsection{Miscellaneous}
296 \begin{tabularx}{\linewidth}{lX}
297 \tabhead{Field & Description}
298 \var{transparent_background} & Should windows' that use this style
299 background be transparent? true/false. \\
300 \var{based_on} & The name of a previously defined style that this
301 style should be based on. \\
305 \subsubsection{Substyles}
307 As discussed in previous sections, styles may have substyles to e.g.
308 indicate different states of the object being drawn. The ``de'' engine
309 limits what can be configured in substyles to the set of colours in the
310 first table above, but also specifically interprets for the main style
311 \codestr{tab-frame} the substyles \codestr{*-*-tagged} and \codestr{*-*-*-dragged}
312 by, respectively, drawing a right angle shape at the top right corner
313 of a tab and by shading the tab with a stipple pattern. Also for
314 menus the substyles \codestr{*-*-submenu} are handled as a special case.
316 Substyles are defined with the function \fnref{de.substyle} within the
317 table defining the main style. The parameters to this function are
318 similar to those of \fnref{de.defstyle}.
321 de.defstyle("some-style", {
323 de.substyle("some-substyle", {
331 \subsection{An example}
333 The following shortened segment from \file{look\_cleanviolet.lua}
334 should help to clarify the matters discussed in the previous
340 highlight_colour = "#eeeeee",
341 shadow_colour = "#eeeeee",
342 background_colour = "#aaaaaa",
343 foreground_colour = "#000000",
346 highlight_pixels = 1,
349 border_style = "elevated",
351 font = "-*-helvetica-medium-r-normal-*-12-*-*-*-*-*-*-*",
352 text_align = "center",
355 de.defstyle("tab-frame", {
358 de.substyle("active-selected", {
360 highlight_colour = "#aaaacc",
361 shadow_colour = "#aaaacc",
362 background_colour = "#666699",
363 foreground_colour = "#eeeeee",
366 -- More substyles would follow ...
371 \section{Miscellaneous settings}
375 \subsection{Frame user attributes}
377 The function \fnref{WFrame.set_grattr} may be used to give frames
378 (and their tabs) arbitrary extra attributes to be passed to the
379 drawing engine. Hence, by configuring such substyles in the style
380 configuration files, and turning on the attribute when needed,
381 scripts may display visual cues related to the frame. There is
382 also one extra attribute specially interpreted by the default
383 drawing engine: the \codestr{numbered} attribute, which causes
384 numbers to be displayed on the tabs.
387 \subsection{Extra fields for style \codestr{frame}}
389 The following style fields are independent of the drawing engine used,
390 but are related to objects' styles and therefore configured in the drawing
391 engine configuration file.
393 \begin{tabularx}{\linewidth}{lX}
394 \tabhead{Field & Description}
395 \code{bar} & Controls the style of the tab-bar. Possible values
396 are the strings \codestr{none}, \codestr{inside}, \codestr{outside}
397 and \codestr{shaped}, with the last providing the PWM-style
398 tab-bars for floating frames. \\
399 \code{floatframe_tab_min_w} & Minimum tab width in pixels for
400 the shaped style, given that this number times number of tabs
401 doesn't exceed frame width. \\
402 \code{floatframe_bar_max_w_q} & Maximum tab-bar width quotient of
403 frame width for the shaped styles. A number in the
409 \subsection{Extra fields for style \codestr{dock}}
411 \begin{tabularx}{\linewidth}{lX}
412 \tabhead{Field & Description}
413 \code{outline_style} & How borders are drawn:
414 \codestr{none} -- no border,
415 \codestr{all} -- border around whole dock,
416 \codestr{each} -- border around each dockapp. \\
417 \code{tile_size} & A table with entries \codestr{width} and \codestr{height},
418 indicating the width and height of tiles in pixels.
422 Hopefully that's enough to get you started in writing new style
423 configuration files for Ion. When in doubt, study the existing
424 style configuration files.