README

   1 = amazing
   2
   3 an amazing widget manager for an awesome window manager
   4
   5   Usage: amazing [options]
   6      -c, --config FILE                Configuration file (~/.amazing.yml)
   7      -s, --screen ID                  Screen ID (0)
   8      -l, --log-level LEVEL            Severity threshold (info)
   9      -i, --include SCRIPT             Include a widgets script
  10      -u, --update WIDGET              Update a widget and exit
  11      -w, --list-widgets               List available widgets
  12      -h, --help                       You're looking at it
  13
  14 == Widgets
  15
  16 * Battery: Remaining battery power in percentage
  17 * Maildir: Mail count in maildirs
  18 * ALSA: Various data for the ALSA mixer
  19 * Raggle: Unread posts in raggle
  20 * Memory: Various memory related data
  21 * Clock: Displays date and time
  22
  23 == Configuration
  24
  25   include:
  26     - list
  27     - of
  28     - scripts
  29   screens:
  30     - list
  31     - of
  32     - screens
  33   widgets:
  34     identifier:
  35       type: WidgetName
  36       every: seconds
  37       format: ruby code
  38       options:
  39         widget: foo
  40         specific: bar
  41
  42 == Example
  43
  44   widgets:
  45     pb_bat:
  46       type: Battery
  47       every: 10
  48     tb_time:
  49       type: Clock
  50       every: 1
  51       options:
  52         time_format: %T
  53     tb_mail:
  54       type: Maildir
  55       options:
  56         directories:
  57           - Mail/**/new
  58           - Mail/inbox/cur
  59
  60 In this example tb_mail doesn't have an "every" setting and is instead
  61 updated manually with <tt>amazing -u tb_mail</tt>, perhaps in cron after fetching
  62 new mail via fdm, getmail, fetchmail or similar. A good idea is also to
  63 update after closing your MUA such as Mutt which could be done with
  64 shell functions, example:
  65
  66   mutt() {
  67     mutt $*
  68     amazing -u tb_mail
  69   }
  70
  71 == Writing widgets
  72
  73 TODO: describe this more completely
  74
  75 Example widget:
  76
  77   class Clock < Widget
  78     description "Displays date and time"
  79     dependency "some/library", "how to get the library (url, gem name...)"
  80     option :time_format, "Time format as described in DATE(1)", "%R"
  81     field :time, "Formatted time"
  82     default "@time"
  83
  84     init do
  85       @time = Time.now.strftime(@time_format)
  86       raise WidgetError, "An error occured!" if some_error?
  87     end
  88   end
  89
  90 The ProcFile class can be used for parsing /proc files:
  91
  92   cpuinfo = ProcFile.new("cpuinfo")
  93   cpuinfo[1]["model name"]
  94   #=> "AMD Turion(tm) 64 X2 Mobile Technology TL-50"
  95
  96 == Copying
  97
  98   Copyright (C) 2008 Dag Odenhall <dag.odenhall@gmail.com>
  99   Licensed under the Academic Free License version 3.0