Objects

The state of herbstluftwm can interactively be introspected and modified via the object system. Similarly to a file system, the objects are organized in a tree whose root object has the following entries:

autostart:

string global_path = globalAutostart: Path of the system-wide autostart, used as a fallback.
int last_status = 0: the exit status of the last autostart run. if the autostart is still running, then this status corresponds to the exit status of the previous autostart invocation.
string path = autostartFromCmdLine: Custom path to the user’s autostart path. If it is empty, then the autostart in $XDG_CONFIG_HOME or $HOME is used.
uint pid = 0: the process id of the last autostart invocation. Even if the autostart is not running anymore, its pid is still present here.
bool running = false: whether the autostart process (with pid) is still running.

clients:

The managed windows. For every (managed) window id there is an entry here.

dragged: the object of a client which is currently dragged by the mouse, if any. See the documentation of the mousebind command for examples. For attributes and children, see clients.focus
focus: the focused client (only exists if a client is focused). a managed window
- string class: the class of it (second entry in WM_CLASS)
- Rectangle content_geometry: the geometry of the application content, that is, not taking the decoration into account. Also, this is the last window geometry that was reported to the client application.
- bool decorated = true: whether window border and title are drawn
- Rectangle decoration_geometry: the geometry of the client, taking the window decoration into account. The position is the global window position, that is, relative to the top left corner of the entire screen
- bool ewmhnotify = true: if the client is told about its state via ewmh
- bool ewmhrequests = true: if ewmh requests are permitted for this client
- bool floating = false: whether this client is set as a (single-window) floating client. If set, the client is floated above the tiled clients.
- bool floating_effectively = false: whether this client is in the floating state currently. This is the case if the client’s tag is set to floating mode or if the client itself is set as floating. Its value is also indicated via the X11 properties HLWM_FLOATING_WINDOW and HLWM_TILING_WINDOW.
- Rectangle floating_geometry = 0: the geometry of the client content if the client is in floating mode. The position is relative to the monitor and does not take the window decoration into account.
- bool fullscreen = false: whether this client covers all other windows and panels on its monitor.
- string instance: the instance of it (first entry in WM_CLASS)
- regex keymask = "": A regular expression that is matched against the string representation of all key bindings (as they are printed by list_keybinds). While this client is focused, only bindings that match the expression will be active. Any other bindings will be disabled. The default keymask is an empty string (), which does not disable any keybinding.
- regex keys_inactive = "": A regular expression that describes which keybindings are inactive while the client is focused. If a key combination is pressed and its string representation (as given by list_keybinds) matches the regex, then the key press is propagated to the client.
- bool minimized = false: whether this client is minimized (also called iconified).
- int pgid = -1
- int pid = -1: the process id of it (-1 if unset).
- bool pseudotile = false: if activated, the client always has its floating window size, even if it is in tiling mode.
- bool sizehints_floating = true: if sizehints for this client should be respected in floating mode
- bool sizehints_tiling = false: if sizehints for this client should be respected in tiling mode
- string tag: the name of the tag it’s currently on.
- string title = "": its window title
- bool urgent = false: the urgency state (also known as: demands attention)
- bool visible = visible_already: whether this client is rendered currently
- string winid = "": its window id (as a hexadecimal number with 0x prefix)
- parent_frame: the frame contaning this client if the client is tiled. For attributes and children, see tags.focus.tiling.root

monitors:

Every monitor is a rectangular part of the screen on which a tag is shown. These monitors may or may not match the actual outputs. This has an entry INDEX for each monitor with index INDEX.

uint count
by-name: This has an entry name for every object with the given name. If an object has an empty name then it is not listed here.
focus: the focused monitor. The monitor is a rectangular part on the screen that holds precisely one tag at a time. The pad attributes reserve space on the monitor’s edge for panels, so this space (given in number of pixels) is never occupied by tiled clients.
- Rectangle geometry = rect_: the outer geometry of the monitor
- uint index = 0: the monitor’s index (starts at index 0)
- bool lock_tag = false: if activated, then it it is not possible to switch this monitor to a different tag.
- string name = "": the monitor’s name (can be empty)
- int pad_down = 0: space for panels at the monitor’s lower edge
- int pad_left = 0: space for panels at the monitor’s left edge
- int pad_right = 0: space for panels at the monitor’s right edge
- int pad_up = 0: space for panels at the monitor’s upper edge
- string tag: the name of the tag viewed here

panels:

For every panel window, there is an entry with the panel’s window id here.

uint count
0xWindowID: a panel is an unmanaged window that reserves space at the edge of the monitor it is on. The space depends on the _NET_WM_STRUT defined by the panel. If it is however not defined explicitly, then the amount of reserved space is inferred from the window geometry.
- string class: the window class (second entry of WM_CLASS)
- Rectangle geometry: the size and position of the window
- string instance: the window instance (first entry of WM_CLASS)
- WindowID winid = winid: the ID of the panel window

settings:

This has an attribute for each setting. Many settings are wrappers around attributes and only exist for compatibility.

bool always_show_frame = false
bool auto_detect_monitors = false
bool auto_detect_panels = true
bool default_direction_external_only = false
LayoutAlgorithm default_frame_layout = vertical
bool focus_crosses_monitor_boundaries = true
bool focus_follows_mouse = false
bool focus_stealing_prevention = true
int frame_active_opacity = 100
color frame_bg_active_color = black
color frame_bg_normal_color = black
bool frame_bg_transparent = false
color frame_border_active_color = red
color frame_border_inner_color = black
int frame_border_inner_width = 0
color frame_border_normal_color = blue
int frame_border_width = 2
int frame_gap = 5
int frame_normal_opacity = 100
int frame_padding = 0
int frame_transparent_width = 0
bool gapless_grid = true
bool hide_covered_windows = false
uint monitors_locked = 0
int mouse_recenter_gap = 0
int pseudotile_center_threshold = 10
bool raise_on_click = true
bool raise_on_focus = false
bool raise_on_focus_temporarily = false
bool smart_frame_surroundings = false
bool smart_window_surroundings = false
int snap_distance = 10
int snap_gap = 5
bool swap_monitors_to_get_tag = true
bool tabbed_max = true: if activated, multiple windows in a frame with the max layout algorithm are drawn as tabs.
string tree_style = "*| +`--."
bool update_dragged_clients = false
bool verbose = false
color window_border_active_color
color window_border_inner_color
int window_border_inner_width
color window_border_normal_color
color window_border_urgent_color
int window_border_width
int window_gap = 0
string wmname = herbstluftwm

tags:

The tags (or virtual desktops or workspaces). This contains an entry index for each tag with the given index.

uint count
by-name: For attributes and children, see monitors.by-name
focus: the object of the focused tag, equivalently, the tag on the focused monitor.
- int client_count: the number of clients on this tag
- int curframe_wcount: number of clients in the selected frame
- int curframe_windex: index of the focused client in the selected frame
- bool floating = false: if the entire tag is set to floating mode
- bool floating_focused = false: if the floating layer is focused (otherwise the tiling layer is)
- int frame_count: the number of frames on this tag
- uint index = 0: index of this tag (the first index is 0)
- string name = name_: name of the tag (must be non-empty)
- int urgent_count: the number of urgent clients on this tag
- bool visible = false: if this tag is shown on some monitor
- focused_client: For attributes and children, see clients.focus
- tiling:
  - focused_frame: The focused frame (leaf) in this frame tree. For attributes and children, see tags.focus.tiling.root
  - root can be a frame leaf.
    
    LayoutAlgorithm algorithm
    
    int client_count
    
    string index
    
    int selection
  - root can be a frame split.
    
    decimal fraction
    
    string index
    
    int selection
    
    SplitAlign split_type
    
    0 can be a frame leaf. For attributes and children, see tags.focus.tiling.root
    
    0 can be a frame split. For attributes and children, see tags.focus.tiling.root
    
    1 can be a frame leaf. For attributes and children, see tags.focus.tiling.root
    
    1 can be a frame split. For attributes and children, see tags.focus.tiling.root

theme:

inner_color/inner_width
      ╻        outer_color/outer_width
      │                  ╻
      │                  │
┌────╴│╶─────────────────┷─────┐ ⎫ border_width
│     │      color             │ ⎬ + title_height
│  ┌──┷─────────────────────┐  │ ⎭ + padding_top
│  │====================....│  │
│  │== window content ==....│  │
│  │====================..╾──────── background_color
│  │........................│  │
│  └────────────────────────┘  │ ⎱ border_width +
└──────────────────────────────┘ ⎰ padding_bottom

Setting an attribute of the theme object just propagates the value to the respective attribute of the tiling and the floating object.

color background_color = black: color behind window contents visible on resize
uint border_width = 0: the base width of the border
color color = black: the basic background color of the border
color inner_color = black: color of the inner border
uint inner_width = 0: width of the border around the clients content
color outer_color = black: color of the outer border
uint outer_width = 0: width of an border close to the edge
uint padding_bottom = 0: additional border width on the bottom
uint padding_left = 0: additional border width on the left
uint padding_right = 0: additional border width on the right
uint padding_top = 0: additional border width on the top
string reset: writing this resets all attributes to a default value
bool tight_decoration = false: specifies whether the size hints also affect the window decoration or only the window contents of tiled clients (requires enabled sizehints_tiling)
color title_color = black
font title_font = fixed
uint title_height = 0
active: configures the decoration of the focused client.
- color background_color = black: color behind window contents visible on resize
- uint border_width = 0: the base width of the border
- color color = black: the basic background color of the border
- color inner_color = black: color of the inner border
- uint inner_width = 0: width of the border around the clients content
- color outer_color = black: color of the outer border
- uint outer_width = 0: width of an border close to the edge
- uint padding_bottom = 0: additional border width on the bottom
- uint padding_left = 0: additional border width on the left
- uint padding_right = 0: additional border width on the right
- uint padding_top = 0: additional border width on the top
- string reset: writing this resets all attributes to a default value
- bool tight_decoration = false: specifies whether the size hints also affect the window decoration or only the window contents of tiled clients (requires enabled sizehints_tiling)
- color title_color = black
- font title_font = fixed
- uint title_height = 0
floating: behaves analogously to tiling.
- color background_color = black: color behind window contents visible on resize
- uint border_width = 0: the base width of the border
- color color = black: the basic background color of the border
- color inner_color = black: color of the inner border
- uint inner_width = 0: width of the border around the clients content
- color outer_color = black: color of the outer border
- uint outer_width = 0: width of an border close to the edge
- uint padding_bottom = 0: additional border width on the bottom
- uint padding_left = 0: additional border width on the left
- uint padding_right = 0: additional border width on the right
- uint padding_top = 0: additional border width on the top
- string reset: writing this resets all attributes to a default value
- bool tight_decoration = false: specifies whether the size hints also affect the window decoration or only the window contents of tiled clients (requires enabled sizehints_tiling)
- color title_color = black
- font title_font = fixed
- uint title_height = 0
- active: configures the decoration of the focused client. For attributes and children, see theme.active
- normal: the default decoration scheme for clients. For attributes and children, see theme.active
- urgent: configures the decoration of urgent clients. For attributes and children, see theme.active
fullscreen: configures clients in fullscreen state. For attributes and children, see theme.floating
minimal: configures clients with minimal decorations triggered by smart_window_surroundings. For attributes and children, see theme.floating
normal: the default decoration scheme for clients. For attributes and children, see theme.active
tiling: configures the decoration of tiled clients, setting one of its attributes propagates the respective attribute of the active, normal and urgent child objects. For attributes and children, see theme.floating
urgent: configures the decoration of urgent clients. For attributes and children, see theme.active

types:

This lists the types that are used for attributes and command arguments.

bool: Type representing boolean values, i.e. an on or off state, with aliases true and false. When writing to a boolean value, one can also specify toggle in order to alter its value.
- string fullname: the full and unique name of this type
- string shortname: A short (one-character long) name of this type which is used in the output of the attr command
color: Type representing colors. A color can be defined in one of the following formats:
1. #RRGGBB where R, G, B are hexidecimal digits (0-9, A-F), and RR, GG, BB represent the values for red, green, blue.
2. #RRGGBBAA represents a color with alpha-value AA. The alpha value 00 is fully transparent and FF is fully opaque/intransparent.
3. a common color name like red, blue, orange, etc. For attributes and children, see types.bool
decimal: Fixed precision decimal numbers, e.g. 0.34. For attributes and children, see types.bool
font: A font specification (font family with modifiers regarding size, weight, etc.) in one of the following formats:
- Fontconfig description. This supports antialiased fonts, for example:
  - Dejavu Sans:pixelsize=12
  - Bitstream Vera Sans:size=12:bold
- X logical font description (XLFD), as provided by the xfontsel tool. No antialiasing is supported here, but this is usually superior for bitmap fonts. For example:
  - -*-fixed-medium-r-*-*-13-*-*-*-*-*-*-* for a standard bitmap font available on most systems. For attributes and children, see types.bool
int: Type representing signed integers. When overwriting an integer, you can increase or decrease its value relatively by writing +=N or -=N where N is an integer. So for example, writing +=3 to an attribute increases its value by 3. For attributes and children, see types.bool
names: A fixed set of names, depending on the context, e.g. names of layout algorithms or the split type of a non-leaf frame (which is only horizontal or vertical). For attributes and children, see types.bool
rectangle: A rectangle on the screen consisting of a size and the position on the screen. The format is WxH+X+Y where W is the width, H is the height, and X and Y are the coordinates of the top left corner of the rectangle: X is the number of pixels to the left screen edge and Y is the number of pixels to the top screen edge. (if X or Y is negative, then the + turns into -). For example: 800x600+800+0 or 400x200-10+30. For attributes and children, see types.bool
regex: A POSIX extended regular expression. Note that when passing a regex on the command line, additional quoting can be necessary. For explanations and examples, see section 9.4.6 of the documentation: https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04_06. For attributes and children, see types.bool
string: Type representing normal text. For attributes and children, see types.bool
uint: Type representing unsigned (i.e. non-negative) integers. When overwriting an integer, you can increase or decrease its value relatively by writing +=N or -=N where N is an integer. For attributes and children, see types.bool
windowid: The window id is the number of a window. This can be a managed window (i.e. client) or an unmanaged window (e.g. a panel, a menu, or a desktop window). The default format is 0xHEX where HEX is a hexadecimal number (digits 0-9 and a-f) but it can also be specified in the decimal system (base 10), or as an octal number (with prefix 0 and base 8). When a window id is printed, it is always printed in the 0xHEX format and without any leading zeroes. For attributes and children, see types.bool

watchers:

uint count: the number of attributes that are watched