Configuration

Configuration is written in YAML and resides by default in ~/.amazing.yml. This behavior can be altered with the -c or --config switch, as in amazing --config /path/to/config.yml.

Values

include:
  - list
  - of
  - scripts
screens:
  - list
  - of
  - screens
widgets:
  identifier:
    type: WidgetName
    every: seconds
    format: ruby code
    options:
      widget: foo
      specific: bar

Example

include:
  - /path/to/some.rb
screens:
  - 0
  - 1
widgets:
  pb_bat:
    type: Battery
    every: 10
  tb_time:
    type: Clock
    every: 1
    options:
      time_format: %T
  tb_mail:
    type: Maildir
    options:
      directories:
        - Mail/**/new
        - Mail/inbox/cur

Widget configuration

Each widget type has its own options and “fields”. Fields are variables that can be used in the format option to customize what is displayed in the widget. These options and fields can be found out by issuing amazing with the -w or --list-widgets switch, which will output something like this:

Battery : Remaining battery power in percentage
            battery: <Battery number> || 1
            @percentage = <Power percentage> || 0

Raggle  : Unread posts in raggle
            require 'pstore' # Ruby standard library
            feed_list_path: <Path to feeds list> || ".raggle/feeds.yaml"
            feed_cache_path: <Path to feeds cache> || ".raggle/feed_cache.store"
            @count = <Ammount of unread posts> || 0

ALSA    : Various data for the ALSA mixer
            mixer: <ALSA mixer name> || "Master"
            @volume = <Volume in percentage> || 0

Memory  : Various memory related data
            @cached = <> || 0
            @usage = <Percentage of used memory> || 0
            @total = <Total kilobytes of memory> || 0
            @free = <Free kilobytes of memory> || 0
            @buffers = <> || 0

Maildir : Mail count in maildirs
            directories: <Globs of maildirs> || nil
            @count = <Ammount of mail in searched directories> || 0

Clock   : Displays date and time
            time_format: <Time format as described in DATE(1)> || "%R"
            @time = <Formatted time> || nil

Each section describes a widget type. require describes a dependency, a Ruby library which must be installed for the widget to function. Items followed by a colon describes an option, and items preceded by an at-sign describe a field. The || syntax describes the default value of the option/field.

Note: the output of --list-widgets will likely change as it is currently cryptic.

Format configuration

The format option is actually a Ruby program ran within an instance of the widget type. What this means is you have the full power of Ruby, but don’t have to make it more complex than you want to. Here are some examples:

A simple string

format: '"#@field1 / #@field2"'

Without the single quotes, the double quotes are interpreted by the YAML parser as enforcing the string type.

Conditioning

format: if @free > 1024 then "#{@free / 1024} GB" else "#@free MB" end

format: @free > 1024 ? "#{@free / 1024} GB" : "#@free MB"

Multi line

format: |
  if @free > 1024
    "#{@free / 1024} GB"
  else
    "#@free MB"
  end

Notes

Be wary that the configuration layout will likely change.

• Widget configuration will be screen specific, this also obsoletes the screens list
• Scripts will be included automatically from ~/.amazing/*.rb, rendering the include list less of a necessity
  • How this should be configured needs to be decided
• Custom widget configuration will probably be on equal level with the rest of the widget configuration, rendering the options list obsolete

Example

widgets:
  0:
    tb_mail:
      type: Maildir
      directories:
        - Mail/**/new
        - Mail/inbox/cur