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