]> git.decadent.org.uk Git - ion3-doc.git/blob - de.tex
Merge commit '20080411' into HEAD
[ion3-doc.git] / de.tex
1
2 \chapter{Graphical styles}
3 \label{chap:gr}
4
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}.
10
11
12 \section{Drawing engines, style specifications and sub-styles}
13 \label{sec:engines}
14 \index{style}\index{drawing engine}
15
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
28
29 \begin{verbatim}
30 element1-element2-...-elementn
31 \end{verbatim}
32
33 An example of such a style specification is \codestr{tab-frame};
34 see the table in subsection \ref{sec:styles} for more styles.
35
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:
44
45 \begin{verbatim}
46 foo-bar-baz
47 foo-*-baz
48 foo-bar
49 *
50 \end{verbatim}
51
52 Some of the drawing primitives allow extra attributes to be
53 specified, also in the form
54 \begin{verbatim}
55 attr1-attr2-...-attrn
56 \end{verbatim}
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 
65 tag and drag states.)
66
67
68 \subsection{Known styles and substyles}
69 \label{sec:styles}
70
71 \subsubsection{Frames}
72
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
86         frames. \\
87 \codestr{frame-transient} & A more specific style for frames
88         containing transient windows. \\
89 \end{tabularx}
90
91 \subsubsection{Tabs and menu entries}
92
93 \begin{tabularx}{\linewidth}{lX}
94 \tabhead{Style name & Description}
95 \codestr{tab} & Style for frames' tabs and menu entries. 
96         Substyle attributes:
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
109         different modes. \\
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. \\
115 \codestr{tab-info} & 
116         Extra information tab (displayed e.g. for tagged workspaces). \\
117 \end{tabularx}
118
119 \subsubsection{The rest}
120
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}. \\
139 \end{tabularx}
140
141
142 \section{Defining styles for the default drawing engine}
143 \label{sec:defaultde}
144
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}.
151
152 \subsection{The structure of the configuration files}
153
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.
157
158 \begin{verbatim}
159 if not gr.select_engine("de") then 
160     return 
161 end
162 \end{verbatim}
163
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}.
173
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
178 calling
179
180 \begin{verbatim}
181 de.reset()
182 \end{verbatim}
183
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
188
189 \begin{verbatim}
190 gr.refresh()
191 \end{verbatim}
192
193 \subsection{Defining the styles}
194
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:
199
200 \begin{verbatim}
201 de.defstyle("some-style", {
202     attribute = value,
203     ...
204 })
205 \end{verbatim}
206
207 The supported attributes are described in tables below. The different
208 border elements and styles referred to there are explained in Figure
209 \ref{fig:borders}.
210
211 \begin{figure}
212 \begin{htmlonly}
213 \docode % Kludge to make latex2html interpret contents instead of
214         % creating an image.
215 \end{htmlonly}    
216 \begin{verbatim}
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
225
226 h = highlight, s = shadow, . = padding
227 \end{verbatim}
228 \caption{Sketch of different border styles and elements}
229 \label{fig:borders}
230 \end{figure}
231
232 \subsubsection{Colours}
233
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).
239
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. \\
254 \end{tabularx}
255
256
257 \subsubsection{Borders and widths}
258
259 All other fields below except \var{border_style} are non-negative integers
260 indicating a number of pixels.
261
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. \\
277 \var{spacing} &
278         Space to be left between all kinds of boxes. \\
279 \end{tabularx}
280
281
282 \subsubsection{Text}
283
284 \begin{tabularx}{\linewidth}{lX}
285 \tabhead{Field  & Description}
286 \var{font} & Font to be used in text-drawing operations; standard X font
287              name. \\
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}. \\
290 \end{tabularx}
291
292
293 \subsubsection{Miscellaneous}
294
295
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. \\
302 \end{tabularx}
303
304
305 \subsubsection{Substyles}
306
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.
315
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}.
319
320 \begin{verbatim}
321 de.defstyle("some-style", {
322    ...
323    de.substyle("some-substyle", {
324       ...
325    }),
326    ...
327 })
328 \end{verbatim}
329
330
331 \subsection{An example}
332
333 The following shortened segment from \file{look\_cleanviolet.lua}
334 should help to clarify the matters discussed in the previous
335 subsection.
336
337 \begin{verbatim}
338 de.defstyle("*", {
339     -- Gray background
340     highlight_colour = "#eeeeee",
341     shadow_colour = "#eeeeee",
342     background_colour = "#aaaaaa",
343     foreground_colour = "#000000",
344     
345     shadow_pixels = 1,
346     highlight_pixels = 1,
347     padding_pixels = 1,
348     spacing = 0,
349     border_style = "elevated",
350     
351     font = "-*-helvetica-medium-r-normal-*-12-*-*-*-*-*-*-*",
352     text_align = "center",
353 })
354
355 de.defstyle("tab-frame", {
356     based_on = "*",
357     
358     de.substyle("active-selected", {
359         -- Violet tab
360         highlight_colour = "#aaaacc",
361         shadow_colour = "#aaaacc",
362         background_colour = "#666699",
363         foreground_colour = "#eeeeee",
364     }),
365
366     --  More substyles would follow ...
367 })
368 \end{verbatim}
369
370
371 \section{Miscellaneous settings}
372 \label{sec:grmisc}
373
374
375 \subsection{Frame user attributes}
376
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.
385
386
387 \subsection{Extra fields for style \codestr{frame}}
388
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.
392
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 
404         interval $(0, 1]$.
405 \end{tabularx}
406
407
408
409 \subsection{Extra fields for style \codestr{dock}}
410
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.
419 \end{tabularx}
420
421
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.