Rodentbane
From awesome
Rodentbane is an implementation of keynav in a lua module for awesome. It allows for rapid control of the mouse cursor using just the keyboard, and can speed up your workflow significantly. It is mean to be used in situations where regular window manager and application bindings will not suffice, and you absolutely have to use a click event. (Think flash objects inside webpages) It is not meant as a full-blown replacement for using the mouse, for that, you will need to set keybindings and use programs that support full keyboard control (such as awesome, of course).
Contents |
[edit] Getting Rodentbane
[edit] Arch Linux
If you are using Arch Linux, a PKGBUILD is already available over at the aur, get it here: http://aur.archlinux.org/packages.php?ID=26406
[edit] PLD Linux
If you are using PLD Linux, just install awesome-plugin-rodentbane using poldek:
poldek -i awesome-plugin-rodentbane
[edit] Manually
If you are using other system or would like to fetch the library separately, you can fetch it from the git repository at http://git.glacicle.com/?p=awesome/rodentbane.git;a=summary.
Install it manually as such:
git clone git://git.glacicle.com/awesome/rodentbane.git sudo cp rodentbane/rodentbane.lua /usr/share/awesome/lib/
[edit] Using Rodentbane
[edit] Basic usage
To make use of rodentbane, you need only to require("rodentbane") at the top of your configuration file. After this, you can call rodentbane.start() in any keybinding, and you will be able to use rodentbane with the default keybinding configuration.
- NOTE: At this point in time, rodentbane requires either the xdotool or the xte (usually found in the "xautomation" package) binary in order to simulate mouse clicks. It will use whichever one it finds.
[edit] Rodentbane mode
After rodentbane.start() is called, all keys are grabbed and you are put in "rodentbane mode". In this mode, you can only use the keybindings you have set up with rodentbane. A set of lines is drawn on the screen, dividing the screen into 4 parts. You can use keybindings to cut the area in half horizontally or vertically, after which you can choose to click at the center of the (now smaller) area, or cut it in half again. You can also move the entire area in any direction. This means you can find the correct spot to click (at worst) in a logarithmic amount of time.
[edit] Default keybindings
h Cut to the left j Cut downwards k Cut upwards l Cut to the right Shift+h Move the area to the left Shift+j Move the area downwards Shift+k Move the area upwards Shift+l Move the area to the right u Undo the last cut or move operation Space Click the spot in the center of the area Mod1+Space Double click the spot in the center of the area Control+Space Middle click the spot in the center of the area Shift+Space Right click the spot in the center of the area Return Only warp the cursor the the spot in the center of the area
Pressing any key not defined as a binding will terminate rodentbane mode.
[edit] Custom Keybindings
You can define your own custom bindings by calling the rodentbane.bind() function in much the same way you define regular awesome bindings.
Call the function as such:
rodentbane.bind(modkeys, key, func)
With modkeys as the table of modkeys that should be pressed, key as a string keysym for the key to be pressed, and func for the function to be called when it is pressed.
For example, to add a left click binding to the combination of control+h, use:
rodentbane.bind({"Control"}, "h", function()
rodentbane.warp() -- Place the cursor in the center of the active area
rodentbane.click(1) -- Click button 1 (left)
rodentbane.stop() -- Leave rodentbane mode
end)
- NOTE: Once you define a custom keybind, the defaults will no longer be loaded. If you want to load the defaults and still add custom bindings, add a call to rodentbane.binddefault() to your rc.lua.
[edit] Rodentbane appearance
You can use beautiful to change the appearance settings of rodentbane. By default, it will use your beautiful.border_focus color as the color for the guidelines, and will use a line width of 2. You can override either by setting the beautiful.rodentbane_bg and beautiful.rodentbane_width settings respectively.
[edit] Rodentbane Functions
This is a reference of all the notable functions exposed by rodentbane.
- rodentbane.start([screen, recall])
Start rodentbane mode. Screen is the screen to start it on, defaults to the current screen. If recall is true, the area you last used will be recalled.
- rodentbane.stop()
Leaves rodentbane mode, nothing is done.
- rodentbane.cut(dir)
Cut the current area into a direction. With dir as one of {"up", "right", "down", "left"}.
- rodentbane.move(dir[, ratio=0.5])
Move the current area in a direction. With dir as one of {"up", "right", "down", "left"}. Ratio is the amount of space to move, a ratio of 0.5 (default) will move the area half its size, a ration of 2 will move it twice its size.
- rodentbane.warp()
Warps the cursor to the center position of the active area.
- rodentbane.click([button=1])
Simulates a mouse click at the current position of the cursor.
- rodentbane.undo()
Undo the last operation that changed the active area.
- rodentbane.binddefault()
Bind all default keybindings. This is automatically called if no custom bindings have been defined by the time start() is called for the first time.
- rodentbane.bind(modkeys, key, func)
Bind a key in rodentbane mode.
