Inspect and Tune X Toolkit Widgets Safely with editres

editres pops open the widget tree of a running X Toolkit application so you can test a resource change live before writing it anywhere. The examples target the installed editres 1.0.8 interface from the x11-utils package, version 7.7+6build2.

Allow about fifteen minutes. You need a running X11 desktop, an X Toolkit application that speaks the Editres protocol, and permission to connect to the same X display. No command here needs sudo. Wayland-native applications, and most non-X Toolkit applications, will not give editres a tree to inspect at all.

1. Check the installed program and display

Start with read-only checks. They confirm which binary is in use, which package supplied it, and whether the display variable is even set:

$ command -v editres
/usr/bin/editres
$ dpkg-query -W -f='${Package} ${Version}\n' x11-utils
x11-utils 7.7+6build2
$ printf 'DISPLAY=%s\n' "$DISPLAY"
DISPLAY=:0

Your display value will differ. editres reads DISPLAY to find the X server, and may also read XENVIRONMENT for a resource file. If DISPLAY is empty, launch it from the graphical session or set the display value using your desktop's normal X11 procedure. Do not copy another user's display value: X access control is a security boundary, not a formality.

Checkpoint: the command path is /usr/bin/editres, the package query returns a version, and DISPLAY names the X server that owns the target window.

2. Start editres and select the target

Launch it as your normal desktop user:

$ editres

The window shows a menu bar, a panner, a message area and the application widget tree. Choose Get Widget Tree. The pointer turns into a crosshair. Click any window belonging to the application you want to inspect.

The target has to understand the Editres protocol, which comes from the Athena Widget set and so is commonly available in Xaw applications. If it does not, editres reports the failure in its message area after a short delay. That is a protocol limitation, not a reason to retry with elevated privileges.

Checkpoint: a successful selection populates the tree with the target's widgets. An unsupported target leaves you with no usable tree, so stop there or pick an Xaw application instead.

3. Refresh widgets created later

The tree is a snapshot of whatever widgets existed at the moment you asked for it. Applications often create transient windows only after some action; a manual page window in xman, for instance, may not exist until its button is pressed.

Once you have opened the part of the application you need to change, choose Refresh Current Widget Tree. This asks the target to send its current hierarchy again. Skip the refresh and a missing widget is easy to mistake for an uneditable resource.

$ xman
# In xman: open the manual page window.
# In editres: choose Get Widget Tree, or Refresh Current Widget Tree.

Those comments describe GUI actions, not shell commands to paste in. Use the tree labels and the Show Widget Names, Show Class Names, Show Widget IDs or Show Widget Windows commands to work out which item you mean.

4. Select the exact widget and resource

The resource box starts with a restrictive name-and-dot specification. You can broaden it with class names, the star separator, Any Widget or Any Widget Chain. Broader matching hits more widgets, so keep the narrowest selector that solves the problem: this is the main spot where a quick visual experiment turns into an application-wide change.

5. Test a value without saving it

Pick a resource, type its value into the resource field, and select Apply. The value gets sent to matching widgets through an XtSetValues call, using the same syntax as an X resource file. The field must hold one logical line, with these escape forms:

Apply is a live experiment, not a guarantee about what happens at the next start-up. Some X Toolkit resources are effectively static once a widget is created, and a widget can reject or mishandle a value outright. The manual treats the result as suspect whenever a static resource is changed dynamically like this.

Warning: warn anyone using the target application before you apply an unfamiliar value. Applying can change a live window without asking the application to restart. To undo a harmless visual experiment, apply the original value again if you still know it; otherwise close and restart the target application, which clears the in-memory change but does not undo anything already saved.

6. Save a reviewed resource line

Do not press Save until the resource line and value are correct. Save appends the generated line to the current save file. If none is configured, editres prompts for one; use Set Save File first when you want an explicit destination, such as a personal file under your home directory.

Saving appends rather than replacing a file's contents, which makes the operation easy to repeat but can leave conflicting duplicate entries behind. Inspect the target file in another terminal and back it up first if it already holds settings you care about:

$ test -e "$HOME/.Xresources" && cp --preserve=all "$HOME/.Xresources" "$HOME/.Xresources.before-editres"
$ ls -l "$HOME/.Xresources" "$HOME/.Xresources.before-editres" 2>/dev/null

The backup is optional and stays unprivileged. The ls output should show both files if .Xresources already existed. Swap in the real path if you picked a different save file. To undo this before accepting the change, remove only the newly created backup, or restore the original with an explicit, reviewed copy. Do not overwrite a resource file blindly.

After saving, check the final lines before loading them into a resource manager:

$ tail -n 10 "$HOME/.Xresources"

Save and Apply does both actions at once. Treat it as two separate changes, one to the running application and one to a file, and use it only when you actually want both outcomes.

7. Load the saved resource deliberately

editres writes the resource line but does not take over your whole resource-management workflow. If your desktop uses xrdb, load the reviewed file with the command your session expects, then restart the target application so resources that are only read at creation time can take effect:

$ xrdb -merge "$HOME/.Xresources"
$ xclock

This merge changes the X server's resource database and can affect other X Toolkit applications, not just the one you were testing. Check the file first, or use a separate test file if you are unsure. To recover, restore the reviewed backup and merge that again, or remove only the entry you added and reload; a running application may still need restarting on top of that.

8. Understand the target application's safety boundary

An Xaw application can set its own editresBlock resource to restrict the protocol: all blocks every request, setValues blocks changes while leaving inspection open, and none allows everything. These resources belong to the target application, not to editres, and editres is itself an Xaw application, so it can be inspected or restricted too.

If the target allows inspection but refuses Apply, check whether it sets editresBlock: setValues. Do not weaken that setting just to make a test work; it may be a deliberate read-only boundary around state that should never change dynamically.

Done means