de.tex

   1
   2 \chapter{Graphical styles}
   3 \label{chap:gr}
   4
   5 This chapter first gives in section \ref{sec:engines} a general outline
   6 of how drawing engines are used, of style specifications and then
   7 in section \ref{sec:defaultde} describes how to specify styles
   8 for the default drawing engine.
   9
  10 \section{Drawing engines, style specifications and sub-styles}
  11 \label{sec:engines}
  12 \index{style}\index{drawing engine}
  13
  14 Ion's drawing routines are abstracted into so-called drawing engine
  15 modules that can, again depending on the system, be dynamically
  16 loaded as needed. The drawing engine modules provide ''brushes''
  17 that objects can use to draw some high-level primitives such
  18 as borders and text boxes (in addition to simple text and rectangle
  19 drawing) on their windows and configure e.g. the shape and
  20 background of the window. While the drawing engines therefore
  21 do not directly implement looks for each possible object (that
  22 would hardly be maintainable), different brush styles can be
  23 used to give a distinctive look to different objects and engines
  24 could interpret some styles as special cases. Style specifications
  25 are strings of the form
  26
  27 \begin{verbatim}
  28 element1-element2-...-elementn
  29 \end{verbatim}
  30
  31 An example of such a style specification is \code{tab-frame};
  32 see the table in subsection \ref{sec:styles} for more styles.
  33
  34 When an object asks for a brush of certain style, the selected
  35 drawing engine will attempt to find the closest match to this
  36 specification. The styles/brushes defined by the drawing engines
  37 may have asterisks (\verb!*!) as some of the elements indicating
  38 a match to anything. Exact matches are preferred to asterisk
  39 matches and longer matches to shorter. For example, let a brush
  40 for style \code{foo-bar-baz} be queried, then the following
  41 brushes are in order of preference:
  42
  43 \begin{verbatim}
  44 foo-bar-baz
  45 foo-*-baz
  46 foo-bar
  47 *
  48 foo-baz   -- Doesn't match, not selected!
  49 \end{verbatim}
  50
  51 Some of the drawing primitives allow extra attributes to be
  52 specified, also in the form
  53 \begin{verbatim}
  54 attr1-attr2-...-attrn
  55 \end{verbatim}
  56 These extra attributes are called \emph{substyles}\index{substyle}
  57 and allow, for example, the state of the object to be indicated
  58 by  different colour sets while keeping the interface at an
  59 abstract level and the drawing engine completely ignorant
  60 of the semantics -- only the writer of the drawing engine
  61 configuration file has to know them. However the drawing
  62 engine can again interpret known substyles as special cases
  63 and the default engine indeed does so with frame tab
  64 tag and drag states.)
  65
  66
  67 \subsection{Known styles and substyles}
  68 \label{sec:styles}
  69
  70 \subsubsection{Frames}
  71
  72 \begin{tabularx}{\linewidth}{lX}
  73 \tabhead{Style name & Description}
  74 \code{frame} & Style for frames.
  75         Substyles: \code{active}, \code{inactive}. \\
  76 \code{frame-tiled} & A more specific style for tiled frames.
  77         Substyles as for \code{frame}. \\
  78 \code{frame-tiled-alt} & An alternative style for tiled frames.
  79         Often used to disable the tab-bar. \\
  80 \code{frame-floating} & A more specific style for floating
  81         frames. \\
  82 \code{frame-transient} & A more specific style for frames
  83         containing transient windows. \\
  84 \end{tabularx}
  85
  86 \subsubsection{Tabs and menu entries}
  87
  88 \begin{tabularx}{\linewidth}{lX}
  89 \tabhead{Style name & Description}
  90 \code{tab} & Style for frames' tabs and menu entries.
  91         Substyles: combinations of the form \code{a-s} where
  92         \code{a} is one of \code{active}\nobreak/\code{inactive} and
  93         \code{s} is one of \code{selected}\nobreak/\code{unselected} \\
  94 \code{tab-frame} & A more specific style for frames' tabs.
  95         Substyles: combinations of the form \code{a-s-t-d-u} where
  96         \code{a} and \code{s} are as above and
  97         \code{t} is one of \code{tagged}\nobreak/\code{not_tagged},
  98         \code{d} is one of \code{dragged}\nobreak/\code{not_dragged} and
  99         \code{u} is one of \code{activity}\nobreak/\code{no_activity}. \\
 100 \code{tab-frame-tiled}, & \\
 101 \code{tab-frame-tiled-alt}, & \\
 102 \code{tab-frame-floating}, & \\
 103 \code{tab-frame-transient} & More specific styles for frames in the
 104         different modes. \\
 105 \code{tab-menuentry} & A more specific style for entries in \type{WMenu}s. \\
 106 \code{tab-menuentry-bigmenu} & An alternate style for entries in \type{WMenu}s. \\
 107 \end{tabularx}
 108
 109 \subsubsection{The rest}
 110
 111 \begin{tabularx}{\linewidth}{lX}
 112 \tabhead{Style name & Description}
 113 \code{input} & A style for \type{WInput}s. \\
 114 \code{input-edln} & A more specific style for \type{WEdln}s.
 115         Substyles: \code{selection} for selected text and
 116         \code{cursor} for the cursor indicating current editing point. \\
 117 \code{input-message} & A more specific style for \type{WMessage}s. \\
 118 \code{input-menu} & A more specific style for \type{WMenu}s. \\
 119 \code{input-menu-bigmenu} & An alternate style for \type{WMenu}s. \\
 120 \code{moveres_display} & The box displaying position/size when
 121         moving or resizing frames. \\
 122 \code{dock} & The dock. \\
 123 \end{tabularx}
 124
 125
 126 \section{Defining styles for the default drawing engine}
 127 \label{sec:defaultde}
 128
 129 Drawing engine style files are usually named
 130 \file{look\_foo.lua} where \file{foo} is the name of the
 131 style. The file that Ion loads on startup or when
 132 \fnref{gr.read_config} is called, however, is \file{look.lua}
 133 and should usually be symlinked to or a copy of of some
 134 \file{look\_foo.lua}.
 135
 136 \subsection{The structure of the configuration files}
 137
 138 The first thing to do in a stylefile is to choose the drawing
 139 engine, possibly loading the module as well. This is done
 140 with the following chunk of code.
 141
 142 \begin{verbatim}
 143 if not gr.select_engine("de") then
 144     return
 145 end
 146 \end{verbatim}
 147
 148 The \fnref{gr.select_engine} function sees if the engine
 149 given as argument is registered (the default drawing engine is
 150 simply called ''de''). If the engine could not be found, it
 151 tries to load a module of the same name. If the engine still
 152 is not registered, \fnref{gr.select_engine} returns \code{false}
 153 and in this case we also exit the style setup script.
 154 If the engine was found, \fnref{gr.select_engine} sees that
 155 further requests for brushes are forwarded to that engine
 156 and returns \code{true}.
 157
 158 Before defining new styles it may be a good idea to clear old
 159 styles from memory so if the old configuration defines more
 160 specific styles than the new, the old styles don't override
 161 those specified by the new configuration. That can be done by
 162 calling
 163
 164 \begin{verbatim}
 165 de.reset()
 166 \end{verbatim}
 167
 168 After this the new styles can be defined with \fnref{de.defstyle}
 169 as explained in the next subsection. Finally, after the styles have
 170 been defined we must ask objects on the screen to look up new brushes
 171 to reflect the changes in configuration. This is done with
 172
 173 \begin{verbatim}
 174 gr.refresh()
 175 \end{verbatim}
 176
 177 \subsection{Defining the styles}
 178
 179 Styles for the default drawing engine are defined with the
 180 function \fnref{de.defstyle}. It has two arguments the first being
 181 a style specification as explained in previous sections and the second
 182 a table whose fields describe the style:
 183
 184 \begin{verbatim}
 185 de.defstyle("some-style", {
 186     attribute = value,
 187     ...
 188 })
 189 \end{verbatim}
 190
 191 The supported attributes are described in tables below. The different
 192 border elements and styles referred to there are explained in Figure
 193 \ref{fig:borders}.
 194
 195 \begin{figure}
 196 \begin{htmlonly}
 197 \docode % Kludge to make latex2html interpret contents instead of
 198         % creating an image.
 199 \end{htmlonly}
 200 \begin{verbatim}
 201 Elevated:        Inlaid:         Ridge:            Groove:
 202   hhhhhhhhhhhs     ............    hhhhhhhhhhhs      sssssssssssh
 203   h..........s     .sssssssssh.    h..........s      s..........h
 204   h.        .s     .s        h.    h.sssssssh.s      s.hhhhhhhs.h
 205   h.        .s     .s        h.    h.s      h.s      s.h      s.h
 206   h.        .s     .s        h.    h.shhhhhhh.s      s.hsssssss.h
 207   h..........s     .shhhhhhhhh.    h..........s      s..........h
 208   hsssssssssss     ............    hsssssssssss      shhhhhhhhhhh
 209
 210 h = highlight, s = shadow, . = padding
 211 \end{verbatim}
 212 \caption{Sketch of different border styles and elements}
 213 \label{fig:borders}
 214 \end{figure}
 215
 216 \subsubsection{Colours}
 217
 218 Each of these fields a string of the form that can be
 219 passed to \code{XAllocNamedColor}. Valid strings are e.g.
 220 hexadecimal RGB specifications of the form
 221 \code{#RRGGBB} and colour names as specified
 222 in \file{/usr/X11R6/lib/X11/rgb.txt} (exact path varying).
 223
 224 \begin{tabularx}{\linewidth}{lX}
 225 \tabhead{Field  & Description}
 226 \var{highlight_colour} &
 227         Colour for the ''highlight'' part of a border. \\
 228 \var{shadow_colour}    &
 229         Colour for the ''highlight'' part of a border. \\
 230 \var{foreground_colour} &
 231         Colour for the normal drawing operations, e.g. text. \\
 232 \var{background_colour} &
 233         Window background colour (unless transparency is enabled) and
 234         background colour boxes. \\
 235 \var{padding_colour} &
 236         Colour for the ''padding'' part of a border border. Set to
 237         \var{background_colour} if unset. \\
 238 \end{tabularx}
 239
 240
 241 \subsubsection{Borders and widths}
 242
 243 All other fields below except \var{border_style} are non-negative integers
 244 indicating a number of pixels.
 245
 246 \begin{tabularx}{\linewidth}{lX}
 247 \tabhead{Field  & Description}
 248 \var{border_style} & A string indicating the style of border; one of
 249                      elevated/inlaid/ridge/groove as seen in the
 250                      above sketch. \\
 251 \var{highlight_pixels} &
 252         Width of the highlight part of the border in pixels. \\
 253 \var{shadow_pixels}    &
 254         Width of the shadow part of the border in pixels. \\
 255 \var{padding_pixels} &
 256         Width of the padding part of the border in pixels. \\
 257 \var{spacing} &
 258         Space to be left between all kinds of boxes. \\
 259 \end{tabularx}
 260
 261
 262 \subsubsection{Text}
 263
 264 \begin{tabularx}{\linewidth}{lX}
 265 \tabhead{Field  & Description}
 266 \var{font} & Font to be used in text-drawing operations; standard X font
 267              name. \\
 268 \var{text_align} & How text is to be aligned in text boxes/tabs; one of
 269                    the strings left\nobreak/right\nobreak/center. \\
 270 \end{tabularx}
 271
 272
 273 \subsubsection{Miscellaneous}
 274
 275
 276 \begin{tabularx}{\linewidth}{lX}
 277 \tabhead{Field  & Description}
 278 \var{transparent_background} & Should windows' that use this style
 279         background be transparent? true/false. \\
 280 \var{based_on} & The name of a previously defined style that this
 281         style should be based on. \\
 282 \end{tabularx}
 283
 284
 285 \subsubsection{Substyles}
 286
 287 As discussed in previous sections, styles may have substyles to e.g.
 288 indicate different states of the object being drawn. The ''de'' engine
 289 limits what can be configured in substyles to the set of colours in the
 290 first table above, but also specifically interprets for the main style
 291 \code{tab-frame} the substyles \code{*-*-tagged} and \code{*-*-*-dragged}
 292 by, respectively, drawing a right angle shape at the top right corner
 293 of a tab and by shading the tab with a stipple pattern. Also for
 294 menus the substyles \code{*-*-submenu} are handled as a special case.
 295
 296 Substyles are defined with the function \fnref{de.substyle} within the
 297 table defining the main style. The parameters to this function are
 298 similar to those of \fnref{de.defstyle}.
 299
 300 \begin{verbatim}
 301 de.defstyle("some-style", {
 302    ...
 303    de.substyle("some-substyle", {
 304       ...
 305    }),
 306    ...
 307 })
 308 \end{verbatim}
 309
 310
 311 \subsection{An example}
 312
 313 The following shortened segment from \file{look\_cleanviolet.lua}
 314 should help to clarify the matters discussed in the previous
 315 subsection.
 316
 317 \begin{verbatim}
 318 de.defstyle("*", {
 319     -- Gray background
 320     highlight_colour = "#eeeeee",
 321     shadow_colour = "#eeeeee",
 322     background_colour = "#aaaaaa",
 323     foreground_colour = "#000000",
 324
 325     shadow_pixels = 1,
 326     highlight_pixels = 1,
 327     padding_pixels = 1,
 328     spacing = 0,
 329     border_style = "elevated",
 330
 331     font = "-*-helvetica-medium-r-normal-*-12-*-*-*-*-*-*-*",
 332     text_align = "center",
 333 })
 334
 335 de.defstyle("tab-frame", {
 336     based_on = "*",
 337
 338     de.substyle("active-selected", {
 339         -- Violet tab
 340         highlight_colour = "#aaaacc",
 341         shadow_colour = "#aaaacc",
 342         background_colour = "#666699",
 343         foreground_colour = "#eeeeee",
 344     }),
 345
 346     --  More substyles would follow ...
 347 })
 348 \end{verbatim}
 349
 350
 351 \section{Miscellaneous settings}
 352
 353 The following style fields are independent of the drawing engine used,
 354 but are related to objects' styles and therefore configured in the drawing
 355 engine configuration file.
 356
 357 \subsection{Extra fields for style \code{frame}}
 358
 359 \begin{tabularx}{\linewidth}{lX}
 360 \tabhead{Field  & Description}
 361 \code{bar} & Controls the style of the tab-bar. Possible values
 362         are the strings \code{"none"}, \code{"inside"}, \code{"outside"}
 363         and \code{"shaped"}, with the last providing the PWM-style
 364         tab-bars for floating frames. \\
 365 \code{floatframe_tab_min_w} & Minimum tab width in pixels for
 366         the shaped style, given that this number times number of tabs
 367         doesn't exceed frame width. \\
 368 \code{floatframe_bar_max_w_q} & Maximum tab-bar width quotient of
 369         frame width for the shaped styles. A number in the
 370         interval $(0, 1]$.
 371 \end{tabularx}
 372
 373 \subsection{Extra fields for style \code{dock}}
 374
 375 \begin{tabularx}{\linewidth}{lX}
 376 \tabhead{Field  & Description}
 377 \code{outline_style} & How borders are drawn:
 378                         \code{"none"} -- no border,
 379                         \code{"all"} -- border around whole dock,
 380                         \code{"each"} -- border around each dockapp. \\
 381 \code{tile_size} & A table with entries \code{width} and \code{height},
 382         indicating the width and height of tiles in pixels.
 383 \end{tabularx}
 384
 385
 386 Hopefully that's enough to get you started in writing new style
 387 configuration files for Ion. When in doubt, study the existing
 388 style configuration files.