editres - a dynamic resource editor for X Toolkit applications
editres [-toolkitoption...]
The editres command accepts all of the standard X Toolkit
command line options (see X(1X)). The order of the command
line options is not important.
editres is a tool that allows users and application developers
to view the full widget hierarchy of any X Toolkit
application that speaks the editres protocol. In addition
editres will help the user construct resource specifications,
allow the user to apply the resource to the application
and view the results dynamically. Once the user is
happy with a resource specification editres will append
the resource string to the user's X Resources file.
Editres provides a window consisting of the following four
areas: A set of popup menus that allow you full access to
editres's features. The panner allows a more intuitive
way to scroll the application tree display. Displays
information to the user about the action that editres
expects of her. This area will be used to display the
selected application's widget tree.
To begin an editres session select the Get Widget Tree
menu item from the command menu. This will change the
pointer cursor to cross hair. You should now select the
application you wish look at by clicking on any of its
windows. If this application understands the editres protocol
then editres will display the application's widget
tree in its tree window. If the application does not
understand the editres protocol editres will inform you of
this fact in the message area after a few seconds delay.
Once you have a widget tree you may now select any of the
other menu options. The effect of each of these is
described below.
Allows the user to click on any application that speaks
the editres protocol and receive its widget tree. Editres
only knows about the widgets that exist at the present
time. Many applications create and destroy widgets on the
fly. 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.
For 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
actually clicks on the Manual Page button. If you
retrieved xman's widget tree before the manual page
is active, you may wish to refresh the widget tree
after the manual page has been displayed. This
will allow you to also edit the manual page's
resources. For documenting applications it is
often useful to be able 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 popup dialog is activated.
Type the name of the file in this dialog, and
either select okay, or type a carriage-return.
Editres will now dump the widget tree to this file.
To cancel the file dialog, select the cancel button.
This command will popup a resource box for
the current application. This resource box
(described in detail below) will allow the user to
see exactly which resources can be set for the widget
that is currently selected in the widget tree
display. Only one widget may be currently
selected; if greater or fewer are selected editres
will refuse to pop up the resource box and put an
error message in the Message Area. This command
will popup a simple dialog box for setting an arbitrary
resource on all selected widgets. You must
type in the resource name, as well as the value.
You can use the Tab key to switch between the
resource name field the resource value field.
Exits editres.
The Tree menu contains several commands that allow operations
to be performed on the widget tree. This menu item
allows you to select any widget in the application;
editres will then highlight the corresponding element the
widget tree display. Once this menu item is selected the
pointer cursor will again turn to a crosshair, and you
must click any pointer button in the widget you wish to
have displayed. Since some widgets are fully obscured by
their children, it is not possible to get to every widget
this way, but this mechanism does give very useful feedback
between the elements in the widget tree and those in
the actual application. These functions allow the user to
select, unselect, or invert all widgets in the widget
tree. These functions select the immediate parent or
children of each of the currently selected widgets. These
functions select all parents or children of each of the
currently selected widgets. This is a recursive search.
When the tree widget 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 hex numbers. In the case of
64 bit addressing these hex numbers will only be the lower
32 bits of the widget's ID.
In addition there are keyboard accelerators for
each of the Tree operations. If the input focus is
over an individual widget in the tree, then that
operation will only effect 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 may be applied to any
widget in the application. If that widget is a
child of the Tree widget, then it will only affect
that widget, otherwise it will have the same effect
as the commands in the tree menu. 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, by flashing the corresponding
widget in the application numFlashes
(three by default) times in the flashColor.
-------------------------------------------------------
Key Option Translation Entry
-------------------------------------------------------
space Unselect Select(nothing)
w Select Select(widget)
s Select
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.
USING THE RESOURCE BOX [Toc] [Back] The resource box contains five different areas. Each of
the areas, as they appear on the screen, from top to bottom
will be discussed. 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.
This area allows you to select exactly which widgets this
resource will apply to. The area contains four lines, the
first contains the name of the selected widget and all its
ancestors, and the more restrictive dot (.) separator.
The second line contains less specific the Class names of
each widget, and well as the less restrictive star (*)
separator. The third line contains a set of special buttons
called Any Widget which will generalize this level to
match any widget. The last line contains a set of special
buttons called Any Widget Chain which will 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 dot separator.
By selecting the other buttons in this area
you can ease the restrictions to allow more and
more widgets to match the specification. The
extreme case is to select all 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 effected by the current resource
specification. The next area allows you to select
the name of the normal or constraint resources you
wish to set. Some widgets may not have constraint
resources, so that area will not appear. This next
area allows you to enter the resource value. This
value should be entered exactly as you would type a
line into your resource file. Thus it should
contain no unescaped new-lines. There are a few
special character sequences for this file:
\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> -- This will compress to nothing.
\\ -- This will compress to a single backslash.
If the client application uses a version of the
editres protocol that can provide the current values
of the widget's resources to the editres editor,
the initial value of the text in the Resource
Value area will be set to a representation of the
current value of the resource.
Being able to display a meaningful text representation
of the value depends on the existence of a
converter that can convert from the data type of
the resource to a text string. For any resource
value that cannot be converted to a text string,
the value string will be a decimal integer representation
of the value followed by the string
(integer fallback conversion). If you enter a new
value for this resource, be sure to delete the
(integer fallback conversion) string and enter a
string value in the appropriate format for conversion
to the resource's data type. This area contains
several command buttons, described in this
section. This button allows the user to modify
file that the resources will be saved to. This
button will bring up a dialog box that will ask you
for a filename; once the filename has been entered,
either hit carriage-return or click on the okay
button. To pop down the dialog box without changing
the save file, click the cancel button. This
button will append 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 be popped up to prompt the user for a filename.
This button attempts to perform a XtSetValues
call on all widgets that match the resource
line described above. The value specified is
applied directly to all matching widgets. This
behavior is an attempt to give a dynamic feel to
the resource editor. Since this feature allows
users to put an application in states it may not be
willing to handle, a hook has been provided to
allow specific applications to block these SetValues
requests (see Blocking Editres Requests below).
Unfortunately due to design constraints imposed on
the widgets by the X Toolkit and the Resource Manager,
trying to coerce an inherently static system
into dynamic behavior can cause strange results.
There is no guarantee that the results of an apply
will be the same as what will happen when you save
the value and restart the application. This functionality
is provided to try to give you a rough
feel for what your changes will accomplish, and the
results obtained should be considered suspect at
best. Having said that, this is one of the neatest
features of editres, and I strongly suggest that
you play with it, and see what it can do. This
button combines the Save and Apply actions
described above into one button. This button will
remove the resource box from the display.
BLOCKING EDITRES REQUESTS [Toc] [Back] The editres protocol has been built into the Athena Widget
set. This allows all applications that are linked against
Xaw to be able to speak to the resource editor. While
this provides great flexibility, and is a useful tool, it
can quite easily be abused. It is therefore possible for
any Xaw application to specify a value for the editresBlock
resource described below, to keep editres from
divulging information about its internals, or to disable
the SetValues part of the protocol. Specifies which type
of blocking this application wishes to impose on the
editres protocol.
The accepted values are: Block all requests. Block all
SetValues requests. As this is the only editres request
that actually modifies the application, this is in effect
stating that the application is read-only. Allow all
editres requests.
Remember that these resources are set on any Xaw application,
not editres. They allow individual applications to
keep all or some of the requests editres makes from ever
succeeding. Of course, editres is also an Xaw application,
so it may also be viewed and modified by editres
(rather recursive, I know), these commands can be blocked
by setting the editresBlock resource on editres itself.
For editres the available application resources are: Specifies
the number of times the widgets in the application
will be flashed when the Show Active Widgets command is
invoked. Amount of time between the flashes described
above. Specifies the color used to flash application widgets.
A bright color should be used that will immediately
draw your attention to the area being flashed, such as red
or yellow. This is the file the resource line will be
append to when the Save button activated in the resource
box.
In order to specify resources, it is useful to know the
hierarchy of the widgets which compose editres. In the
notation below, 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 application>
.
.
.
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
to get the default host and display number. to get the
name of a resource file that overrides the global
resources stored in the RESOURCE_MANAGER property.
This is a prototype, there are lots of nifty features I
would love to add, but I hope this will give you some
ideas about what a resource editor can do.
specifies required resources
X(1X), xrdb(1X), Athena Widget Set
Chris D. Peterson, formerly MIT X Consortium
editres(1X)
[ Back ] |
