API reference
Everything lives on the global oxwm table. Functions marked action return a value for oxwm.key.bind or oxwm.key.chord and do nothing until the key is pressed. Everything else is a setting that applies when the config loads.
Colors are hex strings like "#7aa2f7" or "0x7aa2f7", or numbers like 0x7aa2f7.
Core
Settings
| Function |
Default |
Description |
oxwm.set_terminal(cmd) |
"st" |
Command run by oxwm.spawn_terminal() |
oxwm.set_modkey(mod) |
"Mod4" |
Modifier for mouse move and resize |
oxwm.set_tags(names) |
"1" to "9" |
List of tag names, up to 12 |
oxwm.set_layout(name) |
"tiling" |
Layout that tags start in |
oxwm.set_tag_layout(tag, name) |
none |
Starting layout for one tag, counted from 1 |
oxwm.set_layout_symbol(name, symbol) |
see Layouts |
Text the bar shows for a layout |
oxwm.set_attach_method(name) |
"aside" |
Where new windows go: aside, top, bottom, above, below |
oxwm.set_floating_position(pos) |
"center" |
Where floating windows open |
oxwm.auto_tile(enabled) |
false |
Put a dragged tiled window back into the layout on drop |
oxwm.tiled_resize_mode(enabled) |
false |
Mod + right drag on a tiled window resizes the master area |
oxwm.autostart(cmd) |
none |
Run a command when oxwm starts |
The config written by oxwm --init sets the terminal to alacritty.
Actions
| Function |
Description |
oxwm.spawn(cmd) |
Run a shell command |
oxwm.spawn_terminal() |
Run the terminal |
oxwm.restart() |
Reload the config |
oxwm.quit() |
Exit oxwm |
oxwm.toggle_gaps() |
Turn gaps on or off |
oxwm.toggle_bar() |
Show or hide the bar |
oxwm.show_keybinds() |
Show the keybind overlay |
oxwm.set_master_factor(delta) |
Resize the master area by delta thousandths of the screen. In the scrolling layout, resize the focused window |
oxwm.inc_num_master(delta) |
Add or remove master windows |
oxwm.key
| Function |
Description |
oxwm.key.bind(mods, key, action) |
Bind one key press to an action |
oxwm.key.chord(steps, action) |
Bind a sequence of up to four key presses |
mods is a list of modifier names: Mod4, Mod1, Shift, Control. Each chord step is { mods, key }. Key names are listed under Keybindings.
oxwm.key.bind({ "Mod4", "Shift" }, "Q", oxwm.quit())
oxwm.key.chord({
{ { "Mod4" }, "Space" },
{ {}, "T" },
}, oxwm.spawn_terminal())
oxwm.client
All of these are actions on the focused window.
| Function |
Description |
oxwm.client.kill() |
Close the window |
oxwm.client.toggle_floating() |
Float or tile the window |
oxwm.client.toggle_fullscreen() |
Enter or leave fullscreen |
oxwm.client.focus_stack(dir) |
Focus the next (1) or previous (-1) window |
oxwm.client.move_stack(dir) |
Move the window down (1) or up (-1) the stack |
oxwm.layout
All of these are actions.
| Function |
Description |
oxwm.layout.set(name) |
Switch to a layout |
oxwm.layout.cycle() |
Switch to the next layout |
oxwm.layout.scroll_left() |
Scrolling layout: focus the window to the left |
oxwm.layout.scroll_right() |
Scrolling layout: focus the window to the right |
oxwm.layout.cycle_width(dir) |
Scrolling layout: step to the next (1) or previous (-1) width preset |
oxwm.layout.set_width(width) |
Scrolling layout: set the focused window’s width |
Layout names are tiling, dwindle, grid, monocle, scrolling and floating. The aliases tile, fib, fibonacci, scroll, float and normie also work.
Settings for the scrolling layout. A width of 1 or less is a share of the screen, and anything above 1 is pixels.
| Function |
Default |
Description |
oxwm.scroll.set_default_width(width) |
0.5 |
Width of new windows |
oxwm.scroll.set_width_presets(list) |
{ 1/3, 1/2, 2/3 } |
Widths used by cycle_width, up to 8 |
oxwm.scroll.set_indicator(enabled) |
true |
Show the minimap in the bar |
oxwm.scroll.set_indicator_width(px) |
0 |
Minimap width, 0 means four times the bar height |
oxwm.scroll.set_gesture_enabled(enabled) |
false |
Turn on touchpad swipes |
oxwm.scroll.set_gesture_fingers(n) |
3 |
Fingers for a swipe: 3, 4 or 5 |
oxwm.scroll.set_gesture_speed(x) |
2.0 |
Swipe speed multiplier |
oxwm.scroll.set_gesture_natural(enabled) |
false |
Reverse the swipe direction |
oxwm.tag
Tag indexes in this module count from 0.
Actions
| Function |
Description |
oxwm.tag.view(index) |
Show a tag |
oxwm.tag.view_next() |
Show the next tag |
oxwm.tag.view_previous() |
Show the previous tag |
oxwm.tag.view_next_nonempty() |
Show the next tag that has windows |
oxwm.tag.view_previous_nonempty() |
Show the previous tag that has windows |
oxwm.tag.move_to(index) |
Move the focused window to a tag |
oxwm.tag.toggleview(index) |
Add or remove a tag from the view |
oxwm.tag.toggletag(index) |
Add or remove a tag from the focused window |
Settings
| Function |
Default |
Description |
oxwm.tag.set_back_and_forth(enabled) |
false |
Viewing the current tag again goes back to the previous one |
oxwm.monitor
Actions
| Function |
Description |
oxwm.monitor.focus(dir) |
Focus the next (1) or previous (-1) monitor |
oxwm.monitor.tag(dir) |
Send the focused window to the next or previous monitor |
Settings
| Function |
Default |
Description |
oxwm.monitor.warp_cursor(enabled) |
false |
Move the pointer when focusing another monitor |
oxwm.monitor.warp_cursor_on_send(enabled) |
false |
Move the pointer along with a window sent to another monitor |
oxwm.border
| Function |
Default |
Description |
oxwm.border.set_width(px) |
2 |
Border width in pixels |
oxwm.border.set_focused_color(color) |
#6dade3 |
Border of the focused window |
oxwm.border.set_unfocused_color(color) |
#444444 |
Border of every other window |
oxwm.gaps
| Function |
Default |
Description |
oxwm.gaps.set_enabled(enabled) |
true |
Turn gaps on or off |
oxwm.gaps.enable() |
|
Same as set_enabled(true) |
oxwm.gaps.disable() |
|
Same as set_enabled(false) |
oxwm.gaps.set_inner(h, v) |
5, 5 |
Gap between windows |
oxwm.gaps.set_outer(h, v) |
5, 5 |
Gap at the screen edge |
oxwm.gaps.set_smart(enabled) |
false |
No outer gaps when a tag has one window |
oxwm.rule
| Function |
Description |
oxwm.rule.add(rule) |
Add a window rule |
Fields of rule:
| Field |
Type |
Description |
class |
string |
Substring of the window class |
instance |
string |
Substring of the window instance |
title |
string |
Substring of the window title |
floating |
boolean |
Open floating |
fullscreen |
boolean |
Open fullscreen |
tag |
integer |
Tag to open on, counted from 1 |
monitor |
integer |
Monitor to open on, counted from 0 |
focus |
boolean |
Switch to the window’s tag when it opens |
width |
number |
Width in the scrolling layout |
See Window rules.
oxwm.bar
| Function |
Default |
Description |
oxwm.bar.set_font(font) |
"monospace:size=10" |
Fontconfig pattern for the bar font |
oxwm.bar.set_position(pos) |
"top" |
top or bottom |
oxwm.bar.set_blocks(blocks) |
none |
List of blocks to show |
oxwm.bar.set_hide_vacant_tags(enabled) |
false |
Hide tags with no windows |
oxwm.bar.set_scheme_normal(fg, bg, underline) |
#bbbbbb, #1a1b26, #444444 |
Colors for empty tags |
oxwm.bar.set_scheme_occupied(fg, bg, underline) |
#0db9d7, #1a1b26, #0db9d7 |
Colors for tags with windows |
oxwm.bar.set_scheme_selected(fg, bg, underline) |
#0db9d7, #1a1b26, #ad8ee6 |
Colors for the selected tag |
oxwm.bar.set_scheme_urgent(fg, bg, underline) |
#f7768e, #1a1b26, #f7768e |
Colors for urgent tags |
oxwm.bar.block
Each constructor takes one table and returns a block for oxwm.bar.set_blocks.
| Function |
Extra fields |
oxwm.bar.block.ram(config) |
none. format takes {used} and {total} |
oxwm.bar.block.datetime(config) |
date_format |
oxwm.bar.block.shell(config) |
command |
oxwm.bar.block.static(config) |
text |
oxwm.bar.block.battery(config) |
charging, discharging, full, battery_name |
oxwm.bar.block.systray(config) |
none. Only color and underline are used |
Fields shared by all blocks:
| Field |
Type |
Description |
format |
string |
Text to draw, {} is the value |
interval |
integer |
Seconds between updates |
color |
color |
Text color |
underline |
boolean |
Draw a line under the block |
click |
string or table |
Command to run on click. As a table: { command, floating, bypass_rules } |
See Status bar for an example of each.
Command line
| Flag |
Description |
--init |
Write the default config to ~/.config/oxwm/config.lua |
--config PATH, -c PATH |
Use another config file |
--validate |
Check the config and exit |
--version, -v |
Print the version |
--help, -h |
Print help |
oxwm