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