Home

Awesome

howm (Beta)

Build Status Flattr this git repo

A lightweight, tiling X11 window manager that mimics vi by offering operators, motions and modes.

Howm is on the AUR, there are two packages for it:

Come and join us on Freenode in the channel #howm

Contents

Requirements

Installation

Howm is on the AUR, there are two packages for it:

If you can't use the AUR, then there may be a package available for your distro.

As a last resort install xcb's libraries and then, do the following:

git clone https://github.com/HarveyHunt/howm
cd howm
make
sudo make install

After howm is installed, you'll want to copy over some configuration files.

cp examples/sxhkdrc_* ~/.config/sxhkd
cp examples/howmrc ~/.config/howmrc

Then take a look at the example xinitrc for ideas on how to start howm.

Be sure to install cottage and sxhkd.

Commandline Arguments

howm -c ~/.config/howm/howmrc

Configuration

Configuration is done through the use of cottage. Any element in this structure can be changed using cottage. The syntax is as follows:

cottage -c config_var value

For example:

cottage -c bar_height 20

To override howm's default values at startup, cottage commands can be placed in a shell script and then executed by howm. Take a look at the example howmrc for ideas.

Note: When configuring colours in howmrc, enclose the colour in quotes, such as:

cottage -c border_focus "#343434"

Changing Socket Path

By default, howm will attempt to create a socket at /tmp/howm, this can be overwritten by setting the environment variable HOWM_SOCK. For example:

export HOWM_SOCK=/tmp/howm_test

Keybinds

Keybinds are now placed in multiple sxhkd files.

A keypress is bound to a call to cottage in the following form:

cottage -f func_name <args>

All of the available functions can be found here. Take a look at the example sxhkdrcs.

Scratchpad

The scratchpad is a location to store a single client out of view. When requesting a client back from the scratchpad, it will float in the center of the screen. This is useful for keeping a terminal handy or hiding your music player- only displaying it when it is really needed.

The size of the scratchpad's client is defined by SCRATCHPAD_WIDTH and SCRATCHPAD_HEIGHT.

Motions

For a good primer on motions, vim's documentation explains them well.

Please note: The modifier key that is OTHER_MOD needs to be held down whilst entering a motion.

Operators and motions are combined so that an operation can be performed on multiple things, such as clients or workspaces. The current supported motions are as follows:

Counts

Counts be applied to a motion, to make an operator affect multiple things. For example, you can add a 3 before a motion, meaning that the operator will affect 3 of the motions. The modifier that is used is defined by COUNT_MOD.

For example:

q2w

Will kill 2 workspaces (assuming the correct modifier keys are pressed and default keybindings are being used).

Operators

Operators perform an action upon one or more targets (identified by motions).

Implementation details for all operators can be found here.

Below are descriptions of each operator, the motions that they can perform an action upon and the mode that they work in (Note, all examples assume that the correct modifier keys have been pressed and use the default keymappings.):

q4c

The above command will kill 4 clients, closing the applications and removing them from the workspace.

qw

The above command will kill one workspace. This means that all clients on the current workspace will be killed.

j2c

The above command moves 2 clients down one place in the workspace's client list. If a client is moved past the last place, then it is wrapped around and placed at the start of the workspace's client list.

g1w

The above command will shrink the gaps of all windows on the current workspace by OP_GAP_SIZE.

g4c

The above command will shrink the gaps of 4 clients on the current workspace by OP_GAP_SIZE.

j3c

The above command will move the current focus down 3 clients.

d2c

The above command will cut 2 clients and place them onto the delete register stack. One use of the cut operation takes up one place on the stack.

Modes

A good primer on modes is available here.

Note: Modes used to be implemented in howm itself, but are now in the sxhkd configuration file.

In howm, modes are used to allow the same keys to be bound to multiple functions. Modes also help to logically separate what needs to be done to a window. The available modes are as follows:

Code Documentation

howm uses doxygen throughout the entire codebase. The generated documentation is available here.

Parsing Output

When debug mode is disabled, howm outputs information about its current state and the current workspace whenever something changes (such as adding a new window). When debug mode is enabled, information is outputted for each workspace (placed on a new line).

The format for the output is as follows:

Layout:Workspace:State:NumberofClients:MonitorIndex

An example output can be seen below:

2:1:0:1:0

The information outputted at the same time as the example above, but with debugging mode turned on is shown below:

2:1:0:1:0
2:2:0:0:0
2:3:0:0:0
2:4:0:0:0
2:5:0:0:0