]> git.decadent.org.uk Git - ion3.git/blob - doc/ionconf/node5.html
7fe37d1f2b5b31f06059c9c9ef58768eff97b1a0
[ion3.git] / doc / ionconf / node5.html
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2
3 <!--Converted with LaTeX2HTML 2002-2-1 (1.71)
4 original version by:  Nikos Drakos, CBLU, University of Leeds
5 * revised and updated by:  Marcus Hennecke, Ross Moore, Herb Swan
6 * with significant contributions from:
7   Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
8 <HTML>
9 <HEAD>
10 <TITLE>4. Graphical styles</TITLE>
11 <META NAME="description" CONTENT="4. Graphical styles">
12 <META NAME="keywords" CONTENT="ionconf">
13 <META NAME="resource-type" CONTENT="document">
14 <META NAME="distribution" CONTENT="global">
15
16 <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
17 <META NAME="Generator" CONTENT="LaTeX2HTML v2002-2-1">
18 <META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
19
20 <LINK REL="STYLESHEET" HREF="ionconf.css">
21
22 <LINK REL="next" HREF="node6.html">
23 <LINK REL="previous" HREF="node4.html">
24 <LINK REL="up" HREF="ionconf.html">
25 <LINK REL="next" HREF="node6.html">
26 </HEAD>
27
28 <BODY >
29
30 <DIV CLASS="navigation"><!--Navigation Panel-->
31 <A NAME="tex2html331"
32   HREF="node6.html">
33 <IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A> 
34 <A NAME="tex2html325"
35   HREF="ionconf.html">
36 <IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A> 
37 <A NAME="tex2html319"
38   HREF="node4.html">
39 <IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A> 
40 <A NAME="tex2html327"
41   HREF="node1.html">
42 <IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A> 
43 <A NAME="tex2html329"
44   HREF="node11.html">
45 <IMG WIDTH="43" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="index" SRC="index.png"></A> 
46 <BR>
47 <B> Next:</B> <A NAME="tex2html332"
48   HREF="node6.html">5. Scripting</A>
49 <B> Up:</B> <A NAME="tex2html326"
50   HREF="ionconf.html">Configuring and extending Ion3</A>
51 <B> Previous:</B> <A NAME="tex2html320"
52   HREF="node4.html">3. Basic configuration</A>
53  &nbsp; <B>  <A NAME="tex2html328"
54   HREF="node1.html">Contents</A></B> 
55  &nbsp; <B>  <A NAME="tex2html330"
56   HREF="node11.html">Index</A></B> 
57 <BR>
58 <BR></DIV>
59 <!--End of Navigation Panel-->
60 <!--Table of Child-Links-->
61 <A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></A>
62
63 <UL CLASS="ChildLinks">
64 <LI><A NAME="tex2html333"
65   HREF="node5.html#SECTION00510000000000000000"><SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">1</SPAN> Drawing engines, style specifications and sub-styles</A>
66 <UL>
67 <LI><A NAME="tex2html334"
68   HREF="node5.html#SECTION00511000000000000000"><SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">1</SPAN>.<SPAN CLASS="arabic">1</SPAN> Known styles and substyles</A>
69 <UL>
70 <LI><A NAME="tex2html335"
71   HREF="node5.html#SECTION00511100000000000000"><SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">1</SPAN>.<SPAN CLASS="arabic">1</SPAN>.<SPAN CLASS="arabic">1</SPAN> Frames</A>
72 <LI><A NAME="tex2html336"
73   HREF="node5.html#SECTION00511200000000000000"><SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">1</SPAN>.<SPAN CLASS="arabic">1</SPAN>.<SPAN CLASS="arabic">2</SPAN> Tabs and menu entries</A>
74 <LI><A NAME="tex2html337"
75   HREF="node5.html#SECTION00511300000000000000"><SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">1</SPAN>.<SPAN CLASS="arabic">1</SPAN>.<SPAN CLASS="arabic">3</SPAN> The rest</A>
76 </UL>
77 </UL>
78 <BR>
79 <LI><A NAME="tex2html338"
80   HREF="node5.html#SECTION00520000000000000000"><SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">2</SPAN> Defining styles for the default drawing engine</A>
81 <UL>
82 <LI><A NAME="tex2html339"
83   HREF="node5.html#SECTION00521000000000000000"><SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">1</SPAN> The structure of the configuration files</A>
84 <LI><A NAME="tex2html340"
85   HREF="node5.html#SECTION00522000000000000000"><SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">2</SPAN> Defining the styles</A>
86 <UL>
87 <LI><A NAME="tex2html341"
88   HREF="node5.html#SECTION00522100000000000000"><SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">1</SPAN> Colours</A>
89 <LI><A NAME="tex2html342"
90   HREF="node5.html#SECTION00522200000000000000"><SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">2</SPAN> Borders and widths</A>
91 <LI><A NAME="tex2html343"
92   HREF="node5.html#SECTION00522300000000000000"><SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">3</SPAN> Text</A>
93 <LI><A NAME="tex2html344"
94   HREF="node5.html#SECTION00522400000000000000"><SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">4</SPAN> Miscellaneous</A>
95 <LI><A NAME="tex2html345"
96   HREF="node5.html#SECTION00522500000000000000"><SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">5</SPAN> Substyles</A>
97 </UL>
98 <LI><A NAME="tex2html346"
99   HREF="node5.html#SECTION00523000000000000000"><SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">3</SPAN> An example</A>
100 </UL>
101 <BR>
102 <LI><A NAME="tex2html347"
103   HREF="node5.html#SECTION00530000000000000000"><SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">3</SPAN> Miscellaneous settings</A>
104 <UL>
105 <LI><A NAME="tex2html348"
106   HREF="node5.html#SECTION00531000000000000000"><SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">1</SPAN> Frame user attributes</A>
107 <LI><A NAME="tex2html349"
108   HREF="node5.html#SECTION00532000000000000000"><SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">2</SPAN> Extra fields for style `<TT>frame</TT>'</A>
109 <LI><A NAME="tex2html350"
110   HREF="node5.html#SECTION00533000000000000000"><SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN> Extra fields for style `<TT>dock</TT>'</A>
111 </UL></UL>
112 <!--End of Table of Child-Links-->
113 <HR>
114
115 <H1><A NAME="SECTION00500000000000000000"></A>
116 <A NAME="chap:gr"></A>
117 <BR>
118 <SPAN CLASS="arabic">4</SPAN>. Graphical styles
119 </H1>
120
121 <P>
122 This chapter first gives in section <A HREF="#sec:engines">4.1</A> a general outline 
123 of how drawing engines are used, of style specifications and then
124 in section <A HREF="#sec:defaultde">4.2</A> describes how to specify styles
125 for the default drawing engine. Some additional settings and
126 user attributes are explained in Sections <A HREF="#sec:grmisc">4.3</A>.
127
128 <P>
129
130 <H2><A NAME="SECTION00510000000000000000"></A>
131 <A NAME="sec:engines"></A><A NAME="1905"></A><A NAME="1906"></A>
132 <BR>
133 <SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">1</SPAN> Drawing engines, style specifications and sub-styles
134 </H2>
135
136 <P>
137 Ion's drawing routines are abstracted into so-called drawing engine
138 modules that can, again depending on the system, be dynamically
139 loaded as needed. The drawing engine modules provide ``brushes''
140 that objects can use to draw some high-level primitives such
141 as borders and text boxes (in addition to simple text and rectangle
142 drawing) on their windows and configure e.g. the shape and 
143 background of the window. While the drawing engines therefore
144 do not directly implement looks for each possible object (that
145 would hardly be maintainable), different brush styles can be
146 used to give a distinctive look to different objects and engines
147 could interpret some styles as special cases. Style specifications 
148 are strings of the form
149
150 <P>
151 <PRE>
152 element1-element2-...-elementn
153 </PRE>
154
155 <P>
156 An example of such a style specification is `<TT>tab-frame</TT>';
157 see the table in subsection <A HREF="#sec:styles">4.1.1</A> for more styles.
158
159 <P>
160 When an object asks for a brush of certain style, the selected
161 drawing engine will attempt to find the closest match to this
162 specification. The styles/brushes defined by the drawing engines 
163 may have asterisks (`<TT>*</TT>') as some of the elements indicating
164 a match to anything. Exact matches are preferred to asterisk
165 matches and longer matches to shorter. For example, let a brush
166 for style `<TT>foo-bar-baz</TT>' be queried, then the following
167 brushes are in order of preference:
168
169 <P>
170 <PRE>
171 foo-bar-baz
172 foo-*-baz
173 foo-bar
174 *
175 </PRE>
176
177 <P>
178 Some of the drawing primitives allow extra attributes to be
179 specified, also in the form
180 <PRE>
181 attr1-attr2-...-attrn
182 </PRE>
183 These extra attributes are called <SPAN  CLASS="textit">substyles</SPAN><A NAME="1918"></A>
184 and allow, for example, the state of the object to be indicated 
185 by  different colour sets while keeping the interface at an 
186 abstract level and the drawing engine completely ignorant 
187 of the semantics - only the writer of the drawing engine
188 configuration file has to know them. However the drawing 
189 engine can again interpret known substyles as special cases
190 and the default engine indeed does so with frame tab 
191 tag and drag states.)
192
193 <P>
194
195 <H3><A NAME="SECTION00511000000000000000"></A>
196 <A NAME="sec:styles"></A>
197 <BR>
198 <SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">1</SPAN>.<SPAN CLASS="arabic">1</SPAN> Known styles and substyles
199 </H3>
200
201 <P>
202
203 <H4><A NAME="SECTION00511100000000000000">
204 <SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">1</SPAN>.<SPAN CLASS="arabic">1</SPAN>.<SPAN CLASS="arabic">1</SPAN> Frames</A>
205 </H4>
206
207 <P>
208 <TABLE CELLPADDING=3 BORDER="1" WIDTH="100%">
209 <TR><TD ALIGN="LEFT">Style name</TD>
210 <TD ALIGN="LEFT">Description</TD>
211 </TR>
212 <TR><TD ALIGN="LEFT">`<TT>frame</TT>'</TD>
213 <TD ALIGN="LEFT">Style for frames. 
214         Substyle attributes: `<TT>active</TT>'/`<TT>inactive</TT>' 
215         (mutually exclusive) and
216         `<TT>quasiactive</TT>'/`<TT>not_quasiactive</TT>'. 
217         A frame is ``quasiactive'' when an active region
218         has a back-link to it, such as a detached window.</TD>
219 </TR>
220 <TR><TD ALIGN="LEFT">`<TT>frame-tiled</TT>'</TD>
221 <TD ALIGN="LEFT">A more specific style for tiled frames.
222         Substyle attributes as for `<TT>frame</TT>'.</TD>
223 </TR>
224 <TR><TD ALIGN="LEFT">`<TT>frame-tiled-alt</TT>'</TD>
225 <TD ALIGN="LEFT">An alternative style for tiled frames.
226         Often used to disable the tab-bar.</TD>
227 </TR>
228 <TR><TD ALIGN="LEFT">`<TT>frame-floating</TT>'</TD>
229 <TD ALIGN="LEFT">A more specific style for floating
230         frames.</TD>
231 </TR>
232 <TR><TD ALIGN="LEFT">`<TT>frame-transient</TT>'</TD>
233 <TD ALIGN="LEFT">A more specific style for frames
234         containing transient windows.</TD>
235 </TR>
236 </TABLE>
237
238 <P>
239
240 <H4><A NAME="SECTION00511200000000000000">
241 <SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">1</SPAN>.<SPAN CLASS="arabic">1</SPAN>.<SPAN CLASS="arabic">2</SPAN> Tabs and menu entries</A>
242 </H4>
243
244 <P>
245 <TABLE CELLPADDING=3 BORDER="1" WIDTH="100%">
246 <TR><TD ALIGN="LEFT">Style name</TD>
247 <TD ALIGN="LEFT">Description</TD>
248 </TR>
249 <TR><TD ALIGN="LEFT">`<TT>tab</TT>'</TD>
250 <TD ALIGN="LEFT">Style for frames' tabs and menu entries. 
251         Substyle attributes:
252         `<TT>active</TT>'/`<TT>inactive</TT>' and
253         `<TT>selected</TT>'/`<TT>unselected</TT>'</TD>
254 </TR>
255 <TR><TD ALIGN="LEFT">`<TT>tab-frame</TT>'</TD>
256 <TD ALIGN="LEFT">A more specific style for frames' tabs.
257         Additional substyle attributes include:
258         `<TT>tagged</TT>'/`<TT>not_tagged</TT>',
259         `<TT>dragged</TT>'/`<TT>not_dragged</TT>',
260         `<TT>activity</TT>'/`<TT>no_activity</TT>',
261         `<TT>quasiactive</TT>'/`<TT>not_quasiactive</TT>'.</TD>
262 </TR>
263 <TR><TD ALIGN="LEFT">`<TT>tab-frame-tiled</TT>',</TD>
264 <TD ALIGN="LEFT">&nbsp;</TD>
265 </TR>
266 <TR><TD ALIGN="LEFT">`<TT>tab-frame-tiled-alt</TT>',</TD>
267 <TD ALIGN="LEFT">&nbsp;</TD>
268 </TR>
269 <TR><TD ALIGN="LEFT">`<TT>tab-frame-floating</TT>',</TD>
270 <TD ALIGN="LEFT">&nbsp;</TD>
271 </TR>
272 <TR><TD ALIGN="LEFT">`<TT>tab-frame-transient</TT>'</TD>
273 <TD ALIGN="LEFT">More specific styles for frames in the
274         different modes.</TD>
275 </TR>
276 <TR><TD ALIGN="LEFT">`<TT>tab-menuentry</TT>'</TD>
277 <TD ALIGN="LEFT">A more specific style for entries in WMenus. 
278         Additional substyle attributes include `<TT>submenu</TT>' and
279         occasionally also `<TT>activity</TT>' is used.</TD>
280 </TR>
281 <TR><TD ALIGN="LEFT">`<TT>tab-menuentry-bigmenu</TT>'</TD>
282 <TD ALIGN="LEFT">An alternate style for entries in WMenus.</TD>
283 </TR>
284 </TABLE>
285
286 <P>
287
288 <H4><A NAME="SECTION00511300000000000000">
289 <SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">1</SPAN>.<SPAN CLASS="arabic">1</SPAN>.<SPAN CLASS="arabic">3</SPAN> The rest</A>
290 </H4>
291
292 <P>
293 <TABLE CELLPADDING=3 BORDER="1" WIDTH="100%">
294 <TR><TD ALIGN="LEFT">Style name</TD>
295 <TD ALIGN="LEFT">Description</TD>
296 </TR>
297 <TR><TD ALIGN="LEFT">`<TT>input</TT>'</TD>
298 <TD ALIGN="LEFT">A style for WInputs.</TD>
299 </TR>
300 <TR><TD ALIGN="LEFT">`<TT>input-edln</TT>'</TD>
301 <TD ALIGN="LEFT">A more specific style for WEdlns. 
302         Substyle attributes: `<TT>selection</TT>' for selected text and
303         `<TT>cursor</TT>' for the cursor indicating current editing point.</TD>
304 </TR>
305 <TR><TD ALIGN="LEFT">`<TT>input-message</TT>'</TD>
306 <TD ALIGN="LEFT">A more specific style for WMessages.</TD>
307 </TR>
308 <TR><TD ALIGN="LEFT">`<TT>input-menu</TT>'</TD>
309 <TD ALIGN="LEFT">A more specific style for WMenus.</TD>
310 </TR>
311 <TR><TD ALIGN="LEFT">`<TT>input-menu-bigmenu</TT>'</TD>
312 <TD ALIGN="LEFT">An alternate style for WMenus.</TD>
313 </TR>
314 <TR><TD ALIGN="LEFT">`<TT>moveres_display</TT>'</TD>
315 <TD ALIGN="LEFT">The box displaying position/size when
316         moving or resizing frames.</TD>
317 </TR>
318 <TR><TD ALIGN="LEFT">`<TT>stdisp</TT>'</TD>
319 <TD ALIGN="LEFT">Any status display.</TD>
320 </TR>
321 <TR><TD ALIGN="LEFT">`<TT>stdisp-dock</TT>'</TD>
322 <TD ALIGN="LEFT">The dock.</TD>
323 </TR>
324 <TR><TD ALIGN="LEFT">`<TT>stdisp-statusbar</TT>'</TD>
325 <TD ALIGN="LEFT">The statusbar. Substyles include:
326     the name of any monitor/meter (such as `<TT>date</TT>'), and 
327     the supplied hint. Typical hints are: `<TT>normal</TT>',
328     `<TT>important</TT>', and `<TT>critical</TT>'.</TD>
329 </TR>
330 </TABLE>
331
332 <P>
333
334 <H2><A NAME="SECTION00520000000000000000"></A>
335 <A NAME="sec:defaultde"></A>
336 <BR>
337 <SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">2</SPAN> Defining styles for the default drawing engine
338 </H2>
339
340 <P>
341 Drawing engine style files are usually named
342 <SPAN  CLASS="textit">look_foo.lua</SPAN> where <SPAN  CLASS="textit">foo</SPAN> is the name of the
343 style. The file that Ion loads on startup or when
344 <A HREF="node7.html#fn:gr.read_config"><TT>gr.read_config</TT></A> is called, however, is <SPAN  CLASS="textit">look.lua</SPAN>
345 and should usually be symlinked to or a copy of of some
346 <SPAN  CLASS="textit">look_foo.lua</SPAN>.
347
348 <P>
349
350 <H3><A NAME="SECTION00521000000000000000">
351 <SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">1</SPAN> The structure of the configuration files</A>
352 </H3>
353
354 <P>
355 The first thing to do in a style file is to choose the drawing
356 engine, possibly loading the module as well. This is done
357 with the following chunk of code.
358
359 <P>
360 <PRE>
361 if not gr.select_engine("de") then 
362     return 
363 end
364 </PRE>
365
366 <P>
367 The <A HREF="node7.html#fn:gr.select_engine"><TT>gr.select_engine</TT></A> function sees if the engine
368 given as argument is registered (the default drawing engine is
369 simply called ``de''). If the engine could not be found, it
370 tries to load a module of the same name. If the engine still
371 is not registered, <A HREF="node7.html#fn:gr.select_engine"><TT>gr.select_engine</TT></A> returns `<TT>false</TT>'
372 and in this case we also exit the style setup script.
373 If the engine was found, <A HREF="node7.html#fn:gr.select_engine"><TT>gr.select_engine</TT></A> sees that
374 further requests for brushes are forwarded to that engine
375 and returns `<TT>true</TT>'.
376
377 <P>
378 Before defining new styles it may be a good idea to clear old
379 styles from memory so if the old configuration defines more
380 specific styles than the new, the old styles don't override 
381 those specified by the new configuration. That can be done by
382 calling
383
384 <P>
385 <PRE>
386 de.reset()
387 </PRE>
388
389 <P>
390 After this the new styles can be defined with <A HREF="node7.html#fn:de.defstyle"><TT>de.defstyle</TT></A>
391 as explained in the next subsection. Finally, after the styles have
392 been defined we must ask objects on the screen to look up new brushes
393 to reflect the changes in configuration. This is done with
394
395 <P>
396 <PRE>
397 gr.refresh()
398 </PRE>
399
400 <P>
401
402 <H3><A NAME="SECTION00522000000000000000">
403 <SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">2</SPAN> Defining the styles</A>
404 </H3>
405
406 <P>
407 Styles for the default drawing engine are defined with the
408 function <A HREF="node7.html#fn:de.defstyle"><TT>de.defstyle</TT></A>. It has two arguments the first being
409 a style specification as explained in previous sections and the second
410 a table whose fields describe the style:
411
412 <P>
413 <PRE>
414 de.defstyle("some-style", {
415     attribute = value,
416     ...
417 })
418 </PRE>
419
420 <P>
421 The supported attributes are described in tables below. The different
422 border elements and styles referred to there are explained in Figure
423 <A HREF="#fig:borders">4.1</A>.
424
425 <P>
426
427 <DIV ALIGN="CENTER"><A NAME="fig:borders"></A><A NAME="2021"></A>
428 <TABLE>
429 <CAPTION ALIGN="BOTTOM"><STRONG>Figure 4.1:</STRONG>
430 Sketch of different border styles and elements</CAPTION>
431 <TR><TD><PRE>
432 Elevated:        Inlaid:         Ridge:            Groove:        
433   hhhhhhhhhhhs     ............    hhhhhhhhhhhs      sssssssssssh
434   h..........s     .sssssssssh.    h..........s      s..........h
435   h.        .s     .s        h.    h.sssssssh.s      s.hhhhhhhs.h
436   h.        .s     .s        h.    h.s      h.s      s.h      s.h
437   h.        .s     .s        h.    h.shhhhhhh.s      s.hsssssss.h
438   h..........s     .shhhhhhhhh.    h..........s      s..........h
439   hsssssssssss     ............    hsssssssssss      shhhhhhhhhhh
440
441 h = highlight, s = shadow, . = padding
442 </PRE></TD></TR>
443 </TABLE>
444 </DIV>
445
446 <P>
447
448 <H4><A NAME="SECTION00522100000000000000">
449 <SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">1</SPAN> Colours</A>
450 </H4>
451
452 <P>
453 Each of these fields a string of the form that can be
454 passed to <TT>XAllocNamedColor</TT>. Valid strings are e.g.
455 hexadecimal RGB specifications of the form
456 <TT>#RRGGBB</TT> and colour names as specified
457 in <SPAN  CLASS="textit">/usr/X11R6/lib/X11/rgb.txt</SPAN> (exact path varying).
458
459 <P>
460 <TABLE CELLPADDING=3 BORDER="1" WIDTH="100%">
461 <TR><TD ALIGN="LEFT">Field</TD>
462 <TD ALIGN="LEFT">Description</TD>
463 </TR>
464 <TR><TD ALIGN="LEFT"><TT>highlight_colour</TT></TD>
465 <TD ALIGN="LEFT">Colour for the ``highlight'' part of a border.</TD>
466 </TR>
467 <TR><TD ALIGN="LEFT"><TT>shadow_colour</TT></TD>
468 <TD ALIGN="LEFT">Colour for the ``shadow'' part of a border.</TD>
469 </TR>
470 <TR><TD ALIGN="LEFT"><TT>foreground_colour</TT></TD>
471 <TD ALIGN="LEFT">Colour for the normal drawing operations, e.g. text.</TD>
472 </TR>
473 <TR><TD ALIGN="LEFT"><TT>background_colour</TT></TD>
474 <TD ALIGN="LEFT">Window background colour (unless transparency is enabled) and
475         background colour boxes.</TD>
476 </TR>
477 <TR><TD ALIGN="LEFT"><TT>padding_colour</TT></TD>
478 <TD ALIGN="LEFT">Colour for the ``padding'' part of a border border. Set to 
479         <TT>background_colour</TT> if unset.</TD>
480 </TR>
481 </TABLE>
482
483 <P>
484
485 <H4><A NAME="SECTION00522200000000000000">
486 <SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">2</SPAN> Borders and widths</A>
487 </H4>
488
489 <P>
490 All other fields below except <TT>border_style</TT> are non-negative integers
491 indicating a number of pixels.
492
493 <P>
494 <TABLE CELLPADDING=3 BORDER="1" WIDTH="100%">
495 <TR><TD ALIGN="LEFT">Field</TD>
496 <TD ALIGN="LEFT">Description</TD>
497 </TR>
498 <TR><TD ALIGN="LEFT"><TT>border_style</TT></TD>
499 <TD ALIGN="LEFT">A string indicating the style of border; one of
500                      `<TT>elevated</TT>'/`<TT>inlaid</TT>'/`<TT>ridge</TT>'/`<TT>groove</TT>'
501                      as seen in the above sketch.</TD>
502 </TR>
503 <TR><TD ALIGN="LEFT"><TT>border_sides</TT></TD>
504 <TD ALIGN="LEFT">A string indicating which sides of the border
505                      to draw: `<TT>all</TT>'/`<TT>tb</TT>'/`<TT>lr</TT>' for all, 
506                      top and bottom, and left and right. To control between
507                      left/right and top/bottom, use the pixel options below.</TD>
508 </TR>
509 <TR><TD ALIGN="LEFT"><TT>highlight_pixels</TT></TD>
510 <TD ALIGN="LEFT">Width of the highlight part of the border in pixels.</TD>
511 </TR>
512 <TR><TD ALIGN="LEFT"><TT>shadow_pixels</TT></TD>
513 <TD ALIGN="LEFT">Width of the shadow part of the border in pixels.</TD>
514 </TR>
515 <TR><TD ALIGN="LEFT"><TT>padding_pixels</TT></TD>
516 <TD ALIGN="LEFT">Width of the padding part of the border in pixels.</TD>
517 </TR>
518 <TR><TD ALIGN="LEFT"><TT>spacing</TT></TD>
519 <TD ALIGN="LEFT">Space to be left between all kinds of boxes.</TD>
520 </TR>
521 </TABLE>
522
523 <P>
524
525 <H4><A NAME="SECTION00522300000000000000">
526 <SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">3</SPAN> Text</A>
527 </H4>
528
529 <P>
530 <TABLE CELLPADDING=3 BORDER="1" WIDTH="100%">
531 <TR><TD ALIGN="LEFT">Field</TD>
532 <TD ALIGN="LEFT">Description</TD>
533 </TR>
534 <TR><TD ALIGN="LEFT"><TT>font</TT></TD>
535 <TD ALIGN="LEFT">Font to be used in text-drawing operations; standard X font
536              name.</TD>
537 </TR>
538 <TR><TD ALIGN="LEFT"><TT>text_align</TT></TD>
539 <TD ALIGN="LEFT">How text is to be aligned in text boxes/tabs; one of
540                    the strings `<TT>left</TT>'/`<TT>right</TT>'/`<TT>center</TT>'.</TD>
541 </TR>
542 </TABLE>
543
544 <P>
545
546 <H4><A NAME="SECTION00522400000000000000">
547 <SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">4</SPAN> Miscellaneous</A>
548 </H4>
549
550 <P>
551 <TABLE CELLPADDING=3 BORDER="1" WIDTH="100%">
552 <TR><TD ALIGN="LEFT">Field</TD>
553 <TD ALIGN="LEFT">Description</TD>
554 </TR>
555 <TR><TD ALIGN="LEFT"><TT>transparent_background</TT></TD>
556 <TD ALIGN="LEFT">Should windows' that use this style
557         background be transparent? true/false.</TD>
558 </TR>
559 <TR><TD ALIGN="LEFT"><TT>based_on</TT></TD>
560 <TD ALIGN="LEFT">The name of a previously defined style that this
561         style should be based on.</TD>
562 </TR>
563 </TABLE>
564
565 <P>
566
567 <H4><A NAME="SECTION00522500000000000000">
568 <SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">5</SPAN> Substyles</A>
569 </H4>
570
571 <P>
572 As discussed in previous sections, styles may have substyles to e.g.
573 indicate different states of the object being drawn. The ``de'' engine
574 limits what can be configured in substyles to the set of colours in the
575 first table above, but also specifically interprets for the main style
576 `<TT>tab-frame</TT>' the substyles `<TT>*-*-tagged</TT>' and `<TT>*-*-*-dragged</TT>'
577 by, respectively, drawing a right angle shape at the top right corner 
578 of a tab and by shading the tab with a stipple pattern. Also for
579 menus the substyles `<TT>*-*-submenu</TT>' are handled as a special case.
580
581 <P>
582 Substyles are defined with the function <A HREF="node7.html#fn:de.substyle"><TT>de.substyle</TT></A> within the
583 table defining the main style. The parameters to this function are 
584 similar to those of <A HREF="node7.html#fn:de.defstyle"><TT>de.defstyle</TT></A>.
585
586 <P>
587 <PRE>
588 de.defstyle("some-style", {
589    ...
590    de.substyle("some-substyle", {
591       ...
592    }),
593    ...
594 })
595 </PRE>
596
597 <P>
598
599 <H3><A NAME="SECTION00523000000000000000">
600 <SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">3</SPAN> An example</A>
601 </H3>
602
603 <P>
604 The following shortened segment from <SPAN  CLASS="textit">look_cleanviolet.lua</SPAN>
605 should help to clarify the matters discussed in the previous
606 subsection.
607
608 <P>
609 <PRE>
610 de.defstyle("*", {
611     -- Gray background
612     highlight_colour = "#eeeeee",
613     shadow_colour = "#eeeeee",
614     background_colour = "#aaaaaa",
615     foreground_colour = "#000000",
616     
617     shadow_pixels = 1,
618     highlight_pixels = 1,
619     padding_pixels = 1,
620     spacing = 0,
621     border_style = "elevated",
622     
623     font = "-*-helvetica-medium-r-normal-*-12-*-*-*-*-*-*-*",
624     text_align = "center",
625 })
626
627 de.defstyle("tab-frame", {
628     based_on = "*",
629     
630     de.substyle("active-selected", {
631         -- Violet tab
632         highlight_colour = "#aaaacc",
633         shadow_colour = "#aaaacc",
634         background_colour = "#666699",
635         foreground_colour = "#eeeeee",
636     }),
637
638     --  More substyles would follow ...
639 })
640 </PRE>
641
642 <P>
643
644 <H2><A NAME="SECTION00530000000000000000"></A>
645 <A NAME="sec:grmisc"></A>
646 <BR>
647 <SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">3</SPAN> Miscellaneous settings
648 </H2>
649
650 <P>
651
652 <H3><A NAME="SECTION00531000000000000000">
653 <SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">1</SPAN> Frame user attributes</A>
654 </H3>
655
656 <P>
657 The function <A HREF="node7.html#fn:WFrame.set_grattr"><TT>WFrame.set_grattr</TT></A> may be used to give frames
658 (and their tabs) arbitrary extra attributes to be passed to the
659 drawing engine. Hence, by configuring such substyles in the style
660 configuration files, and turning on the attribute when needed, 
661 scripts may display visual cues related to the frame. There is
662 also one extra attribute specially interpreted by the default
663 drawing engine: the `<TT>numbered</TT>' attribute, which causes 
664 numbers to be displayed on the tabs.
665
666 <P>
667
668 <H3><A NAME="SECTION00532000000000000000">
669 <SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">2</SPAN> Extra fields for style `<TT>frame</TT>'</A>
670 </H3>
671
672 <P>
673 The following style fields are independent of the drawing engine used,
674 but are related to objects' styles and therefore configured in the drawing
675 engine configuration file.
676
677 <P>
678 <TABLE CELLPADDING=3 BORDER="1" WIDTH="100%">
679 <TR><TD ALIGN="LEFT">Field</TD>
680 <TD ALIGN="LEFT">Description</TD>
681 </TR>
682 <TR><TD ALIGN="LEFT"><TT>bar</TT></TD>
683 <TD ALIGN="LEFT">Controls the style of the tab-bar. Possible values
684         are the strings `<TT>none</TT>', `<TT>inside</TT>', `<TT>outside</TT>'
685         and `<TT>shaped</TT>', with the last providing the PWM-style
686         tab-bars for floating frames.</TD>
687 </TR>
688 <TR><TD ALIGN="LEFT"><TT>floatframe_tab_min_w</TT></TD>
689 <TD ALIGN="LEFT">Minimum tab width in pixels for
690         the shaped style, given that this number times number of tabs
691         doesn't exceed frame width.</TD>
692 </TR>
693 <TR><TD ALIGN="LEFT"><TT>floatframe_bar_max_w_q</TT></TD>
694 <TD ALIGN="LEFT">Maximum tab-bar width quotient of
695         frame width for the shaped styles. A number in the 
696         interval <SPAN CLASS="MATH"><IMG
697  WIDTH="42" HEIGHT="36" ALIGN="MIDDLE" BORDER="0"
698  SRC="img3.png"
699  ALT="$(0, 1]$"></SPAN>.</TD>
700 </TR>
701 </TABLE>
702
703 <P>
704
705 <H3><A NAME="SECTION00533000000000000000">
706 <SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN> Extra fields for style `<TT>dock</TT>'</A>
707 </H3>
708
709 <P>
710 <TABLE CELLPADDING=3 BORDER="1" WIDTH="100%">
711 <TR><TD ALIGN="LEFT">Field</TD>
712 <TD ALIGN="LEFT">Description</TD>
713 </TR>
714 <TR><TD ALIGN="LEFT"><TT>outline_style</TT></TD>
715 <TD ALIGN="LEFT">How borders are drawn:
716                         `<TT>none</TT>' - no border,
717                         `<TT>all</TT>' - border around whole dock,
718                         `<TT>each</TT>' - border around each dockapp.</TD>
719 </TR>
720 <TR><TD ALIGN="LEFT"><TT>tile_size</TT></TD>
721 <TD ALIGN="LEFT">A table with entries `<TT>width</TT>' and `<TT>height</TT>',
722         indicating the width and height of tiles in pixels.</TD>
723 </TR>
724 </TABLE>
725
726 <P>
727 Hopefully that's enough to get you started in writing new style
728 configuration files for Ion. When in doubt, study the existing
729 style configuration files.
730
731 <P>
732
733 <DIV CLASS="navigation"><HR>
734 <!--Navigation Panel-->
735 <A NAME="tex2html331"
736   HREF="node6.html">
737 <IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A> 
738 <A NAME="tex2html325"
739   HREF="ionconf.html">
740 <IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A> 
741 <A NAME="tex2html319"
742   HREF="node4.html">
743 <IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A> 
744 <A NAME="tex2html327"
745   HREF="node1.html">
746 <IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A> 
747 <A NAME="tex2html329"
748   HREF="node11.html">
749 <IMG WIDTH="43" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="index" SRC="index.png"></A> 
750 <BR>
751 <B> Next:</B> <A NAME="tex2html332"
752   HREF="node6.html">5. Scripting</A>
753 <B> Up:</B> <A NAME="tex2html326"
754   HREF="ionconf.html">Configuring and extending Ion3</A>
755 <B> Previous:</B> <A NAME="tex2html320"
756   HREF="node4.html">3. Basic configuration</A>
757  &nbsp; <B>  <A NAME="tex2html328"
758   HREF="node1.html">Contents</A></B> 
759  &nbsp; <B>  <A NAME="tex2html330"
760   HREF="node11.html">Index</A></B> </DIV>
761 <!--End of Navigation Panel-->
762
763 </BODY>
764 </HTML>