With editres, you can view the full widget hierarchy of
any X Toolkit client that speaks the editres protocol. In
addition, you can use editres to construct resource
specifications, apply the resource to the application, and view the
results dynamically. Once you are satisfied with a resource
specification, editres will append the resource string to
your X Resources file.
A window provided by editres consists of the following
four areas:
Menu Bar
A set of pop-up menus that provide full access to the features
of editres.
Panner
Provides an intuitive way to scroll the application tree
display.
Message Area
Displays information about the action that editres
expects of the user.
Application Widget Tree
Displays the selected client's widget tree.
To begin an editres session, on the command menu, click
Get Widget Tree. This changes the cursor from a pointer to a
cross-hair. To view an application, click any of its windows. If
the application is able to communicate with the editres
protocol, editres will display the client's widget tree in
its tree window. If the application is unable to communicate with
the editres protocol, after a few seconds, a message to that
effect will appear in the message area.
After you have established a widget tree, you can use any of the
other menu options. The effect of each of these is described in the
following section.
Allows the user to click any client that speaks the
editres protocol and receive its widget tree.
Refresh Widget Tree
Only those widgets that exist at the present time are known by
editres. Many applications create and destroy widgets as
they go. Selecting this menu item will cause editres to ask
the application to resend its widget tree, thus updating its
information to the new state of the application.
Example
Xman only creates the widgets for its "topbox" when it starts
up. None of the widgets for the manual page window are created
until the user clicks the Manual Page button. If xman's
widget tree is retrieved before the manual page is active, you
might want to refresh the widget tree after the manual page has
been displayed. This will also allow you to edit the manual page's
resources.
Dump Widget Tree to a File
For documenting applications, it is often useful to dump the
entire application widget tree to an ASCII file. This file can then
be included in the manual page. When this menu item is selected, a
pop-up dialog box is activated. Type the name of the file in this
dialog box, and either click OK or press ENTER. The widget
tree will then be dumped to this file by editres. To cancel
the file dialog box, click Cancel.
Show Resource Box
Causes a resource box for the current client to appear. Use
this resource box (described later) to view the resources that can
be set for the widget that is currently selected in the widget tree
display. Only one widget can be selected at a time. If more than
one widget is selected, editres will refuse to display the
resource box, and it will put an error message in the message
area.
Set Resource
This command displays a dialog box for setting an arbitrary
resource on all selected widgets. You must type in the resource
name, as well as the value. Use the TAB key to switch between the
resource name field the resource value field.
The Tree menu contains several commands you can use to
perform operations on the widget tree.
Select Widget in Client
Use this menu item to select any widget in the application;
editres will then highlight the corresponding element in the
widget tree display. Once this menu item is selected, the cursor
will change from a pointer to a cross-hair. You can then click any
pointer button in the widget that you want to have displayed.
Because some widgets are fully obscured by their children, it is
not possible to get to every widget this way, but this mechanism
does provide a useful exchange of information between the elements
in the widget tree and those in the actual client.
Select All
Unselect All
Invert All
These functions to select, unselect, or invert all widgets in
the widget tree.
Select Children
Select Parents
These functions select the immediate parent or children of each
of the currently selected widgets.
Select Descendants
Select Ancestors
These functions select all parents or children of each of the
currently selected widgets. This is a recursive search.
Show Widget Names
Show Class Names
Show Widget IDs
Show Widget Windows
When the widget tree is initially displayed, the labels of each
widget in the tree correspond to the widget names. These functions
will cause the label of all widgets in the tree to be changed to
show the class name, IDs, or window associated with each widget in
the application. The widget IDs, and windows are shown as
hexadecimal numbers.
Flash Active Widgets
This command is the inverse of the Select Widget in
Client command: it will show the user each widget that is
currently selected in the widget tree. It does so by flashing the
corresponding widget in the application numFlashes times
(three by default) in the flashColor.
In addition, there are keyboard accelerators for each of the
tree operations. If the input focus is over an individual widget in
the tree, that operation will only affect that widget. If the input
focus is in the tree background, it will have exactly the same
effect as the corresponding menu item.
The translation entries shown can be applied to any widget in
the application. If that widget is a child of the Tree widget, it
will only affect that widget; otherwise, it will have the same
effect as the commands in the tree menu.
Key
Option
Translation Entry
Space
Unselect
Select(nothing)
w
Select
Select(widget)
s
Select
Select(all)
i
Invert
Select(invert)
c
Select Children
Select(children)
d
Select Descendants
Select(descendants)
p
Select Parent
Select(parent)
a
Select Ancestors
Select(ancestors)
N
Show Widget Names
Relabel(name)
C
Show Class Names
Relabel(class)
I
Show Widget IDs
Relabel(id)
W
Show Widget Windows
Relabel(window)
T
Toggle Widget/Class Name
Relabel(toggle)
Clicking button 1 on a widget adds it to the set of selected
widgets. Clicking button 2 on a widget deselects all other widgets,
and then selects just that widget. Clicking button 3 on a widget
toggles its label between the widget's instance name the widget's
class name.
The resource box contains five different areas. Each of these
areas will be discussed in the order in which they appear on the
screen, from top to bottom.
The Resource Line
This area at the top of the resource box shows the current
resource name exactly as it would appear if you were to save it to
a file or apply it.
The Widget Names and Classes
Use this area to select the widgets to which this resource will
apply. The area contains four lines. The first line contains the
name of the selected widget, all of its ancestors, and the more
restrictive period (.) separator. The second line contains
the class names of each widget and the less restrictive asterisk
(*) separator. The third line contains a set of special
buttons called Any Widget that generalize this level to
match any widget. The last line contains a set of special buttons
called Any Widget Chain that turn the single level into
something that matches zero or more levels.
The initial state of this area is the most restrictive, using
the resource names and the period (.) separator. If you
select other buttons in this area, you can ease the restrictions to
allow more widgets to match the specification. The extreme case is
to select all of the Any Widget Chain buttons, which will
match every widget in the application. As you select different
buttons, the tree display will update to show you exactly which
widgets will be affected by the current resource
specification.
Normal and Constraint Resources
This area allows you to select the name of the normal or
constraint resources you want to set. Some widgets may not have
constraint resources, so that area will not appear.
Resource Value
Use this area to enter the resource value. Because this value
should be entered exactly as you would type a line into your
resource file, it should not contain any unescaped newlines. The
special character sequences for this file are described in the
following list:
\n
This will be replaced with a newline.
\###
Where # is any octal digit. This will be replaced with a
single byte that contains this sequence interpreted as an octal
number. For example, a value containing a NULL byte can be stored
by specifying \000.
\<new-line>
Compresses to nothing.
\\
Compresses to a single backslash.
Command Area
Contains several command buttons that are described later in
this section.
Set Save File
Modifies the file to which the resources will be saved. When
you click this button, a dialog box prompts you for a file name.
Once the file name has been typed, press ENTER or click OK.
To close the dialog box without changing the save file, click
Cancel.
Save
Appends the resource line described above to the end of the
current save file. If no save file has been set, the Set Save
File dialog box will prompt you for a file name.
Apply
Attempts to perform a XtSetValues call on all widgets that
match the resource line. The value specified is applied directly to
all matching widgets. This behavior is an attempt to give a dynamic
feel to the resource editor. You can use this feature to put an
application in states it may not be willing to handle; a hook has
been provided to allow specific clients to block these SetValues
requests (see Blocking Editres Requests, described later).
Due to design constraints imposed on the widgets by the X
Toolkit and the Resource Manager, trying to force an inherently
static system into dynamic behavior can produce strange results.
There is no guarantee that the clicking the Apply button
will produce the same results as saving the value and restarting
the application. This functionality is provided to give users a
preview of what particular changes might accomplish. The results
obtained, however, are neither reliable nor predictable.
Nonetheless, this is a strong and useful feature of editres.
Users are encouraged to experiment with it to learn the many useful
ways in which it can be applied.
Save and Apply
Combines the save and apply actions described previously into
one button.
The editres protocol has been built into the Athena
Widget set. This allows all applications that are linked against
Xaw to communicate with the resource editor. While this provides
great flexibility and is a useful tool, it can easily be misused.
It is therefore possible for any Xaw client to either specify a
value for the editresBlock resource that will prevent
editres from divulging information about its internals, or
to disable the SetValues part of the protocol.
editresBlock (Class EditresBlock)
Specifies which type of blocking this client wants to impose on
the editres protocol.
The accepted values are:
all
Block all requests.
setValues
Block all setvalues requests. This is the only editres
request that actually modifies the application that is in effect,
stating that the application is read-only.
none
Allow all editres requests.
These resources are set on any Xaw client, not editres.
They allow individual clients to prevent all or some of the
requests editres makes from succeeding. Because
editres is also an Xaw client, it can be viewed and modified
by editres (which might seem rather recursive). These
commands can be blocked by setting the editresBlock resource
on editres itself.
The available application resources for editres are as
follows:
numFlashes (Class NumFlashes)
Specifies the number of times the widgets in the client
application will be flashed when the Show Active Widgets
command is invoked.
flashTime (Class FlashTime)
Amount of time between the flashes described in the previous
entry.
flashColor (Class flashColor)
Specifies the color used to flash client widgets. It is
recommended that a bright color such as red or yellow be used to
draw attention to the area being flashed.
saveResourcesFile (Class SaveResourcesFile)
This is the file the resource line will be append to when the
Save button is activated in the resource box.
In order to specify resources, it is useful to know the
hierarchy of the widgets that compose editres. In the
following notation, indentation indicates hierarchical structure.
The widget class name is given first, followed by the widget
instance name.
Editres editres
Paned paned
Box box
MenuButton commands
SimpleMenu menu
SmeBSB sendTree
SmeBSB refreshTree
SmeBSB dumpTreeToFile
SmeLine line
SmeBSB getResourceList
SmeLine line
SmeBSB quit
MenuButton treeCommands
SimpleMenu menu
SmeBSB showClientWidget
SmeBSB selectAll
SmeBSB unselectAll
SmeBSB invertAll
SmeLine line
SmeBSB selectChildren
SmeBSB selectParent
SmeBSB selectDescendants
SmeBSB selectAncestors
SmeLine line
SmeBSB showWidgetNames
SmeBSB showClassNames
SmeBSB showWidgetIDs
SmeBSB showWidgetWindows
SmeLine line
SmeBSB flashActiveWidgets
Paned hPane
Panner panner
Label userMessage
Grip grip
Porthole porthole
Tree tree
Toggle <name of widget in client>
.
TransientShell resourceBox
Paned pane
Label resourceLabel
Form namesAndClasses
Toggle dot
Toggle star
Toggle any
Toggle name
Toggle class
.
Label namesLabel
List namesList
Label constraintLabel
List constraintList
Form valueForm
Label valueLabel
Text valueText
Box commandBox
Command setFile
Command save
Command apply
Command saveAndApply
Command cancel
Grip grip
Grip grip
This is a prototype. There are lots of useful features I would
love to add, but I hope this will give you some ideas about what a
resource editor can do.