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="1906"></A><A NAME="1907"></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="1919"></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 <TR><TD ALIGN="LEFT">`<TT>tab-info</TT>'</TD>
 285 <TD ALIGN="LEFT">Extra information tab (displayed e.g. for tagged workspaces).</TD>
 286 </TR>
 287 </TABLE>
 288
 289 <P>
 290
 291 <H4><A NAME="SECTION00511300000000000000">
 292 <SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">1</SPAN>.<SPAN CLASS="arabic">1</SPAN>.<SPAN CLASS="arabic">3</SPAN> The rest</A>
 293 </H4>
 294
 295 <P>
 296 <TABLE CELLPADDING=3 BORDER="1" WIDTH="100%">
 297 <TR><TD ALIGN="LEFT">Style name</TD>
 298 <TD ALIGN="LEFT">Description</TD>
 299 </TR>
 300 <TR><TD ALIGN="LEFT">`<TT>input</TT>'</TD>
 301 <TD ALIGN="LEFT">A style for WInputs.</TD>
 302 </TR>
 303 <TR><TD ALIGN="LEFT">`<TT>input-edln</TT>'</TD>
 304 <TD ALIGN="LEFT">A more specific style for WEdlns.
 305         Substyle attributes: `<TT>selection</TT>' for selected text and
 306         `<TT>cursor</TT>' for the cursor indicating current editing point.</TD>
 307 </TR>
 308 <TR><TD ALIGN="LEFT">`<TT>input-message</TT>'</TD>
 309 <TD ALIGN="LEFT">A more specific style for WMessages.</TD>
 310 </TR>
 311 <TR><TD ALIGN="LEFT">`<TT>input-menu</TT>'</TD>
 312 <TD ALIGN="LEFT">A more specific style for WMenus.</TD>
 313 </TR>
 314 <TR><TD ALIGN="LEFT">`<TT>input-menu-bigmenu</TT>'</TD>
 315 <TD ALIGN="LEFT">An alternate style for WMenus.</TD>
 316 </TR>
 317 <TR><TD ALIGN="LEFT">`<TT>moveres_display</TT>'</TD>
 318 <TD ALIGN="LEFT">The box displaying position/size when
 319         moving or resizing frames.</TD>
 320 </TR>
 321 <TR><TD ALIGN="LEFT">`<TT>actnotify</TT>'</TD>
 322 <TD ALIGN="LEFT">Actification notification box.</TD>
 323 </TR>
 324 <TR><TD ALIGN="LEFT">`<TT>stdisp</TT>'</TD>
 325 <TD ALIGN="LEFT">Any status display.</TD>
 326 </TR>
 327 <TR><TD ALIGN="LEFT">`<TT>stdisp-dock</TT>'</TD>
 328 <TD ALIGN="LEFT">The dock.</TD>
 329 </TR>
 330 <TR><TD ALIGN="LEFT">`<TT>stdisp-statusbar</TT>'</TD>
 331 <TD ALIGN="LEFT">The statusbar. Substyles include:
 332     the name of any monitor/meter (such as `<TT>date</TT>'), and
 333     the supplied hint. Typical hints are: `<TT>normal</TT>',
 334     `<TT>important</TT>', and `<TT>critical</TT>'.</TD>
 335 </TR>
 336 </TABLE>
 337
 338 <P>
 339
 340 <H2><A NAME="SECTION00520000000000000000"></A>
 341 <A NAME="sec:defaultde"></A>
 342 <BR>
 343 <SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">2</SPAN> Defining styles for the default drawing engine
 344 </H2>
 345
 346 <P>
 347 Drawing engine style files are usually named
 348 <SPAN  CLASS="textit">look_foo.lua</SPAN> where <SPAN  CLASS="textit">foo</SPAN> is the name of the
 349 style. The file that Ion loads on startup or when
 350 <A HREF="node7.html#fn:gr.read_config"><TT>gr.read_config</TT></A> is called, however, is <SPAN  CLASS="textit">look.lua</SPAN>
 351 and should usually be symlinked to or a copy of of some
 352 <SPAN  CLASS="textit">look_foo.lua</SPAN>.
 353
 354 <P>
 355
 356 <H3><A NAME="SECTION00521000000000000000">
 357 <SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">1</SPAN> The structure of the configuration files</A>
 358 </H3>
 359
 360 <P>
 361 The first thing to do in a style file is to choose the drawing
 362 engine, possibly loading the module as well. This is done
 363 with the following chunk of code.
 364
 365 <P>
 366 <PRE>
 367 if not gr.select_engine("de") then
 368     return
 369 end
 370 </PRE>
 371
 372 <P>
 373 The <A HREF="node7.html#fn:gr.select_engine"><TT>gr.select_engine</TT></A> function sees if the engine
 374 given as argument is registered (the default drawing engine is
 375 simply called ``de''). If the engine could not be found, it
 376 tries to load a module of the same name. If the engine still
 377 is not registered, <A HREF="node7.html#fn:gr.select_engine"><TT>gr.select_engine</TT></A> returns `<TT>false</TT>'
 378 and in this case we also exit the style setup script.
 379 If the engine was found, <A HREF="node7.html#fn:gr.select_engine"><TT>gr.select_engine</TT></A> sees that
 380 further requests for brushes are forwarded to that engine
 381 and returns `<TT>true</TT>'.
 382
 383 <P>
 384 Before defining new styles it may be a good idea to clear old
 385 styles from memory so if the old configuration defines more
 386 specific styles than the new, the old styles don't override
 387 those specified by the new configuration. That can be done by
 388 calling
 389
 390 <P>
 391 <PRE>
 392 de.reset()
 393 </PRE>
 394
 395 <P>
 396 After this the new styles can be defined with <A HREF="node7.html#fn:de.defstyle"><TT>de.defstyle</TT></A>
 397 as explained in the next subsection. Finally, after the styles have
 398 been defined we must ask objects on the screen to look up new brushes
 399 to reflect the changes in configuration. This is done with
 400
 401 <P>
 402 <PRE>
 403 gr.refresh()
 404 </PRE>
 405
 406 <P>
 407
 408 <H3><A NAME="SECTION00522000000000000000">
 409 <SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">2</SPAN> Defining the styles</A>
 410 </H3>
 411
 412 <P>
 413 Styles for the default drawing engine are defined with the
 414 function <A HREF="node7.html#fn:de.defstyle"><TT>de.defstyle</TT></A>. It has two arguments the first being
 415 a style specification as explained in previous sections and the second
 416 a table whose fields describe the style:
 417
 418 <P>
 419 <PRE>
 420 de.defstyle("some-style", {
 421     attribute = value,
 422     ...
 423 })
 424 </PRE>
 425
 426 <P>
 427 The supported attributes are described in tables below. The different
 428 border elements and styles referred to there are explained in Figure
 429 <A HREF="#fig:borders">4.1</A>.
 430
 431 <P>
 432
 433 <DIV ALIGN="CENTER"><A NAME="fig:borders"></A><A NAME="2022"></A>
 434 <TABLE>
 435 <CAPTION ALIGN="BOTTOM"><STRONG>Figure 4.1:</STRONG>
 436 Sketch of different border styles and elements</CAPTION>
 437 <TR><TD><PRE>
 438 Elevated:        Inlaid:         Ridge:            Groove:
 439   hhhhhhhhhhhs     ............    hhhhhhhhhhhs      sssssssssssh
 440   h..........s     .sssssssssh.    h..........s      s..........h
 441   h.        .s     .s        h.    h.sssssssh.s      s.hhhhhhhs.h
 442   h.        .s     .s        h.    h.s      h.s      s.h      s.h
 443   h.        .s     .s        h.    h.shhhhhhh.s      s.hsssssss.h
 444   h..........s     .shhhhhhhhh.    h..........s      s..........h
 445   hsssssssssss     ............    hsssssssssss      shhhhhhhhhhh
 446
 447 h = highlight, s = shadow, . = padding
 448 </PRE></TD></TR>
 449 </TABLE>
 450 </DIV>
 451
 452 <P>
 453
 454 <H4><A NAME="SECTION00522100000000000000">
 455 <SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">1</SPAN> Colours</A>
 456 </H4>
 457
 458 <P>
 459 Each of these fields a string of the form that can be
 460 passed to <TT>XAllocNamedColor</TT>. Valid strings are e.g.
 461 hexadecimal RGB specifications of the form
 462 <TT>#RRGGBB</TT> and colour names as specified
 463 in <SPAN  CLASS="textit">/usr/X11R6/lib/X11/rgb.txt</SPAN> (exact path varying).
 464
 465 <P>
 466 <TABLE CELLPADDING=3 BORDER="1" WIDTH="100%">
 467 <TR><TD ALIGN="LEFT">Field</TD>
 468 <TD ALIGN="LEFT">Description</TD>
 469 </TR>
 470 <TR><TD ALIGN="LEFT"><TT>highlight_colour</TT></TD>
 471 <TD ALIGN="LEFT">Colour for the ``highlight'' part of a border.</TD>
 472 </TR>
 473 <TR><TD ALIGN="LEFT"><TT>shadow_colour</TT></TD>
 474 <TD ALIGN="LEFT">Colour for the ``shadow'' part of a border.</TD>
 475 </TR>
 476 <TR><TD ALIGN="LEFT"><TT>foreground_colour</TT></TD>
 477 <TD ALIGN="LEFT">Colour for the normal drawing operations, e.g. text.</TD>
 478 </TR>
 479 <TR><TD ALIGN="LEFT"><TT>background_colour</TT></TD>
 480 <TD ALIGN="LEFT">Window background colour (unless transparency is enabled) and
 481         background colour boxes.</TD>
 482 </TR>
 483 <TR><TD ALIGN="LEFT"><TT>padding_colour</TT></TD>
 484 <TD ALIGN="LEFT">Colour for the ``padding'' part of a border border. Set to
 485         <TT>background_colour</TT> if unset.</TD>
 486 </TR>
 487 </TABLE>
 488
 489 <P>
 490
 491 <H4><A NAME="SECTION00522200000000000000">
 492 <SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">2</SPAN> Borders and widths</A>
 493 </H4>
 494
 495 <P>
 496 All other fields below except <TT>border_style</TT> are non-negative integers
 497 indicating a number of pixels.
 498
 499 <P>
 500 <TABLE CELLPADDING=3 BORDER="1" WIDTH="100%">
 501 <TR><TD ALIGN="LEFT">Field</TD>
 502 <TD ALIGN="LEFT">Description</TD>
 503 </TR>
 504 <TR><TD ALIGN="LEFT"><TT>border_style</TT></TD>
 505 <TD ALIGN="LEFT">A string indicating the style of border; one of
 506                      `<TT>elevated</TT>'/`<TT>inlaid</TT>'/`<TT>ridge</TT>'/`<TT>groove</TT>'
 507                      as seen in the above sketch.</TD>
 508 </TR>
 509 <TR><TD ALIGN="LEFT"><TT>border_sides</TT></TD>
 510 <TD ALIGN="LEFT">A string indicating which sides of the border
 511                      to draw: `<TT>all</TT>'/`<TT>tb</TT>'/`<TT>lr</TT>' for all,
 512                      top and bottom, and left and right. To control between
 513                      left/right and top/bottom, use the pixel options below.</TD>
 514 </TR>
 515 <TR><TD ALIGN="LEFT"><TT>highlight_pixels</TT></TD>
 516 <TD ALIGN="LEFT">Width of the highlight part of the border in pixels.</TD>
 517 </TR>
 518 <TR><TD ALIGN="LEFT"><TT>shadow_pixels</TT></TD>
 519 <TD ALIGN="LEFT">Width of the shadow part of the border in pixels.</TD>
 520 </TR>
 521 <TR><TD ALIGN="LEFT"><TT>padding_pixels</TT></TD>
 522 <TD ALIGN="LEFT">Width of the padding part of the border in pixels.</TD>
 523 </TR>
 524 <TR><TD ALIGN="LEFT"><TT>spacing</TT></TD>
 525 <TD ALIGN="LEFT">Space to be left between all kinds of boxes.</TD>
 526 </TR>
 527 </TABLE>
 528
 529 <P>
 530
 531 <H4><A NAME="SECTION00522300000000000000">
 532 <SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">3</SPAN> Text</A>
 533 </H4>
 534
 535 <P>
 536 <TABLE CELLPADDING=3 BORDER="1" WIDTH="100%">
 537 <TR><TD ALIGN="LEFT">Field</TD>
 538 <TD ALIGN="LEFT">Description</TD>
 539 </TR>
 540 <TR><TD ALIGN="LEFT"><TT>font</TT></TD>
 541 <TD ALIGN="LEFT">Font to be used in text-drawing operations; standard X font
 542              name.</TD>
 543 </TR>
 544 <TR><TD ALIGN="LEFT"><TT>text_align</TT></TD>
 545 <TD ALIGN="LEFT">How text is to be aligned in text boxes/tabs; one of
 546                    the strings `<TT>left</TT>'/`<TT>right</TT>'/`<TT>center</TT>'.</TD>
 547 </TR>
 548 </TABLE>
 549
 550 <P>
 551
 552 <H4><A NAME="SECTION00522400000000000000">
 553 <SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">4</SPAN> Miscellaneous</A>
 554 </H4>
 555
 556 <P>
 557 <TABLE CELLPADDING=3 BORDER="1" WIDTH="100%">
 558 <TR><TD ALIGN="LEFT">Field</TD>
 559 <TD ALIGN="LEFT">Description</TD>
 560 </TR>
 561 <TR><TD ALIGN="LEFT"><TT>transparent_background</TT></TD>
 562 <TD ALIGN="LEFT">Should windows' that use this style
 563         background be transparent? true/false.</TD>
 564 </TR>
 565 <TR><TD ALIGN="LEFT"><TT>based_on</TT></TD>
 566 <TD ALIGN="LEFT">The name of a previously defined style that this
 567         style should be based on.</TD>
 568 </TR>
 569 </TABLE>
 570
 571 <P>
 572
 573 <H4><A NAME="SECTION00522500000000000000">
 574 <SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">5</SPAN> Substyles</A>
 575 </H4>
 576
 577 <P>
 578 As discussed in previous sections, styles may have substyles to e.g.
 579 indicate different states of the object being drawn. The ``de'' engine
 580 limits what can be configured in substyles to the set of colours in the
 581 first table above, but also specifically interprets for the main style
 582 `<TT>tab-frame</TT>' the substyles `<TT>*-*-tagged</TT>' and `<TT>*-*-*-dragged</TT>'
 583 by, respectively, drawing a right angle shape at the top right corner
 584 of a tab and by shading the tab with a stipple pattern. Also for
 585 menus the substyles `<TT>*-*-submenu</TT>' are handled as a special case.
 586
 587 <P>
 588 Substyles are defined with the function <A HREF="node7.html#fn:de.substyle"><TT>de.substyle</TT></A> within the
 589 table defining the main style. The parameters to this function are
 590 similar to those of <A HREF="node7.html#fn:de.defstyle"><TT>de.defstyle</TT></A>.
 591
 592 <P>
 593 <PRE>
 594 de.defstyle("some-style", {
 595    ...
 596    de.substyle("some-substyle", {
 597       ...
 598    }),
 599    ...
 600 })
 601 </PRE>
 602
 603 <P>
 604
 605 <H3><A NAME="SECTION00523000000000000000">
 606 <SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">2</SPAN>.<SPAN CLASS="arabic">3</SPAN> An example</A>
 607 </H3>
 608
 609 <P>
 610 The following shortened segment from <SPAN  CLASS="textit">look_cleanviolet.lua</SPAN>
 611 should help to clarify the matters discussed in the previous
 612 subsection.
 613
 614 <P>
 615 <PRE>
 616 de.defstyle("*", {
 617     -- Gray background
 618     highlight_colour = "#eeeeee",
 619     shadow_colour = "#eeeeee",
 620     background_colour = "#aaaaaa",
 621     foreground_colour = "#000000",
 622
 623     shadow_pixels = 1,
 624     highlight_pixels = 1,
 625     padding_pixels = 1,
 626     spacing = 0,
 627     border_style = "elevated",
 628
 629     font = "-*-helvetica-medium-r-normal-*-12-*-*-*-*-*-*-*",
 630     text_align = "center",
 631 })
 632
 633 de.defstyle("tab-frame", {
 634     based_on = "*",
 635
 636     de.substyle("active-selected", {
 637         -- Violet tab
 638         highlight_colour = "#aaaacc",
 639         shadow_colour = "#aaaacc",
 640         background_colour = "#666699",
 641         foreground_colour = "#eeeeee",
 642     }),
 643
 644     --  More substyles would follow ...
 645 })
 646 </PRE>
 647
 648 <P>
 649
 650 <H2><A NAME="SECTION00530000000000000000"></A>
 651 <A NAME="sec:grmisc"></A>
 652 <BR>
 653 <SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">3</SPAN> Miscellaneous settings
 654 </H2>
 655
 656 <P>
 657
 658 <H3><A NAME="SECTION00531000000000000000">
 659 <SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">1</SPAN> Frame user attributes</A>
 660 </H3>
 661
 662 <P>
 663 The function <A HREF="node7.html#fn:WFrame.set_grattr"><TT>WFrame.set_grattr</TT></A> may be used to give frames
 664 (and their tabs) arbitrary extra attributes to be passed to the
 665 drawing engine. Hence, by configuring such substyles in the style
 666 configuration files, and turning on the attribute when needed,
 667 scripts may display visual cues related to the frame. There is
 668 also one extra attribute specially interpreted by the default
 669 drawing engine: the `<TT>numbered</TT>' attribute, which causes
 670 numbers to be displayed on the tabs.
 671
 672 <P>
 673
 674 <H3><A NAME="SECTION00532000000000000000">
 675 <SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">2</SPAN> Extra fields for style `<TT>frame</TT>'</A>
 676 </H3>
 677
 678 <P>
 679 The following style fields are independent of the drawing engine used,
 680 but are related to objects' styles and therefore configured in the drawing
 681 engine configuration file.
 682
 683 <P>
 684 <TABLE CELLPADDING=3 BORDER="1" WIDTH="100%">
 685 <TR><TD ALIGN="LEFT">Field</TD>
 686 <TD ALIGN="LEFT">Description</TD>
 687 </TR>
 688 <TR><TD ALIGN="LEFT"><TT>bar</TT></TD>
 689 <TD ALIGN="LEFT">Controls the style of the tab-bar. Possible values
 690         are the strings `<TT>none</TT>', `<TT>inside</TT>', `<TT>outside</TT>'
 691         and `<TT>shaped</TT>', with the last providing the PWM-style
 692         tab-bars for floating frames.</TD>
 693 </TR>
 694 <TR><TD ALIGN="LEFT"><TT>floatframe_tab_min_w</TT></TD>
 695 <TD ALIGN="LEFT">Minimum tab width in pixels for
 696         the shaped style, given that this number times number of tabs
 697         doesn't exceed frame width.</TD>
 698 </TR>
 699 <TR><TD ALIGN="LEFT"><TT>floatframe_bar_max_w_q</TT></TD>
 700 <TD ALIGN="LEFT">Maximum tab-bar width quotient of
 701         frame width for the shaped styles. A number in the
 702         interval <SPAN CLASS="MATH"><IMG
 703  WIDTH="41" HEIGHT="36" ALIGN="MIDDLE" BORDER="0"
 704  SRC="img3.png"
 705  ALT="$(0, 1]$"></SPAN>.</TD>
 706 </TR>
 707 </TABLE>
 708
 709 <P>
 710
 711 <H3><A NAME="SECTION00533000000000000000">
 712 <SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">3</SPAN>.<SPAN CLASS="arabic">3</SPAN> Extra fields for style `<TT>dock</TT>'</A>
 713 </H3>
 714
 715 <P>
 716 <TABLE CELLPADDING=3 BORDER="1" WIDTH="100%">
 717 <TR><TD ALIGN="LEFT">Field</TD>
 718 <TD ALIGN="LEFT">Description</TD>
 719 </TR>
 720 <TR><TD ALIGN="LEFT"><TT>outline_style</TT></TD>
 721 <TD ALIGN="LEFT">How borders are drawn:
 722                         `<TT>none</TT>' - no border,
 723                         `<TT>all</TT>' - border around whole dock,
 724                         `<TT>each</TT>' - border around each dockapp.</TD>
 725 </TR>
 726 <TR><TD ALIGN="LEFT"><TT>tile_size</TT></TD>
 727 <TD ALIGN="LEFT">A table with entries `<TT>width</TT>' and `<TT>height</TT>',
 728         indicating the width and height of tiles in pixels.</TD>
 729 </TR>
 730 </TABLE>
 731
 732 <P>
 733 Hopefully that's enough to get you started in writing new style
 734 configuration files for Ion. When in doubt, study the existing
 735 style configuration files.
 736
 737 <P>
 738
 739 <DIV CLASS="navigation"><HR>
 740 <!--Navigation Panel-->
 741 <A NAME="tex2html330"
 742   HREF="node6.html">
 743 <IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
 744 <A NAME="tex2html324"
 745   HREF="ionconf.html">
 746 <IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
 747 <A NAME="tex2html318"
 748   HREF="node4.html">
 749 <IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
 750 <A NAME="tex2html326"
 751   HREF="node1.html">
 752 <IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>
 753 <A NAME="tex2html328"
 754   HREF="node11.html">
 755 <IMG WIDTH="43" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="index" SRC="index.png"></A>
 756 <BR>
 757 <B> Next:</B> <A NAME="tex2html331"
 758   HREF="node6.html">5. Scripting</A>
 759 <B> Up:</B> <A NAME="tex2html325"
 760   HREF="ionconf.html">Configuring and extending Ion3</A>
 761 <B> Previous:</B> <A NAME="tex2html319"
 762   HREF="node4.html">3. Basic configuration</A>
 763  &nbsp; <B>  <A NAME="tex2html327"
 764   HREF="node1.html">Contents</A></B>
 765  &nbsp; <B>  <A NAME="tex2html329"
 766   HREF="node11.html">Index</A></B> </DIV>
 767 <!--End of Navigation Panel-->
 768
 769 </BODY>
 770 </HTML>