4. Graphical styles
Keywords: notionconf

Subsections

- 4.1 Drawing engines, style specifications and sub-styles
  - 4.1.1 Known styles and substyles
    - 4.1.1.1 Frames
    - 4.1.1.2 Tabs and menu entries
    - 4.1.1.3 The rest
- 4.2 Defining styles for the default drawing engine
  - 4.2.1 The structure of the configuration files
  - 4.2.2 Defining the styles
    - 4.2.2.1 Colours
    - 4.2.2.2 Borders and widths
    - 4.2.2.3 Text
    - 4.2.2.4 Miscellaneous
    - 4.2.2.5 Substyles
  - 4.2.3 An example
- 4.3 Miscellaneous settings
  - 4.3.1 Frame user attributes
  - 4.3.2 Extra fields for style `frame'
  - 4.3.3 Extra fields for style `dock'

#
4. Graphical styles

This chapter first gives in section a general outline of how drawing engines are used, of style specifications and then in section describes how to specify styles for the default drawing engine. Some additional settings and user attributes are explained in Sections .

##
4.1 Drawing engines, style specifications and sub-styles

Notion's drawing routines are abstracted into so-called drawing engine modules that can, again depending on the system, be dynamically loaded as needed. The drawing engine modules provide “brushes” that objects can use to draw some high-level primitives such as borders and text boxes (in addition to simple text and rectangle drawing) on their windows and configure e.g. the shape and background of the window. While the drawing engines therefore do not directly implement looks for each possible object (that would hardly be maintainable), different brush styles can be used to give a distinctive look to different objects and engines could interpret some styles as special cases. Style specifications are strings of the form

    element1-element2-...-elementn

An example of such a style specification is `tab-frame'; see the table in subsection for more styles.

When an object asks for a brush of certain style, the selected drawing engine will attempt to find the closest match to this specification. The styles/brushes defined by the drawing engines may have asterisks (`*') as some of the elements indicating a match to anything. Exact matches are preferred to asterisk matches and longer matches to shorter. For example, let a brush for style `foo-bar-baz' be queried, then the following brushes are in order of preference:

    foo-bar-baz
    foo-*-baz
    foo-bar
    *

Some of the drawing primitives allow extra attributes to be specified, also in the form

    attr1-attr2-...-attrn

These extra attributes are called substyles and allow, for example, the state of the object to be indicated by different colour sets while keeping the interface at an abstract level and the drawing engine completely ignorant of the semantics - only the writer of the drawing engine configuration file has to know them. However the drawing engine can again interpret known substyles as special cases and the default engine indeed does so with frame tab tag and drag states.)

###
4.1.1 Known styles and substyles

#### 4.1.1.1 Frames

Style name | Description
`frame' | Style for frames. Substyle attributes: `active'/`inactive' (mutually exclusive), and `quasiactive'. A frame is “quasiactive” when an active region has a back-link to it, such as a detached window.
`frame-tiled' | A more specific style for tiled frames. Substyle attributes as for `frame'.
`frame-tiled-alt' | An alternative style for tiled frames. Often used to disable the tab-bar.
`frame-floating' | A more specific style for floating frames.
`frame-transient' | A more specific style for frames containing transient windows.

#### 4.1.1.2 Tabs and menu entries

Style name | Description
`tab' | Style for frames' tabs and menu entries. Substyle attributes: `active'/`inactive' and `selected'/`unselected'
`tab-frame' | A more specific style for frames' tabs. Additional substyle attributes include those of the `frame' style, as well as tab-specific `tagged'/`not_tagged', `dragged'/`not_dragged', and `activity'/`no_activity'.
`tab-frame-tiled', |
`tab-frame-tiled-alt', |
`tab-frame-floating', |
`tab-frame-transient' | More specific styles for frames in the different modes.
`tab-menuentry' | A more specific style for entries in WMenus. Additional substyle attributes include `submenu' and occasionally also `activity' is used.
`tab-menuentry-bigmenu' | An alternate style for entries in WMenus.
`tab-info' | Extra information tab (displayed e.g. for tagged workspaces).

#### 4.1.1.3 The rest

Style name | Description
`input' | A style for WInputs.
`input-edln' | A more specific style for WEdlns. Substyle attributes: `selection' for selected text and `cursor' for the cursor indicating current editing point.
`input-message' | A more specific style for WMessages.
`input-menu' | A more specific style for WMenus.
`input-menu-bigmenu' | An alternate style for WMenus.
`moveres_display' | The box displaying position/size when moving or resizing frames.
`actnotify' | Actification notification box.
`stdisp' | Any status display.
`stdisp-dock' | The dock.
`stdisp-statusbar' | The statusbar. Substyles include: the name of any monitor/meter (such as `date'), and the supplied hint. Typical hints are: `normal', `important', and `critical'.

##
4.2 Defining styles for the default drawing engine

Drawing engine style files are usually named look_foo.lua where foo is the name of the style. The file that Notion loads on startup or when gr.read_config is called, however, is look.lua and should usually be symlinked to or a copy of of some look_foo.lua.

### 4.2.1 The structure of the configuration files

The first thing to do in a style file is to choose the drawing engine, possibly loading the module as well. This is done with the following chunk of code.

    if not gr.select_engine("de") then
        return
    end

The gr.select_engine function sees if the engine given as argument is registered (the default drawing engine is simply called “de”). If the engine could not be found, it tries to load a module of the same name. If the engine still is not registered, gr.select_engine returns `false' and in this case we also exit the style setup script. If the engine was found, gr.select_engine sees that further requests for brushes are forwarded to that engine and returns `true'.

Before defining new styles it may be a good idea to clear old styles from memory so if the old configuration defines more specific styles than the new, the old styles don't override those specified by the new configuration. That can be done by calling

    de.reset()

After this the new styles can be defined with de.defstyle as explained in the next subsection. Finally, after the styles have been defined we must ask objects on the screen to look up new brushes to reflect the changes in configuration. This is done with

    gr.refresh()

### 4.2.2 Defining the styles

Styles for the default drawing engine are defined with the function de.defstyle. It has two arguments the first being a style specification as explained in previous sections and the second a table whose fields describe the style:

    de.defstyle("some-style", {
        attribute = value,
        ...
    })

The supported attributes are described in tables below. The different border elements and styles referred to there are explained in the following sketch of different border styles and elements:

    Elevated:        Inlaid:         Ridge:            Groove:
      hhhhhhhhhhhs     ............	   hhhhhhhhhhhs      sssssssssssh
      h..........s     .sssssssssh.	   h..........s      s..........h
      h.        .s     .s        h.	   h.sssssssh.s      s.hhhhhhhs.h
      h.        .s     .s        h.	   h.s      h.s      s.h      s.h
      h.        .s     .s        h.	   h.shhhhhhh.s      s.hsssssss.h
      h..........s     .shhhhhhhhh.	   h..........s      s..........h
      hsssssssssss     ............	   hsssssssssss      shhhhhhhhhhh

    h = highlight, s = shadow, . = padding

#### 4.2.2.1 Colours

Each of these fields a string of the form that can be passed to XAllocNamedColor. Valid strings are e.g. hexadecimal RGB specifications of the form #RRGGBB and colour names as specified in /usr/X11R6/lib/X11/rgb.txt (exact path varying).

Field | Description
highlight_colour | Colour for the “highlight” part of a border.
shadow_colour | Colour for the “shadow” part of a border.
foreground_colour | Colour for the normal drawing operations, e.g. text.
background_colour | Window background colour (unless transparency is enabled) and background colour boxes.
padding_colour | Colour for the “padding” part of a border border. Set to background_colour if unset.

#### 4.2.2.2 Borders and widths

All other fields below except border_style are non-negative integers indicating a number of pixels.

Field | Description
border_style | A string indicating the style of border; one of `elevated'/`inlaid'/`ridge'/`groove' as seen in the above sketch.
border_sides | A string indicating which sides of the border to draw: `all'/`tb'/`lr' for all, top and bottom, and left and right. To control between left/right and top/bottom, use the pixel options below.
highlight_pixels | Width of the highlight part of the border in pixels.
shadow_pixels | Width of the shadow part of the border in pixels.
padding_pixels | Width of the padding part of the border in pixels.
spacing | Space to be left between all kinds of boxes.

#### 4.2.2.3 Text

Field | Description
font | Font to be used in text-drawing operations; standard X font name.
text_align | How text is to be aligned in text boxes/tabs; one of the strings `left'/`right'/`center'.

#### 4.2.2.4 Miscellaneous

Field | Description
transparent_background | Should windows' that use this style background be transparent? true/false.
based_on | The name of a previously defined style that this style should be based on.

#### 4.2.2.5 Substyles

As discussed in previous sections, styles may have substyles to e.g. indicate different states of the object being drawn. The “de” engine limits what can be configured in substyles to the set of colours in the first table above, but also specifically interprets for the main style `tab-frame' the substyles `*-*-tagged' and `*-*-*-dragged' by, respectively, drawing a right angle shape at the top right corner of a tab and by shading the tab with a stipple pattern. Also for menus the substyles `*-*-submenu' are handled as a special case.

Substyles are defined with the function de.substyle within the table defining the main style. The parameters to this function are similar to those of de.defstyle.

    de.defstyle("some-style", {
       ...
       de.substyle("some-substyle", {
          ...
       }),
       ...
    })

### 4.2.3 An example

The following shortened segment from look_cleanviolet.lua should help to clarify the matters discussed in the previous subsection.

    de.defstyle("*", {
        -- Gray background
        highlight_colour = "#eeeeee",
        shadow_colour = "#eeeeee",
        background_colour = "#aaaaaa",
        foreground_colour = "#000000",

        shadow_pixels = 1,
        highlight_pixels = 1,
        padding_pixels = 1,
        spacing = 0,
        border_style = "elevated",

        font = "-*-helvetica-medium-r-normal-*-12-*-*-*-*-*-*-*",
        text_align = "center",
    })

    de.defstyle("tab-frame", {
        based_on = "*",

        de.substyle("active-selected", {
            -- Violet tab
            highlight_colour = "#aaaacc",
            shadow_colour = "#aaaacc",
            background_colour = "#666699",
            foreground_colour = "#eeeeee",
        }),

        --  More substyles would follow ...
    })

##
4.3 Miscellaneous settings

### 4.3.1 Frame user attributes

The function WFrame.set_grattr may be used to give frames (and their tabs) arbitrary extra attributes to be passed to the drawing engine. Hence, by configuring such substyles in the style configuration files, and turning on the attribute when needed, scripts may display visual cues related to the frame. There is also one extra attribute specially interpreted by the default drawing engine: the `numbered' attribute, which causes numbers to be displayed on the tabs.

### 4.3.2 Extra fields for style `frame'

The following style fields are independent of the drawing engine used, but are related to objects' styles and therefore configured in the drawing engine configuration file.

Field | Description
bar | Controls the style of the tab-bar. Possible values are the strings `none', `inside', `outside' and `shaped', with the last providing the PWM-style tab-bars for floating frames.
frame_tab_width_alg | Algorithm used to determine tab sizes for non-shaped frames. `equal' is the default. `elastic' wants equal sized tabs, with long titles longer. `proportional' wants distribute free space equally among the tabs.
frame_tab_min_w | Minimum size of a tab. This size is maintained as long as no other tab has to be truncated in the case of the `proportional' or `elastic' algorithm. Also minimum size of a tab in shaped frame (for all algorithms).
floatframe_tab_min_w | Alias for frame_tab_min_w. This is an old name of the variable from times when the only algorithm was `equal'.
frame_propor_tab_min_w | Absolute minimum size of an elastic or proportional tab, `elastic' and `proportional' algorithms truncate other tabs rather than shortening a short tab below this size.
floatframe_bar_max_w_q | Maximum tab-bar width quotient of frame width for the shaped styles. A number in the interval (0, 1]. This quotient is maintained even if the tabs have to be smaller than frame_tab_min_w or frame_propor_tab_min_w to fit.

### 4.3.3 Extra fields for style `dock'

Field | Description
outline_style | How borders are drawn: `none' - no border, `all' - border around whole dock, `each' - border around each dockapp.
tile_size | A table with entries `width' and `height', indicating the width and height of tiles in pixels.

Hopefully that's enough to get you started in writing new style configuration files for Notion. When in doubt, study the existing style configuration files.