Inspect Openbox Window Properties with obxprop

An Openbox rule refuses to match, and the window title you copied is not what Openbox matches on: obxprop shows the real values. You will inspect an X window and read the Openbox properties used by application matching rules, and limit the output to just the properties you need, without changing the window or the Openbox configuration.

• Time: about ten minutes.
• You need: an X11 session, the obxprop command from Openbox, and a window you can safely select. The examples use Openbox 3.6.1-12build5, installed here as Debian package version 3.6.1-12build5.
• Safe to run: this is an inspection tool. It does not need root and it does not edit configuration.

1. Check the installed command

Start with the executable and its local help. These are ordinary, read-only commands:

$ command -v obxprop
/usr/bin/obxprop
$ dpkg-query -W -f='${Package} ${Version}\n' openbox
openbox 3.6.1-12build5
$ obxprop --help
Usage: obxprop [OPTIONS] [--] [PROPERTIES ...]

Options:
    --help              Display this help and exit
    --display DISPLAY   Connect to this X display
    --id ID             Show the properties for this window
    --root              Show the properties for the root window

The installed help includes --root, and the manual describes the same window-property operation. Keep the version check in your troubleshooting notes: a different Openbox build may format diagnostics differently.

2. Confirm the X display is reachable

obxprop reads properties through X, so it needs a usable display connection, normally supplied by the DISPLAY environment variable:

$ printf 'DISPLAY=%s\n' "${DISPLAY:-<unset>}"
DISPLAY=:0
$ obxprop --root | head -20

The output is host-specific: you should see property names followed by values, though the first twenty lines vary with the desktop and running applications. Piping to head only limits what is displayed; obxprop still runs a read-only query underneath.

If the variable is unset or the connection fails, do not guess a display number. Run the command inside the graphical session, or pass the display explicitly once you know its value:

$ obxprop --display :0 --root | head -20

A message such as "cannot open display" means the display name, X authority, session or transport is wrong. It is not fixed by running obxprop as root; root can have a different authentication environment and may make the diagnosis less clear.

3. Select a window interactively

With no --id, obxprop asks you to choose a window by clicking it. Run it from a terminal in the same X session:

$ obxprop

Move the pointer to the target window and click. The command prints that window's properties and exits. Select the application window itself, not a panel, desktop background or terminal decoration, unless that is what you actually want to inspect.

Use the full output when you are discovering a rule. Look especially for _OB_APP_NAME, _OB_APP_CLASS, _OB_APP_ROLE and _OB_APP_TYPE. Openbox uses these values when matching windows against your application rules, and they are more reliable than a window title, which commonly changes between documents or sessions.

4. Query a known window by ID

Interactive selection is convenient, but a repeatable diagnostic can pass a window identifier with --id. Supply the identifier in the form accepted by your X tooling:

$ obxprop --id WINDOW_ID

Replace WINDOW_ID with the real identifier, do not paste the placeholder literally. The manual does not define a command for discovering IDs, and identifier formats differ between tools, so get it from whatever X diagnostic tool you already use. If the ID is stale or belongs to a destroyed window, obxprop cannot inspect it; select the live window again.

If a shell variable holds the value, quote it as a single argument:

$ window_id='0x01200007'
$ obxprop --id "$window_id"

Do not put untrusted text into an unquoted command line. Quoting stops whitespace and shell metacharacters from changing how the command is parsed, though it cannot make an invalid X identifier valid.

5. Filter the output to the useful properties

Pass one or more property names after the options to cut the noise, useful when checking a rule or recording a small diagnostic:

$ obxprop --id "$window_id" _OB_APP_NAME _OB_APP_CLASS _OB_APP_ROLE _OB_APP_TYPE

The names must match the properties the window actually exposes. If a requested property is absent, the result may be empty or omit useful information: that is evidence about this particular window, not proof that Openbox is broken.

For a quick UTF-8 check, query a user-facing property by its exact name once you have confirmed the window provides it:

$ obxprop --id "$window_id" WM_NAME

obxprop is similar to xprop, but it is built to show UTF-8 strings as text, which can make non-ASCII window names easier to read. It does not change the encoding the application stores, and it does not rename the window.

Common traps

• Cannot open display. Check DISPLAY, the X session and X authentication. Retry from the graphical session before considering any privilege change.
• No window selected. Rerun without --id and click a visible application window. Avoid clicking the desktop unless you actually want the root or desktop window.
• Bad or stale ID. Get a fresh ID and test the same live window interactively.
• Missing Openbox property. Inspect the full output and confirm the selected client sets the property. A transient or toolkit-specific window may not expose every field.

There is no undo step, because every example here only reads X properties. Do not edit rc.xml, restart Openbox or kill a window while you are still identifying the correct values. If you later change an Openbox matching rule, keep a backup and retain the previous rule so you can restore it after testing.