rwma - ruby window manager addons

TOC:
  0. Introduction
  1. Instalation
  2. Configuration
  3. Commands
  4. Usage


0. Introduction
===============

RWMA is a modular system for adding various keyboard driven actions to (usually
minimalistic) window managers, inspired by ruby-wmii. It's main purpose is launching
programs and notification displaying but can be expanded with plugins. It is somewhat
similar to Gnome Do or Enso (on Windows).

It uses dmenu and dzen for user input/output.

Basically, it is a Ruby script that is started with window manager, which receives
commands via named pipe. Sending commands to rwma is usually binded to keyboard
shortcuts (using window manager settings or xbindkeys)

Plugins are placed in one of modules directories:
    * modules directory inside rwma directory
    * /usr/share/rwma/modules
    * ~/.rwma/modules

For information on how to write plugins look at the modules/PluginSample.rb file.

Requirements:
    ruby (tested on ruby 1.8.7 and 1.9.1)
    dmenu
    dzen
    mechanize gem (install it with "gem install mechanize" as root - needed only
    for EUdict plugin)


RWMA is written by Igor Brkic and distributed under GPLv3 licence.


1. Installation
===============

This section only applies if you are installing rwma by hand.

First make sure you have all the dependencies installed (mechanize is currently used
only for EUdict translation plugin).

Unpack archive to desired location:
    tar xvzf rwma-<version>.tar.gz
    cd rwma-<version>

Make rwma executable it it isn't
    chmod +x rwma
    chmod +x rwma-command

Copy sample configuration file to your home folder:
    cp rwma.yaml.sample ~/.rwma.yaml

Create FIFO pipe (its location can be changed in config file):
    mkfifo ~/.rwma_fifo

Proceed with configuration.


If you want to see rwma in action with default configuration, edit FIFO file path in 
configuration file and then run rwma. in other terminal go to the rwma directory and 
type './rwma-command menu'

It is important to set valid font in configuration file. Otherwise dzen otput will
not work.


2. Configuration
================

Sample config file has a lot of comments inside, but syntax will be explained here
too. It must be placed in ~/.rwma.yaml

Config file is in YAML format and is pretty much self explaining. Indentation IS VERY
important! You can use tabs or spaces but try to be consistent. Words that are prefixed
with colon (:) are keywords, and that colon is important (do not remove it).

Sample config file can be found in rwma tarball or /usr/share/rwma directory (if installed
via package manager).

Config file contains four main sections: :main, :plugins, :visuals and :menu. Each section
has some required and some optional entries.

:main
  In this sections basic things are defined. First thing that is required is to define full
  path to FIFO pipe that will be used for communication. Path must be absolute (ie without ~).

  In this section you can also define what type of logging do you want. This entry is not 
  required and 'none' is default option. For most purposes this will be OK. If you're having
  problems with rwma it is good to enable logging. Possible options are stdout, stderr and
  file (log will be written to <script dir>/rwma.err file).

:plugins
  This section defines which plugins will be enabled. Plugins are put in modules directory
  and each should have description, available options and commands and usage informations at
  the top.

  Enabling a plugin is as easy as putting its name (case is important) and options in :plugins
  section. If plugin does not require options put nil.

:visuals
  This section defines visual look of the rwma. Since # represents comment in YAML format, 
  HEX color values should be put in quotes.

  All entries are optional.

:menu
  This section defines menu hierarchy that can be created using rwma. Every entry must have
  its :type defined. Follows description of available types. Every menu item can be accessed
  through dmenu and also through commands (you can directly call various submenus)

  :type: menu
    Menu item. This item must also have :sub in which its submenu is defined

  :type: text
    Pretty much useless type that just displays text defined in :text using dzen. All dzen
    formatting options are available for adding color and xbm icons. Partly usable for
    debugging.

  :type: app
    Menu item used for direct application launching. Each item must also have :name field
    in which command to run is defined

  :type: plugin
    Menu item used to call plugin's functionality. Each item must also have :name field
    with plugin name. Each item can optionally have :action field for sending command
    directly to plugin (for example Volume plugin will by default show menu with +, -
    and mute choices. This can be bypassed by sending command '+', '-' or m directly to
    plugin via the :action field so you can have for example 'volume mute' menu entry)

  :type: console
    Menu item used for debugging purposes only. Can be used to change config settings
    in the runtime. Not very user friendly (actually not user friendly at all).
    
  :type: reload_config
    Used for reloading config file while program is running. This means you can edit
    the menu stucture, change colors and load new plugins without restarting rwma. Note
    that rwma will crash if you load plugin with syntax or other error (need to fix this).


3. Commands
===========

There are several commands that can be passed to rwma.

menu
----
  This command is used to display main menu as defined in config file. It can also be used
  to display any defined menu item by sufixing it with wanted hierarchy.

  For example, if we have following menu structure
   /
    |-- system
    |     |-- program list update
    |     |-- console
    |
    |-- music
    |     |-- next
    |     |-- prev
    |
    |-- xterm

  Sending command 'menu' to rwma will display root menu (system, music, xterm) using dmenu.
  We can show only music submenu by using 'menu music' command or acces 'next' menu item
  directly by 'menu music next'. Note however that this currently can't be used for menu
  items with more than one word.

quit
----
  Command for quitting rwma

text <any text>
---------------
  Command for showing arbitrary text using dzen. All dzen formatting options are valid.
  Be sure to put text in quotes if you are using formatting options.

  It can be used for various notifications from other scripts.
  
  Why use rwma for this and not directly dzen? It is simpler, and default colors will be
  consistent with other rwma plugins. Other than that, no particular reason.

<plugin name> [<plugin commands>]
---------------------------------
  It is possible to call plugin directly by using its name and optionally send it some
  commands. Case is not important here (you can type 'Launcher', 'launcher' or 'lAuNcHeR')

  You can also send commands to plugin by typing them after plugin name (example 'volume +')



4. Usage
========

You can send command to rwma by writing it directly to  FIFO pipe (echo command > path/to/fifo).
There is also very simple shell script rwma-command included with rwma that enables to send
commands to rwma by passing arguments to it (./rwma-command volume +). This is because in some
window managers (awesome for example) it is not possible (AFAIK) to use IO redirections when
adding keybinding.

You can bind hotkeys to rwma commands using window manager settings or using an application like 
xbindkeys.

I usually have small menu with eudict and program list update, among others,  binded to Super+a 
and Launcher binded to Super+p (old habit from ruby-wmii days :). I also bind multimedia keys directly
to player control and volume plugin.


EOF