Configuration

Mowedline is configured by creating either a ~/.mowedline or $XDG_CONFIG_HOME/mowedline/init.scm file, or passing a file along with the -config command. If XDG_CONFIG_HOME is not specified in the environment, the value ~/.config will be used. The documentation will sometimes refer to this file as your ".mowedline", and when it does, it refers to either one. Some configuration can also be done by passing commands to the mowedline program.

Instead of using a static configuration format and being constrained by the implicit limitations thereof, a mowedline configuration is written in scheme (CHICKEN Scheme to be precise). Your .mowedline is a scheme program, allowing you to leverage the full power of the scheme programming language to configure, enhance, and extend mowedline in novel and creative ways.

The .mowedline file is loaded by the mowedline daemon at startup. Its primary responsibility is to create windows and populate them with widgets. If your .mowedline does not create a window, a default window with one widget will be created. Let's get right into an example.

(window
 (widget:text
  name: "default"
  flex: 1)))

Windows and widgets are instantiated with their specific procedure such as window and widget:text in the example. The arguments to each function depend on what you're creating. In the case of window there can first be pairs of property names and values, followed by any widgets you would like to add.

Every widget must have a unique name. The name is how widgets are referred to in the command-line interface.

The flex property is explained below.

Widget Types

There is a small selection of built-in widget types that you can use. We expect to write more widget types over time, as we the users invent new ideas.

Note: As of version 2.0.0 mowedline uses keywords instead of symbols to name properties. The examples in the documentation use the keyword: notation, but the #:keyword is also possible. Changing the keyword-style parameter in your configuration to #:prefix could also allow you to use :keyword, but this is mutually exclusive with keyword:. According to the CHICKEN documentation the #:keyword style is always accepted.

Widget Types

The widget types that come with Mowedline are listed here. Details about how to configure them can be found below.

• widget:active-window-icon
• widget:active-window-title
• widget:clock
• widget:flags
• widget:map
• widget:spacer
• widget:text

Common properties

These options can be used on any type of widget that appears in your configuration.

• background-color

  The background color of the widget. See the explanation under 'color' below for the allowed values of this property. The default is #f, meaning it should use the window's background color.

• flex

  The flex property makes a widget's width rubber. When a window is drawn on screen, the available width is divvied up among the widgets. Normally, each widget is allocated exactly enough space to fit its contents. A widget with flex, however, is allocated a portion of the leftover space, after allocating space for all other widgets. The flex values of all widgets are added up, and the remaining space is divided among them in proportion to each widget's flex value. In our example, we have one widget with a flex value of 1. The total flex is 1, and our widget receives 1/1th of the space, or 100%. If we add another widget and give it flex 2, that makes a total flex of 3, our first widget get's 1/3, and the new widget gets 2/3. A value of 0 means that the widget's width gets allocated normally.

• name

  Any widget which may be updated from the outside (such as from mowedline-client or over DBus) must have a unique name.

• init

  Optional user-supplied initialization procedure for the widget. When given, it should be a function of one argument (the widget).

widget:text

• color

  The color in which to render the text. This can be given as a string color name, a string hex specifier, a three element (R G B) list or a four element list (R G B A). A string hex specifier is the familiar 6 digit hexidecimal notation as used in HTML, #000000 means black and #ffffff means white. The list forms are slightly more efficient, since they don't require the X server to be queried. The numbers given in the list are on a scale of 0 to 1: (0 0 0 1) means black, and (1 1 1 1) means white. The default is white.

• font

  An Xft-style font name. Use the program fc-list to see what fonts are installed on your computer. Specify size by appending a hyphen followed by a number. Specify other attributes by appending a colon and an attribute specifier. See section 1.1 here for more information on how to format font names. Mowedline's default font is "mono-10:bold".

• format

  A procedure of one argument that receives the raw text and which can return either a string or a list-structured markup definition. Markup definitions can be used to colorize and buttonize text. The markup language is very simple. It is just a nested list that contains strings and markup elements. Markup elements may take positional arguments. The following elements are available:

  • (color <color> ...)

    The argument is a color specification. Text inside the color element will be colored with that color.

    '("a" (color "red" "b") "c")
    

  • (button <thunk> ...)

    Thunk is a procedure of no arguments that will be called when the text inside the button is clicked. In the following example, clicking on the "b" sends an update to the widget, "foo".

    '("a"
      (button (lambda () (update "foo" "bar"))
              "b")
      "c")
    

  • (font <font> ...)

    The argument is a font specification. Text inside the font element will be rendered in that font.

    '("a" (font "Coffee Script-12" "b") "c")
    

• text

  The text to display in the widget. This is the value that gets set when you run mowedline -update awidget 'some text', after possible processing by a format function.

widget:clock

All widget:text properties can be used with a clock.

• time-format

  A string giving the time->string format for the clock.

widget:flags

The flags widget is derived from the text widget, and serves the purpose of displaying a set of flags. The flags are pre-defined via the flags: slot and upon update, input is parsed and interpreted to turn on, turn off, or clear and replace the set of currently displayed flags.

Input is parsed as follows. If the input begins with '+', then the following flagnames are turned on. If the input begins with '-', then the following flagnames are turned off. Otherwise, the given flagnames replace the current flag set. Flagnames are given in a simple sequence, separated by spaces.

• flags

  An alist giving the associations between flag names and display forms. For example:

   '(("foo" . (color "red" "f"))
     ("bar" . (color "blue" "b")))
  

Note: the text property of a flags widget will always be a markup structure, never a string, so format procedures should be adjusted accordingly.

widget:map

The map widget is updated with data in pairs k v and stores them in a hashmap. The contents of this hashmap are formatted as text and displayed according to the format-pair function and separator. The map widget might be used, for example, to receive and display information about email accounts and the number of new messages that they have.

• format-pair

  A function of two arguments (key and value) that returns a string for display. The default procedure converts both key and value to strings and joins them on =.

• separator

  String separator, defaults to ,. Entries in the map are joined on this string for display.

widget:active-window-icon

Displays the icon of the active window.

widget:active-window-title

Displays the title of the active window.

widget:spacer

A boring widget for creating space.

• width

  width of the spacer in pixels.

Window Properties

• height

  Window height in pixels. If not given, defaults to the height of the tallest widget in the window.

• position

  A symbol giving the position of the mowedline window on the screen. Supported values are top and bottom.

• width

  Window width in pixels. If not given, defaults to the width of the display.

• margin-bottom, margin-left, margin-right, margin-top

  How far, in pixels, from the bottom, left, right or top edge of the screen the window should be placed. If not given, all default to 0.

• background

  The background color of the window. Can be either of the values inherit, transparent or #f. The value inherit makes the background transparent for displays without a compositor by copying the root window's background. The value transparent makes the background transparent for displays with a compositor.

  Note: If you use inherit with a compositor, repaint doesn't work right. If you use transparent without a compositor, you'll just get a black background.

Setting Defaults

The default values of many of the properties listed above can be changed by a group of parameter procedures. The following procedures are available for configuring defaults.

• text-widget-font
• text-widget-color
• text-widget-format
• widget-background-color
• widget-flex
• window-position
• window-background

Use these procedures in your .mowedline before instantiating the widgets which are to be affected.

Examples

Change the default font for all text-widgets:

(text-widget-font "DejaVu Sans Mono-10:bold")

Change the default text color of all text-widgets:

(text-widget-color "#999999")