de.tex

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