News Migration Tutorial Objects herbstluftwm(1) herbstclient(1)

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:

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. (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)

    • 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 floated above the tiled clients.

    • 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. (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 maynot match the actual outputs. This has an entry INDEX for each monitor withindex 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

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

  • uint default_frame_layout = 0

  • 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

  • int 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

  • 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 (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 (see clients.focus)

    • tiling

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

  • uint border_width = 0

  • color color = black

  • color inner_color = black

  • uint inner_width = 0

  • color outer_color = black

  • uint outer_width = 0

  • uint padding_bottom = 0

  • uint padding_left = 0

  • uint padding_right = 0

  • uint padding_top = 0

  • string reset writing this resets all attributes to a default value

  • bool tight_decoration = false

  • color title_color = black

  • font title_font = fixed

  • uint title_height = 0

  • active : configures the decoration of the focused client.

    • color background_color = black

    • uint border_width = 0

    • color color = black

    • color inner_color = black

    • uint inner_width = 0

    • color outer_color = black

    • uint outer_width = 0

    • uint padding_bottom = 0

    • uint padding_left = 0

    • uint padding_right = 0

    • uint padding_top = 0

    • string reset writing this resets all attributes to a default value

    • bool tight_decoration = false

    • color title_color = black

    • font title_font = fixed

    • uint title_height = 0

  • floating : behaves analogously to tiling.

    • color background_color = black

    • uint border_width = 0

    • color color = black

    • color inner_color = black

    • uint inner_width = 0

    • color outer_color = black

    • uint outer_width = 0

    • uint padding_bottom = 0

    • uint padding_left = 0

    • uint padding_right = 0

    • uint padding_top = 0

    • string reset writing this resets all attributes to a default value

    • bool tight_decoration = false

    • color title_color = black

    • font title_font = fixed

    • uint title_height = 0

    • active : configures the decoration of the focused client. (see theme.active)

    • normal : the default decoration scheme for clients. (see theme.active)

    • urgent : configures the decoration of urgent clients. (see theme.active)

  • fullscreen : configures clients in fullscreen state. (see theme.floating)

  • minimal : configures clients with minimal decorations triggered by smart_window_surroundings. (see theme.floating)

  • normal : the default decoration scheme for clients. (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. (see theme.floating)

  • urgent : configures the decoration of urgent clients. (see theme.active)

watchers

  • uint count the number of attributes that are watched