Explore Xt widget classes with viewres

You are staring at an X resource file trying to work out which widget class owns a setting, and viewres turns that guesswork into a browsable tree. Open it, walk the Athena Widget Set class hierarchy, and expand resource boxes for the classes you want to understand. This is a read-only inspection tool: it does not edit an Xt application or an X resource database.

Allow about ten minutes for a first look, assuming an X display is already available. You need the x11-utils package, an X server, and permission to connect to that display. No elevated privileges are normally required.

1. Check the installed command and display

This guide describes the installed Ubuntu package x11-utils 7.7+6build2. The local manual identifies the program as viewres 1.0.7. Confirm that the executable is present and that your shell has a display value:

$ command -v viewres
/usr/bin/viewres
$ printf '%s\n' "${DISPLAY:-<unset>}"
:0

Your display may use a different value, such as :1 or a remote display address. Do not copy :0 blindly. If the value is unset, start the command from the graphical session that owns the X server or configure access according to that session's normal policy.

Checkpoint: if command -v prints nothing, install x11-utils through your normal package-management process. If DISPLAY is set but the program reports that it cannot open the display, fix X access first. Running sudo viewres is not a general solution and can create an application with the wrong authorisation environment.

2. Open the full hierarchy

Start with the default view:

$ viewres

A window should appear with a tree whose default highest node is Object. The tree represents widget classes in the Athena Widget Set. Expanding a node reveals the resources that class adds when a widget is created, rather than listing every resource inherited from its parent.

The program is graphical, so a successful launch normally produces no useful terminal output. Keep the terminal open while you work. If the window does not appear, press Ctrl-C in that terminal to stop a process that is still waiting for the display connection, then inspect the display and X authorisation rather than changing files as root.

3. Start with a smaller tree

Use -top to choose the highest widget name shown. The manual's default is Object; supplying another name limits the display to that part of the hierarchy:

$ viewres -top Command

The argument is a widget name, not a shell path or a resource file. Choose a name that exists in the Athena hierarchy. If the resulting view is too narrow for the question you are asking, close it and rerun viewres without -top. This option changes what is displayed, not the widget toolkit installed on the system.

Checkpoint: the window should now begin at the class you requested. If it does not, read the name as a case-sensitive class or variable label and try the complete spelling.

4. Choose useful labels and orientation

Two command-line options make a crowded tree easier to read:

$ viewres -variable -vertical

-variable labels nodes with the widget variable names used in header files. This can distinguish classes that share a class name, such as Text. -vertical lays the tree from top to bottom instead of left to right.

The same choices are available after launch. In the View menu, choose Show Variable Names or Show Class Names, then choose Layout Vertical or Layout Horizontal. The menu is useful when you are comparing the class name used in an Xt resource with the variable name used by code.

5. Inspect resources for selected classes

To inspect one class, click Button2, normally the middle mouse button, on its node. Its resource display is shown directly. Alternatively, click Button1 to toggle the node in the selection list, then choose Show Resource Boxes from the View menu.

Selection is a state, not a one-shot command. Clicking a selected node with Button1 removes it again. This is the common distraction trap: if a resource box does not appear, check that the node is selected before looking for a toolkit problem.

For several related classes, use the Select menu. Select Children adds immediate children, while Select Descendants adds all lower descendants. Select Parent and Select Ancestors move upwards. Select Has Resources narrows the selection to nodes that add regular or constraint resources. After selecting, use Show Resource Boxes; use Hide Resource Boxes when the window becomes too large.

6. Reset the view or exit cleanly

Use Unselect All when you want to begin a new comparison. Invert All is useful for reversing a deliberate selection, but it can select many nodes in a large tree, so expect the display to become busy. Select Shown Resource Boxes finds the currently expanded resource boxes so that you can hide them together.

Close the session with the window's normal quit control or choose the application's quit action. The documented action is:

Quit()

That notation describes an Xt action for translations or a toolkit binding; it is not a shell command. Do not paste it at a prompt expecting a Linux executable. Exiting viewres discards its current selections and resource-box display, but it does not alter the classes, headers or resource files being inspected.

7. Verify what you learned

Use the class name shown in the relevant node when checking an Xt resource specification. Remember what viewres is showing: the class hierarchy of the Athena Widget Set and the resources each class adds. It is not a live inspector of an arbitrary running application, and it does not prove that another toolkit, such as a Motif or GTK application, uses the same hierarchy.

If you need to repeat the investigation, compare these two read-only views:

$ viewres
$ viewres -variable -vertical

The first uses class names and a left-to-right layout by default. The second uses variable names and a top-to-bottom layout. A difference in labels or direction is expected; the underlying widget classes and their relationships are the subject of the inspection.

Done means