Inspect Openbox Window Properties with obxprop

You will finish with a repeatable way to inspect an X window and read the Openbox properties used by application matching rules. You will also be able to limit the output to the properties you actually need, without changing the window or Openbox configuration.

Allow 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 the Debian package version 3.6.1-12build5. This is an inspection tool: it does not require 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 troubleshooting notes: another Openbox build may format diagnostics differently.

2. Confirm that the X display is reachable

obxprop reads properties through X. 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 their values, although the first twenty lines will vary with the desktop and running applications. Piping to head only limits what is displayed; obxprop still performs a read-only query.

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 when you know its value:

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

A message such as "cannot open display" means that 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 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 then 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 intend to inspect.

Use the complete 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 user-defined application rules. The values are more useful than a window title because titles commonly change 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 can differ between tools, so obtain it from the X diagnostic tool already used on your system. 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 place untrusted text into an unquoted command line. Quoting prevents whitespace and shell metacharacters from changing how the command is parsed, although 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 reduce noise. This is 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 exposed by the window. 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 that the window provides it:

$ obxprop --id "$window_id" WM_NAME

obxprop is similar to xprop, but its purpose includes showing UTF-8 strings as text. This can make non-ASCII window names easier to read. It does not change the encoding stored by the application and it does not rename the window.

6. Diagnose failures without changing state

Use the failure category to choose the next check:

• 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 want the root or desktop window.
• Bad or stale ID: obtain a fresh ID and test the same live window interactively.
• Missing Openbox property: inspect the full output and confirm that 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 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.