4. Graphical styles

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

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 4.1.1 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

4.1.1.2 Tabs and menu entries

4.1.1.3 The rest

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 Figure 4.1.

Figure 4.1: 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).

4.2.2.2 Borders and widths

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

4.2.2.3 Text

4.2.2.4 Miscellaneous

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.

4.3.3 Extra fields for style `dock'

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.