Kenton Lee

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

editres is one of the more interesting and poweful X application development tools. In this issue's X Application Software Engineering column, I'll look at some of editres' more useful features. I'll also discuss the ways that I use it in my application development work.

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

Many software tools are currently available for X Toolkit application programmers. Some of these are very complex, others are very simple.

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?

If you have never used editres, your first question might be "what exactly is it?". editres is a tool that edits the X Toolkit widget resources of other application programs. That sounds pretty simple, but since X Toolkit widgets rely so heavily on resources, editres is very useful in several phases of X application development.

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).
Among popular X-based software development tools, the third feature is unique and very powerful. We will look at ways to take advantage of it below.

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

Many sophisticated user interface development tools call themselves "user interface management systems" (UIMS). While editres is a very powerful tool, it is not a UIMS. Let's look at some of the differences.

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
editres' functionality falls only in the second category: specifying widget resources. editres provides no facilities for specifying new widgets or for any of the run-time and application-level aspects of your client.

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

In the next couple of sections, I will briefly review the most important features of editres: examining an X client's widget hierarchy and manipulating its widgets' resources. If you are already familiar with editres, you can skip ahead.

Examining the Widget Hierarchy

The first editres feature you will usually use is the "Get Widget Tree" menu item. After choosing this function, select any X client displaying on your screen by mouseing on it. If that client supports editres, editres will display the widget hierarchy for that application as a graphical tree graph.

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

editres provides two functions that allow you to change widget resource values. The simplest technique is to select one or more widgets in the editres tree graph, then use the "Set Resource" feature. This function pops up a simple dialog box in which you can type in a resource name and its new value. The resource is changed in all the selected widgets (if they support that resource).

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

We have discussed editres' two major features: examining an X client's widget hierarchy and changing the resources of those widgets. In the next several sections, we will look at ways to use these features in the software development process.

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
Since editres has important features in areas 1, 2, and 4, it is very helpful in this process.

Checking the Widget Hierarchy

While editres cannot create a widget hierarchy for you, it can check the accuracy of your existing hierarchy. The widget hierarchy is a fundamental part of your widget layout, but, unfortunately, programming errors that corrupt the hierarchy are easy to make.

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

A related area where editres is useful is in managing widget geometries (sizes and positions). Creating the layout in the first place is often a highly iterative process. Finding problems can take a lot of digging. editres can help in both areas.

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

Because editres is dynamic and interactive, you can quickly try many different resource values until you get your layout right. You do not have to recompile your program unless you need to modify your widget hierarchy.

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

While the discussion in the previous section applies primarily to geometry and layout resources, the same approach works for testing changes to other resource values.

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

While the above material describes ways application developers (widget users) could use editres, the same techniques can also be used by widget developers. Specifying resources is one of the most important parts of X application development. Handling widget resource specifications is one of the most important parts of widget development.

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

In theory, the X Toolkit resource mechanism allows end users to modify X client resources with only the information provided in the client's documentation. In practice, this is too complex a task for the vast majority of users.

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

As mentioned above, one problem with editres is that it only works with X clients supporting the editres protocol. Fortunately, the protocol is widely supported.

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);
If your client uses more than one shell widget, you should repeat the above code for each shell widget.

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
Since the above code is just an event handler, it has no effect on the performance of your client until an editres message is received. Most programmers ship their products with editres support included.

Limitations of editres

Like most tools, editres is not perfect. Here are some limitations you should consider when using 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

editres is a very easy tool to use. Since its features work with resources, the most important part of X Toolkit, editres is also very useful. It has helped me in several phases of software engineering: GUI prototyping, code development, testing, and debugging.

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

Kenton Lee is an independent software consultant specializing in X Window System and OSF/Motif software development. He has been developing UNIX graphical user interface software since 1981.

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/.


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


Please send me your comments on this paper:

Name: E-mail:

[X Consulting] [Home] [Mail] [X Papers] [X WWW Sites]