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 \codestr{tab-info} &
 116         Extra information tab (displayed e.g. for tagged workspaces). \\
 117 \end{tabularx}
 118
 119 \subsubsection{The rest}
 120
 121 \begin{tabularx}{\linewidth}{lX}
 122 \tabhead{Style name & Description}
 123 \codestr{input} & A style for \type{WInput}s. \\
 124 \codestr{input-edln} & A more specific style for \type{WEdln}s.
 125         Substyle attributes: \codestr{selection} for selected text and
 126         \codestr{cursor} for the cursor indicating current editing point. \\
 127 \codestr{input-message} & A more specific style for \type{WMessage}s. \\
 128 \codestr{input-menu} & A more specific style for \type{WMenu}s. \\
 129 \codestr{input-menu-bigmenu} & An alternate style for \type{WMenu}s. \\
 130 \codestr{moveres\_display} & The box displaying position/size when
 131         moving or resizing frames. \\
 132 \codestr{actnotify} & Actification notification box. \\
 133 \codestr{stdisp} & Any status display. \\
 134 \codestr{stdisp-dock} & The dock. \\
 135 \codestr{stdisp-statusbar} & The statusbar. Substyles include:
 136     the name of any monitor/meter (such as \codestr{date}), and
 137     the supplied hint. Typical hints are: \codestr{normal},
 138     \codestr{important}, and \codestr{critical}. \\
 139 \end{tabularx}
 140
 141
 142 \section{Defining styles for the default drawing engine}
 143 \label{sec:defaultde}
 144
 145 Drawing engine style files are usually named
 146 \file{look\_foo.lua} where \file{foo} is the name of the
 147 style. The file that Ion loads on startup or when
 148 \fnref{gr.read_config} is called, however, is \file{look.lua}
 149 and should usually be symlinked to or a copy of of some
 150 \file{look\_foo.lua}.
 151
 152 \subsection{The structure of the configuration files}
 153
 154 The first thing to do in a style file is to choose the drawing
 155 engine, possibly loading the module as well. This is done
 156 with the following chunk of code.
 157
 158 \begin{verbatim}
 159 if not gr.select_engine("de") then
 160     return
 161 end
 162 \end{verbatim}
 163
 164 The \fnref{gr.select_engine} function sees if the engine
 165 given as argument is registered (the default drawing engine is
 166 simply called ``de''). If the engine could not be found, it
 167 tries to load a module of the same name. If the engine still
 168 is not registered, \fnref{gr.select_engine} returns \codestr{false}
 169 and in this case we also exit the style setup script.
 170 If the engine was found, \fnref{gr.select_engine} sees that
 171 further requests for brushes are forwarded to that engine
 172 and returns \codestr{true}.
 173
 174 Before defining new styles it may be a good idea to clear old
 175 styles from memory so if the old configuration defines more
 176 specific styles than the new, the old styles don't override
 177 those specified by the new configuration. That can be done by
 178 calling
 179
 180 \begin{verbatim}
 181 de.reset()
 182 \end{verbatim}
 183
 184 After this the new styles can be defined with \fnref{de.defstyle}
 185 as explained in the next subsection. Finally, after the styles have
 186 been defined we must ask objects on the screen to look up new brushes
 187 to reflect the changes in configuration. This is done with
 188
 189 \begin{verbatim}
 190 gr.refresh()
 191 \end{verbatim}
 192
 193 \subsection{Defining the styles}
 194
 195 Styles for the default drawing engine are defined with the
 196 function \fnref{de.defstyle}. It has two arguments the first being
 197 a style specification as explained in previous sections and the second
 198 a table whose fields describe the style:
 199
 200 \begin{verbatim}
 201 de.defstyle("some-style", {
 202     attribute = value,
 203     ...
 204 })
 205 \end{verbatim}
 206
 207 The supported attributes are described in tables below. The different
 208 border elements and styles referred to there are explained in Figure
 209 \ref{fig:borders}.
 210
 211 \begin{figure}
 212 \begin{htmlonly}
 213 \docode % Kludge to make latex2html interpret contents instead of
 214         % creating an image.
 215 \end{htmlonly}
 216 \begin{verbatim}
 217 Elevated:        Inlaid:         Ridge:            Groove:
 218   hhhhhhhhhhhs     ............    hhhhhhhhhhhs      sssssssssssh
 219   h..........s     .sssssssssh.    h..........s      s..........h
 220   h.        .s     .s        h.    h.sssssssh.s      s.hhhhhhhs.h
 221   h.        .s     .s        h.    h.s      h.s      s.h      s.h
 222   h.        .s     .s        h.    h.shhhhhhh.s      s.hsssssss.h
 223   h..........s     .shhhhhhhhh.    h..........s      s..........h
 224   hsssssssssss     ............    hsssssssssss      shhhhhhhhhhh
 225
 226 h = highlight, s = shadow, . = padding
 227 \end{verbatim}
 228 \caption{Sketch of different border styles and elements}
 229 \label{fig:borders}
 230 \end{figure}
 231
 232 \subsubsection{Colours}
 233
 234 Each of these fields a string of the form that can be
 235 passed to \code{XAllocNamedColor}. Valid strings are e.g.
 236 hexadecimal RGB specifications of the form
 237 \code{#RRGGBB} and colour names as specified
 238 in \file{/usr/X11R6/lib/X11/rgb.txt} (exact path varying).
 239
 240 \begin{tabularx}{\linewidth}{lX}
 241 \tabhead{Field  & Description}
 242 \var{highlight_colour} &
 243         Colour for the ``highlight'' part of a border. \\
 244 \var{shadow_colour}    &
 245         Colour for the ``shadow'' part of a border. \\
 246 \var{foreground_colour} &
 247         Colour for the normal drawing operations, e.g. text. \\
 248 \var{background_colour} &
 249         Window background colour (unless transparency is enabled) and
 250         background colour boxes. \\
 251 \var{padding_colour} &
 252         Colour for the ``padding'' part of a border border. Set to
 253         \var{background_colour} if unset. \\
 254 \end{tabularx}
 255
 256
 257 \subsubsection{Borders and widths}
 258
 259 All other fields below except \var{border_style} are non-negative integers
 260 indicating a number of pixels.
 261
 262 \begin{tabularx}{\linewidth}{lX}
 263 \tabhead{Field  & Description}
 264 \var{border_style} & A string indicating the style of border; one of
 265                      \codestr{elevated}/\codestr{inlaid}/\codestr{ridge}/\codestr{groove}
 266                      as seen in the above sketch. \\
 267 \var{border_sides} & A string indicating which sides of the border
 268                      to draw: \codestr{all}/\codestr{tb}/\codestr{lr} for all,
 269                      top and bottom, and left and right. To control between
 270                      left/right and top/bottom, use the pixel options below. \\
 271 \var{highlight_pixels} &
 272         Width of the highlight part of the border in pixels. \\
 273 \var{shadow_pixels}    &
 274         Width of the shadow part of the border in pixels. \\
 275 \var{padding_pixels} &
 276         Width of the padding part of the border in pixels. \\
 277 \var{spacing} &
 278         Space to be left between all kinds of boxes. \\
 279 \end{tabularx}
 280
 281
 282 \subsubsection{Text}
 283
 284 \begin{tabularx}{\linewidth}{lX}
 285 \tabhead{Field  & Description}
 286 \var{font} & Font to be used in text-drawing operations; standard X font
 287              name. \\
 288 \var{text_align} & How text is to be aligned in text boxes/tabs; one of
 289                    the strings \codestr{left}/\codestr{right}/\codestr{center}. \\
 290 \end{tabularx}
 291
 292
 293 \subsubsection{Miscellaneous}
 294
 295
 296 \begin{tabularx}{\linewidth}{lX}
 297 \tabhead{Field  & Description}
 298 \var{transparent_background} & Should windows' that use this style
 299         background be transparent? true/false. \\
 300 \var{based_on} & The name of a previously defined style that this
 301         style should be based on. \\
 302 \end{tabularx}
 303
 304
 305 \subsubsection{Substyles}
 306
 307 As discussed in previous sections, styles may have substyles to e.g.
 308 indicate different states of the object being drawn. The ``de'' engine
 309 limits what can be configured in substyles to the set of colours in the
 310 first table above, but also specifically interprets for the main style
 311 \codestr{tab-frame} the substyles \codestr{*-*-tagged} and \codestr{*-*-*-dragged}
 312 by, respectively, drawing a right angle shape at the top right corner
 313 of a tab and by shading the tab with a stipple pattern. Also for
 314 menus the substyles \codestr{*-*-submenu} are handled as a special case.
 315
 316 Substyles are defined with the function \fnref{de.substyle} within the
 317 table defining the main style. The parameters to this function are
 318 similar to those of \fnref{de.defstyle}.
 319
 320 \begin{verbatim}
 321 de.defstyle("some-style", {
 322    ...
 323    de.substyle("some-substyle", {
 324       ...
 325    }),
 326    ...
 327 })
 328 \end{verbatim}
 329
 330
 331 \subsection{An example}
 332
 333 The following shortened segment from \file{look\_cleanviolet.lua}
 334 should help to clarify the matters discussed in the previous
 335 subsection.
 336
 337 \begin{verbatim}
 338 de.defstyle("*", {
 339     -- Gray background
 340     highlight_colour = "#eeeeee",
 341     shadow_colour = "#eeeeee",
 342     background_colour = "#aaaaaa",
 343     foreground_colour = "#000000",
 344
 345     shadow_pixels = 1,
 346     highlight_pixels = 1,
 347     padding_pixels = 1,
 348     spacing = 0,
 349     border_style = "elevated",
 350
 351     font = "-*-helvetica-medium-r-normal-*-12-*-*-*-*-*-*-*",
 352     text_align = "center",
 353 })
 354
 355 de.defstyle("tab-frame", {
 356     based_on = "*",
 357
 358     de.substyle("active-selected", {
 359         -- Violet tab
 360         highlight_colour = "#aaaacc",
 361         shadow_colour = "#aaaacc",
 362         background_colour = "#666699",
 363         foreground_colour = "#eeeeee",
 364     }),
 365
 366     --  More substyles would follow ...
 367 })
 368 \end{verbatim}
 369
 370
 371 \section{Miscellaneous settings}
 372 \label{sec:grmisc}
 373
 374
 375 \subsection{Frame user attributes}
 376
 377 The function \fnref{WFrame.set_grattr} may be used to give frames
 378 (and their tabs) arbitrary extra attributes to be passed to the
 379 drawing engine. Hence, by configuring such substyles in the style
 380 configuration files, and turning on the attribute when needed,
 381 scripts may display visual cues related to the frame. There is
 382 also one extra attribute specially interpreted by the default
 383 drawing engine: the \codestr{numbered} attribute, which causes
 384 numbers to be displayed on the tabs.
 385
 386
 387 \subsection{Extra fields for style \codestr{frame}}
 388
 389 The following style fields are independent of the drawing engine used,
 390 but are related to objects' styles and therefore configured in the drawing
 391 engine configuration file.
 392
 393 \begin{tabularx}{\linewidth}{lX}
 394 \tabhead{Field  & Description}
 395 \code{bar} & Controls the style of the tab-bar. Possible values
 396         are the strings \codestr{none}, \codestr{inside}, \codestr{outside}
 397         and \codestr{shaped}, with the last providing the PWM-style
 398         tab-bars for floating frames. \\
 399 \code{floatframe_tab_min_w} & Minimum tab width in pixels for
 400         the shaped style, given that this number times number of tabs
 401         doesn't exceed frame width. \\
 402 \code{floatframe_bar_max_w_q} & Maximum tab-bar width quotient of
 403         frame width for the shaped styles. A number in the
 404         interval $(0, 1]$.
 405 \end{tabularx}
 406
 407
 408
 409 \subsection{Extra fields for style \codestr{dock}}
 410
 411 \begin{tabularx}{\linewidth}{lX}
 412 \tabhead{Field  & Description}
 413 \code{outline_style} & How borders are drawn:
 414                         \codestr{none} -- no border,
 415                         \codestr{all} -- border around whole dock,
 416                         \codestr{each} -- border around each dockapp. \\
 417 \code{tile_size} & A table with entries \codestr{width} and \codestr{height},
 418         indicating the width and height of tiles in pixels.
 419 \end{tabularx}
 420
 421
 422 Hopefully that's enough to get you started in writing new style
 423 configuration files for Ion. When in doubt, study the existing
 424 style configuration files.