X Application Software Engineering:
Debugging X Toolkit Resources with editres

by Kenton Lee

Published in The X Journal, November, 1994.
Copyright © 1994 Kenton Lee. All rights reserved.

Key words: X Window System, X11, Motif widgets, editres, X Toolkit widget resources, programming.

Abstract

Table Of Contents

1. Introduction
2. What is editres?
3. editres vs. User Interface Management Systems
4. editres Feature Review
   1. Examining the Widget Hierarchy
   2. Editing Widget Resources
5. Using editres During Software Development
   1. Checking the Widget Hierarchy
   2. Widget Layouts and Geometries
   3. Editing Non-Geometry Resources
6. Widget Developers and editres
7. End Users and editres
8. Supporting editres
9. Limitations of editres
10. Conclusion
11. References

Introduction

In this issue, I will discuss one of my favorite tools: editres. The X Consortium developed editres and included its source code with the X11R5 and X11R6 distributions. editres provides some very powerful features, some of which are found nowhere else.

The X Consortium distributions include a UNIX manual page for editres.[1] I recommend that you read the manual page for a complete description of editres' functionality and syntax. In this column, I will briefly review the major features of editres, then focus ways that I use editres in my application development work.

What is editres?

editres provides three major features:

1. It retrieves the widget instance hierarchy from your X client and displays it graphically.
2. It allows you to change widget resources dynamically and interactively. When you change a widget resource, you immediately see the results. You can repeatedly change resources without having to recompile or re-start your X client.
3. It does not require a special development environment. editres can interact with any X client on your screen (if it supports the editres protocol, more on this later).

In this article we will study some examples of editres in use. We will also discuss the meaning of that caveat about the editres protocol.

editres vs. User Interface Management Systems

UIMS for the X Toolkit typically contain four major functional areas:

1. specifying hierarchies of widget instances
2. specifying widget resources
3. specifying widget callback functions and event handlers
4. connecting widget inputs and outputs to the non-GUI part of your application program

In many ways, the limited scope of editres is beneficial. You can use editres along side your favorite UIMS and application development tools. editres will not interfere with these. And, as we shall see, widget resources are a very important aspect of X Toolkit applications.

editres Feature Review

Examining the Widget Hierarchy

You can ask editres to display the widget instance name, widget class name, widget ID, or window ID for any of the widgets in the graph.

If the widget names do not provide enough information for you, editres provides two features for matching widgets in the tree graph with those displayed by the X client:

1. The "Select Widget in Client" menu item allows you to mouse on any widget in the X client. The corresponding node in the editres tree graph highlighted. The widget is also "selected", so that its resources can be edited (see below).
2. The "Flash Active Widgets" menu item allows you to select one or more widgets in the editres tree graph. The corresponding widgets in the X client are (temporarily) shown in a blinking highlight color.

Editing Widget Resources

An alternate method for changing widget resources is to select exactly one widget in the editres graph. The "Show Resource Box" function will popup a large dialog box with several features. One section of the dialog box lists all the valid resources for that particular widget. You can select any resource from the list and change its value. Other commands available in the dialog box allow you to save your edits, for use in an app-defaults or .Xdefaults file.

Using either technique to change your resources, the changes are made when you hit the apply button on the dialog box. The "Set Resource" method has the advantage of applying to all selected widgets, even if they have different types. The "Show Resource Box" method, on the other hand, allows you to select resource names from a dialog box, thus avoiding one common source of syntax errors.

Using editres During Software Development

X Toolkit application development can be broken down into four major steps:

1. specifying the widget hierarchy
2. specifying widget resources
3. specifying widget callback functions
4. repeating until you get it right

Checking the Widget Hierarchy

I often try to modify my widget layouts by inserting new manager widgets at various places in the hierarchy. More than once, I have neglected to change the parent specification some of the widgets. The result is an unexpected widget layout, such as widgets missing or placed in incorrect locations. A side effect is that resource specifications in the application's app-defaults file may no longer work properly.

Errors like the above are sometimes difficult to diagnose without editres. With editres, on the other hand, I can quickly display the widget tree and scroll to the area of interest using "Select Widget in Client". Errors in the hierarchy can now be easily identified.

Widget Layouts and Geometries

When creating a widget layout, you usually have to work with a number of different variables:

• widget hierarchy (discussed in the previous section)
• parent widget resources (that control the widget's layout policy)
• child widget resources (sizes, positions, resize policy, constraints)

Let's look at some editres examples in detail. The first problem is usually to just identify widget sizes and positions. In many cases, the graphics on your screen may not directly correspond to widget sizes and positions. Two editres techniques can tell you the exact widget sizes and positions.

The simplest technique is to use the "Flash Active Widgets" feature to temporarily show the boundaries of widgets selected in the editres tree graph.

If you need more time to study the widgets than the flashing feature allows, you can permanently mark a widget's size and position by setting its background color resource to the color of your choice (editres accepts string color names). By setting a parent widgets background color to one color and its children to other colors, for example, you can quickly see how the parent is laying out its children.

Once you have identified your widget geometries, you can easily try different resource settings to see how they affect the widget layout. If your parent widget supports different layout styles, you can try several of those to see what happens. You can also try changing child widget resources (such as size and position values or constraints).

One area where many rapid iterations are especially useful is to set numerical resources. You might, for example, have some position (x and y values) resources hard coded so that different parts of your user interface are aligned (usually not a great idea, but sometimes necessary). You can easily iterate with editres to find the correct x and y values.

Editing Non-Geometry Resources

Frequently, minor changes to your user interface can cause significant usability improvements. In some cases, these are simple changes to resource values, such as label strings, bitmaps, colors, fonts, border widths, etc. Using editres, you can quickly iterate through possible combinations.

If your organization uses non-programming user interface specialists, you might try teaching them to use editres to prototype and/or tune user interfaces.

Widget Developers and editres

Obviously, editres is a simple and powerful way to test a widget's "set values" method. With editres, you can rapidly test different resource settings.

You can also use editres to test a widget's geometry-related resources. Composite widgets have a "geometry manager" method that responds to child widget requests for new sizes and/or positions. You can easily test this method by using editres to change these resources in the child widget.

All widgets have a "resize" method that is called when the parent widget changes the size of a child widget. You can test this method by using a parent widget that always honors child requests for new sizes. Then, use editres to change the child size and see how it responds to the resultant resize.

Thorough testing of a widget's methods requires the testing of all permutations of inputs. editres allows you to reproduce most cases very quickly.

End Users and editres

With editres, however, end users can make some useful changes. The first change they would probably like to make is to change the colors of a client to a scheme that is more comfortable to their eyes. With editres, end users can easily use the "Select Widget In Client" and "Popup Resource Box" features to change the colors and save the necessary resources to a resource file.

If they are comfortable with X font specifications, they can change fonts, too. I suspect that few users are interested in changing more than color and font resources, but those that are will surely find that editres is a very useful tool.

One problem with this approach, however, is that end users cannot override resources that the client has hard coded via resource files. editres, on the other hand, can override these resources. Since most popular X clients specify their colors and fonts in resources files rather than in their code, this limitation probably will not confuse many users.

Supporting editres

The Athena widget (Xaw) library in X11R5 and X11R6 supports the editres protocol by default. While the basic Motif 1.2 library distributed by OSF does not support editres by default, many commercial versions of Motif do support editres. If your widget set does not contain built in support for editres, you can add it by linking your X client with the X Consortium's Xmu library (X11R5 or later) and adding these two lines of code:

#include <X11/Xmu/Editres.h>
XtAddEventHandler(shell, (EventMask)0, True,
    (XtEventHandler)_XEditResCheckMessages, 0);

When linking, you should specify the Xmu library after your widget set and before the X Toolkit library, e.g.:

cc client.c -lXm -lXmu -lXt -lX11

Limitations of editres

editres does not fully work with gadgets (non-widget X Toolkit objects). Gadgets will appear correctly in the editres tree graph, but editres cannot set resource values for gadgets.

editres does not work properly with subresources. Some widgets (such as the Athena and the Motif text widgets) create hidden sub-widgets with resources that editres cannot identify.

editres cannot change resources that cannot be represented as strings, i.e., for which the application and/or widget set have not registered a string-to-resource converter. This is the same limitation that prohibits certain resources from being set in resource files. The most common problem resources are those that take widget ID's, e.g., some constraint resources for form widgets.

A related resource problem is that certain widget resources can be set only when the widgets are created. Any new values supplied via editres will be ignored. (The new values would also be ignored if the X client set new values via XtSetValues().)

One problem with the way editres sets resource values is that they are some times not immediately processed by the X client. You can usually help the client along by forcing it to use the new resource values. Resizing the client will force it to read size, position, and constraint resources. Generating exposures (e.g., by iconifying and de-iconifying the client window) will force it to read graphical resources before it redraws the window.

One feature that has been proposed for editres, but not yet implemented, is the ability to report the current values of widget resources. For various reasons, this is a difficult feature to completely implement. You currently must view the results in your client.

editres can give unpredictable results if some of your widgets are not mapped and/or managed. The "Select Widget in Client" function will sometimes select an unmanaged widget located in the same position as the desired widget. Conversely, if a widget is unmanaged or unmapped, the "Flash Active Widget" function will show report the region in which the widget would have appeared.

editres can only help you if you know exactly which widgets' resources are important. As I discussed in another paper, a widget's behavior might really be controlled by the resources of another widget.[2] You'll have to use your knowledge of your widget set to find the appropriate widget and resources.

Finally, as mentioned above, editres can modify resources that your X client hard codes. Since these resources cannot be overridden through resource files, some users might be confused by the discrepancy.

Conclusion

One of the more powerful features of editres is that it executes independently of the X client on which it working. You do not need to run the client in a special environment (as you do with most symbolic debuggers). You do not have to compile it with special, performance sapping libraries (as you do with most performance and memory analyzers). editres works well with practically any other software engineering tools you might be using.

If you are developing X Toolkit applications and are not already using editres, give it a try. You'll be pleasantly surprised.

References

1. editres manual page and source code, in the X Consortium's X11R5 and X11R6 distributions.
2. Kenton Lee, "Indirect Motif Widget Resources," The X Journal, March, 1995.
3. Kenton Lee, "Widget Resource Syntax Errors," The X Journal, May, 1995.
4. Chris Peterson, "Editres: A Graphical Resource Editor For X Toolkit Applications," Proceedings of the 5th Annual X Technical Conference, January, 1991. A version of this paper also appears in The X Resource, Issue 0, Fall, 1991.

THE AUTHOR

Ken has published over two dozen technical papers on the X Window System. Most are available over the World Wide Web at http://www.rahul.net/kenton/bib.html.

Ken may be reached by Internet electronic mail to kenton @ rahul.net or the World Wide Web at http://www.rahul.net/kenton/.

For more information on the X Window System, please visit my home page..