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.

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.

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

• Select Widget in Client turns the pointer into a crosshair so you can click the matching widget in the target application.
• Select Children, Select Parents, Select Descendants and Select Ancestors expand the selection outward from whatever is already picked.
• Show Resource Box only opens with exactly one widget selected. It shows the widget's name and class path, its available normal resources, and any constraint resources. Select more than one widget and editres refuses to open it, because there is no single resource path left to show.

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:

• \n represents a newline in the value.
• \123 represents one byte whose value is octal 123.
• A backslash followed by a physical newline is removed.
• \\ represents one literal backslash.

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.

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.