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/config.yml)
   7      -l, --log-level LEVEL            Severity threshold (info)
   8      -i, --include SCRIPT             Include a widgets script
   9          --no-auto-include            Don't auto include from ~/.amazing/widgets/
  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     - <path/to/program.rb>
  27   widgets:
  28     <screen>:
  29       <identifier>:
  30         type: <WidgetName>
  31         every: <seconds>
  32         format: <ruby code>
  33         <custom option>: <value>
  34
  35 == Example
  36
  37   include:
  38     - /path/to/widgets.rb
  39   widgets:
  40     0:
  41       pb_bat:
  42         type: Battery
  43         every: 10
  44       tb_time:
  45         type: Clock
  46         every: 1
  47         time_format: %T
  48       tb_mail:
  49         type: Maildir
  50         format: '"#@count new message#{@count != 1 : "s" : ""}"'
  51         directories:
  52           - Mail/**/new
  53           - Mail/inbox/cur
  54
  55 In this example tb_mail doesn't have an "every" setting and is instead
  56 updated manually with <tt>amazing -u tb_mail</tt>, perhaps in cron after fetching
  57 new mail via fdm, getmail, fetchmail or similar. A good idea is also to
  58 update after closing your MUA such as Mutt which could be done with
  59 shell functions, example:
  60
  61   mutt() {
  62     mutt $*
  63     amazing -u tb_mail
  64   }
  65
  66 == Writing widgets
  67
  68 TODO: describe this more completely
  69
  70 Example widget:
  71
  72   class Clock < Widget
  73     description "Displays date and time"
  74     dependency "some/library", "how to get the library (url, gem name...)"
  75     option :time_format, "Time format as described in DATE(1)", "%R"
  76     field :time, "Formatted time"
  77     default "@time"
  78
  79     init do
  80       @time = Time.now.strftime(@time_format)
  81       raise WidgetError, "An error occured!" if some_error?
  82     end
  83   end
  84
  85 The ProcFile class can be used for parsing /proc files:
  86
  87   cpuinfo = ProcFile.parse_file("cpuinfo")
  88   cpuinfo[1]["model name"]
  89   #=> "AMD Turion(tm) 64 X2 Mobile Technology TL-50"
  90
  91 == Copying
  92
  93   Copyright (C) 2008 Dag Odenhall <dag.odenhall@gmail.com>
  94   Licensed under the Academic Free License version 3.0