README.rdoc

   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       -s, --stop                       Stop the running amazing process
   9       -i, --include SCRIPT             Include a widgets script
  10           --no-auto-include            Don't auto include from ~/.amazing/widgets/
  11       -u, --update [WIDGET]            Update a widget and exit
  12       -w, --list-widgets [WIDGET]      List available widgets or options and fields for a widget
  13       -t WIDGET [OPTIONS]              Dump field values for a widget configured with inline YAML
  14           --test-widget
  15       -h, --help                       You're looking at it
  16
  17 == Widgets
  18
  19   ACAdapter  : AC adapter status
  20   ALSA       : Various data for the ALSA mixer
  21   Battery    : Remaining battery power in percentage
  22   Clock      : Displays date and time
  23   File       : Information for a file
  24   Filesystem : Various filesystem information
  25   GMail      : GMail checker
  26   MOC        : Music On Console status
  27   MPD        : MPD Information
  28   Maildir    : Mail count in maildirs
  29   Memory     : Various memory related data
  30   Pacman     : Available upgrades in the Pacman package manager
  31   Raggle     : Unread posts in raggle
  32
  33 == Configuration
  34
  35   include:
  36     - <path/to/program.rb>
  37   widgets:
  38     <screen>:
  39       <identifier>:
  40         type: <WidgetName>
  41         every: <seconds>
  42         format: <ruby code>
  43         <custom option>: <value>
  44
  45 == Example
  46
  47   include:
  48     - /path/to/widgets.rb
  49   widgets:
  50     0:
  51       pb_bat:
  52         type: Battery
  53         every: 10
  54       tb_time:
  55         type: Clock
  56         every: 1
  57         time_format: %T
  58       tb_mail:
  59         type: Maildir
  60         format: '"#@count new message#{@count != 1 : "s" : ""}"'
  61         directories:
  62           - Mail/**/new
  63           - Mail/inbox/cur
  64
  65 In this example tb_mail doesn't have an "every" setting and is instead
  66 updated manually with <tt>amazing -u tb_mail</tt>, perhaps in cron after fetching
  67 new mail via fdm, getmail, fetchmail or similar. A good idea is also to
  68 update after closing your MUA such as Mutt which could be done with
  69 shell functions, example:
  70
  71   mutt() {
  72     mutt $*
  73     amazing -u tb_mail
  74   }
  75
  76 == Writing widgets
  77
  78 TODO: describe this more completely
  79
  80 Example widget:
  81
  82   class Clock < Widget
  83     description "Displays date and time"
  84     dependency "some/library", "how to get the library (url, gem name...)"
  85     option :time_format, "Time format as described in DATE(1)", "%R"
  86     field :time, "Formatted time"
  87     default "@time"
  88
  89     init do
  90       @time = Time.now.strftime(@time_format)
  91       raise WidgetError, "An error occured!" if some_error?
  92     end
  93   end
  94
  95 The ProcFile class can be used for parsing /proc files:
  96
  97   cpuinfo = ProcFile.parse_file("cpuinfo")
  98   cpuinfo[1]["model name"]
  99   #=> "AMD Turion(tm) 64 X2 Mobile Technology TL-50"
 100
 101 == Copying
 102
 103   Copyright (C) 2008 Dag Odenhall <dag.odenhall@gmail.com>
 104   Licensed under the Academic Free License version 3.0