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="tex2html330"
  32   HREF="node6.html">
  33 <IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
  34 <A NAME="tex2html324"
  35   HREF="ionconf.html">
  36 <IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
  37 <A NAME="tex2html318"
  38   HREF="node4.html">
  39 <IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
  40 <A NAME="tex2html326"
  41   HREF="node1.html">
  42 <IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>
  43 <A NAME="tex2html328"
  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="tex2html331"
  48   HREF="node6.html">5. Scripting</A>
  49 <B> Up:</B> <A NAME="tex2html325"
  50   HREF="ionconf.html">Configuring and extending Ion3</A>
  51 <B> Previous:</B> <A NAME="tex2html319"
  52   HREF="node4.html">3. Basic configuration</A>
  53  &nbsp; <B>  <A NAME="tex2html327"
  54   HREF="node1.html">Contents</A></B>
  55  &nbsp; <B>  <A NAME="tex2html329"
  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="tex2html332"
  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="tex2html333"
  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="tex2html334"
  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="tex2html335"
  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="tex2html336"
  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="tex2html337"
  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="tex2html338"
  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="tex2html339"
  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="tex2html340"
  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="tex2html341"
  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="tex2html342"
  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="tex2html343"
  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="tex2html344"
  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="tex2html345"
  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="tex2html346"
 103   HREF="node5.html#SECTION00530000000000000000"><SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">3</SPAN> Miscellaneous settings</A>
 104 <UL>
 105 <LI><A NAME="tex2html347"
 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="tex2html348"
 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="tex2html349"
 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="1903"></A><A NAME="1904"></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="1916"></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>'.
 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 those of
 258         the `<TT>frame</TT>' style, as well as tab-specific
 259         `<TT>tagged</TT>'/`<TT>not_tagged</TT>',
 260         `<TT>dragged</TT>'/`<TT>not_dragged</TT>', and
 261         `<TT>activity</TT>'/`<TT>no_activity</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="2017"></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="tex2html330"
 736   HREF="node6.html">
 737 <IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
 738 <A NAME="tex2html324"
 739   HREF="ionconf.html">
 740 <IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
 741 <A NAME="tex2html318"
 742   HREF="node4.html">
 743 <IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
 744 <A NAME="tex2html326"
 745   HREF="node1.html">
 746 <IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>
 747 <A NAME="tex2html328"
 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="tex2html331"
 752   HREF="node6.html">5. Scripting</A>
 753 <B> Up:</B> <A NAME="tex2html325"
 754   HREF="ionconf.html">Configuring and extending Ion3</A>
 755 <B> Previous:</B> <A NAME="tex2html319"
 756   HREF="node4.html">3. Basic configuration</A>
 757  &nbsp; <B>  <A NAME="tex2html327"
 758   HREF="node1.html">Contents</A></B>
 759  &nbsp; <B>  <A NAME="tex2html329"
 760   HREF="node11.html">Index</A></B> </DIV>
 761 <!--End of Navigation Panel-->
 762
 763 </BODY>
 764 </HTML>