.TH editres "" "" "X Utility"
.PC "Resource editor for X Toolkit applications"
\fBeditres [\fI-toolkitoption\fB ...]\fR
.PP
.HS
.SH Options:
.IC "\fB\-bd \fIcolor\fR"
Set the color of the border to \fIcolor\fR
.IC "\fB\-bg \fIcolor\fR"
Set the color of the background to \fIcolor\fR
.IC "\fB\-bw \fIpixels\fR"
Set the width of the border to \fIpixels\fR
.IC "\fB\-display \fIhost\^\fB[:\fIserver\^\fB][.\fIscreen\^\fB]\fR"
Display the client's window on screen number \fIscreen\fR
of \fIserver\fR on host system \fIhost\fR
.IC "\fB\-fg \fIcolor\fR"
Set the color of the foreground to \fIcolor\fR
.IC "\fB\-fn \fIfont\fR"
Use \fIfont\fR in the display
.IC "\fB\-geometry \fIgeometry\fR"
Set the geometry of the program's window to \fIgeometry\fR
.IC \fB\-rv\fR
Simulate reverse video by exchanging the foreground and background colors
.IC "\fB\-xrm \fIresourcestring\fR"
Use \fIresourcestring\fR to define a resource
.HE
.II "widget^editor"
The X utility
.B editres
lets you view the full widget hierarchy of any X Toolkit client that speaks the
.B Editres
protocol.
In addition,
.B editres
helps you construct a resource specification, then lets you
apply the resource to the application and view the results.
Once you are happy with a resource specification,
.B editres
appends the resource string to your X resources file.
.SH "Command-line Options"
.B editres
recognizes the following command-line options:
.IP "\fB\-bd \fIcolor\fR" 0.75i
Set the color of the border to
.IR color .
.IP "\fB\-bg \fIcolor\fR"
Set the color of the background to
.IR color .
.IP "\fB\-bw \fIpixels\fR"
Set the width of the border to
.IR pixels .
.IP "\fB\-display \fIhost\^\fB[:\fIserver\^\fB][.\fIscreen\^\fB]\fR"
Display the client's window on screen number
.I screen
of
.I server
on host system
.IR host .
.IP "\fB\-fg \fIcolor\fR"
Set the color of the foreground to
.IR color .
.IP "\fB\-fn \fIfont\fR"
Use
.I font
in the display.
.IP "\fB\-geometry \fIgeometry\fR"
Set the geometry of the program's window to
.IR geometry .
The term ``geometry'' means the dimensions of the window and its location
on the screen.
.I geometry
has the form \fIwidth\(muheight\(+-xoffset\(+-yoffset\fR.
.IP \fB\-rv\fR
Simulate reverse video by exchanging the foreground and background colors.
.IP "\fB\-xrm \fIresourcestring\fR"
Use
.I resourcestring
to define a resource.
.SH "editres Window"
.B editres
displays a window that consists of the following four areas:
.IP "\fBMenu Bar\fR" 0.75i
A set of pop-up menus that allow you full access to editres's features.
.IP "\fBPanner\fR" 
This lets the user ``pan'' through an image.
This is a more intuitive way to scroll the application tree's display.
.IP "\fBMessage Area\fR"
Display information about the action that
.B editres
expects of the user.
.IP "\fBApplication Widget Tree\fR"
Display the selected client's widget tree.
.PP
To begin an
.B editres
session, first select the menu item
.K Get_Widget_Tree
from the command menu.
This changes the mouse cursor to a cross hair.
Click on the window of the application you wish to examine.
If this application understands the
.B Editres
protocol, then
.B editres
displays the client's widget tree in its tree window.
If the application does not understand the
.B Editres
protocol,
.B editres
informs you of this fact in the message area.
.SH "editres Menu Commands"
Once you have read a widget tree, you can manipulate it by
selecting any of the following options from the
.B editres
menu:
.IP "\fK(Dump_Widget_Tree_to_a_File)\fR" 0.75i
This option dumps into a file a text description of
the application's widget tree.
The output of this option is especially useful when you wish to include
an application's widget tree in a manual page.
When you select this option,
.B editres
actives a pop-up dialogue.
Type into the dialogue the name of the file into which you wish to dump the
description;
then either click the button labelled \fK(okay)\fR, or press the \*(RT key.
.B editres
dumps the widget tree to this file.
To cancel the file dialogue, click the buttom labelled \fK(cancel)\fR.
.IP "\fK(Quit)\fR"
Exit
.BR editres .
.IP "\fK(Refresh_Widget_Tree)\fR"
.B editres
only knows about the widgets that an application was using at the moment
you read its widget tree.
Many applications create and destroy widgets ``on the fly.''
This menu item tells
.B editres
to re-read an application's widget tree,
thus updating its information to the current state of the application.
.IP "\fK(Send_Widget_Tree)\fR"
Read the widget tree of any client that speaks the
.B Editres
protocol by clicking on any of its windows.
.IP "\fK(Set_Resource)\fR"
This command displays a dialogue box in which you can set a
resource for all selected widgets.
Type the name of the resource and the value to which you are setting it.
To jump between the resource-name field and the resource-value field,
press the \fK(Tab)\fR key.
.IP "\fK(Show_Resource_Box)\fR"
Display a resource box for the current client.
This box (described in detail below) lets you see
exactly which resources can be set for the widget that is currently
selected in the widget tree's display.
Only one widget can be selected at a time; if more or fewer are selected,
.B editres
refuses to display the resource box
and displays an error message in the \fBMessage Area\fR.
.SH "Tree Commands"
The
.B Tree
menu contains the following commands
with which you can manipulate the widget tree:
.IP "\fK(Flash_Active_Widgets)\fR"
This command is the inverse of the command \fBSelect Widget in Client\fR:
for each widget that is currently selected in the widget tree,
it flashes the corresponding widget in the application.
It flashes each widget \fInumFlashes\fR times (default, three)
in \fIflashColor\fR.
.IP "\fK(Invert_All)\fR" 
Invert every widget in the widget tree.
.IP "\fK(Select_All)\fR" 
Select all widgets in the widget tree.
.IP "\fK(Select_Ancestors)\fR"
Select all parents of each of the currently selected widgets.
This is a recursive search.
.IP "\fK(Select_Children)\fR"
Select the immediate children of each of the currently selected widgets.
.IP "\fK(Select_Descendants)\fR"
Select all children of each of the
currently selected widgets, yea, even unto the last generation.
This is a recursive search.
.IP "\fK(Select_Parents)\fR"
Select the immediate parent of each of the currently selected widgets.
.IP "\fK(Select_Widget_in_Client)\fR"
When you select this command, the mouse cursor turns into a cross hair.
When you click a widget in the application,
.B editres
highlights the corresponding entry in the widget tree's display.
Because some widgets are obscured by their children,
it is not possible to display to every widget this way.
.IP "\fK(Show_Class_Names)\fR"
Change the label of every widget in the tree to show the widget's class name
instead of the widget's name.
.IP "\fK(Show_Widget_IDs)\fR"
Change the label of every widget in the tree to show the widget's ID,
in hexadecimal, instead of the widget's name.
.IP "\fK(Show_Widget_Names)\fR"
Change the label of every widget in the tree to show the widget's name.
This is the default.
.IP "\fK(Show_Widget_Windows)\fR"
Change the label of every widget in the tree to show the widget's window,
in hexadecimal, instead of the widget's name.
.IP "\fK(Unselect_All)\fR"
Unselect all widgets in the widget tree.
.PP
Most of the above commands have a keyboard equivalent, as follows:
.DS
.ta 0.75iC 1.5i 3.5i
	\fIKey	Command	Translation Entry\fR
	\fBspace\fR	Unselect	Select(nothing)
	\fBC\fR	Show Class Names	Relabel(class)
	\fBI\fR	Show Widget IDs	Relabel(id)
	\fBN\fR	Show Widget Names	Relabel(name)
	\fBT\fR	Toggle Widget/Class Name	Relabel(toggle)
	\fBW\fR	Show Widget Windows	Relabel(window)
	\fBa\fR	Select Ancestors	Select(ancestors)
	\fBc\fR	Select Children	Select(children)
	\fBd\fR	Select Descendants	Select(descendants)
	\fBi\fR	Invert	Select(invert)
	\fBp\fR	Select Parent	Select(parent)
	\fBs\fR	Select	Select(all)
	\fBw\fR	Select	Select(widget)
.DE
.PP
To add a widget to the set of selected widgets, click the left mouse button.
To select a widget and un-select all other widgets,
click the middle mouse button on that widget.
Clicking the right mouse button on a widget toggles a widget's label
between the widget's instance name and the widget's class name.
.SH "Using the Resource Box"
The resource box contains five areas, as follows:
.IP "\fBResource Line\fR"
This area, which is at the top of the resource box,
shows the name of the current resource
exactly as it would appear if you were to save it into a file or apply it.
.IP "\fBWidget Names and Classes\fR"
This area allows you to select the widgets to which this resource will apply.
The area contains four lines, as follows:
.RS
.IP \fB1.\fR 0.3i
The name of the selected widget and all its ancestors,
and the more-restrictive period `.' separator.
.IS \fB2.\fR
The class names of each widget,
and well as the less-restrictive asterisk `*' separator.
.IS \fB3.\fR
A set of special buttons labelled \fK(Any_Widget)\fR,
which generalizes this level to match any widget.
.IS \fB4.\fR
A set of special buttons labelled
\fK(Any_Widget_Chain)\fR, which turns the single level into something that
matches zero or more levels.
.RE
.IP
The initial state of this area is the most restrictive,
using the resource names and the period 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
\fK(Any_Widget_Chain)\fR buttons,
which matches every widget in the application.
As you select different buttons, the tree's display updates
to show you exactly which widgets are affected by the resource specification.
.IP "\fBNormal and Constraint Resources\fR"
The next area lets you 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.
.IP "\fBResource Value\fR"
This next area allows you to enter the resource value.
Enter this value 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:
.RS
.IP \fB\en\fR 0.3i
A newline.
.IS \fB\e\fIOOO\fR
A number, where
.I OOO
represents three octal digits.
This is replaced by one byte that contains this sequence interpreted
as an octal number.
For example, a NUL can be represented by the sequence
.BR \e000 .
.IS \fB\e<new-line>\fR
A blank line.
.IS \e\e
A literal backslash.
.RE
.IP "\fBCommand Area\fR"
This area contains the following command buttons:
.RS
.IP "\fK(Apply)\fR"
Perform a
.B XtSetValues()
call on all widgets that match the \fIresource line\fR 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.
Because this feature lets you put an application into a state that
it is not willing to handle,
a hook has been provided to allow specific clients block these
.B XtSetValues()
requests (see the discussion of blocking editres requests, below).
.IP
Unfortunately, the X Toolkit and Resource Manager impose constraints
on widgets; thus,trying to coerce an inherently static system
into dynamic behavior can produce strange results.
There is no guarantee that when you save a value and restart an application,
that application behaves the same as it appeared under
.BR editres .
This feature is provided to give you a rough feel for what
your changes will do; the results should be considered suspect at best.
.IP "\fK(Popdown_Resource_Box)\fR"
Remove the resource box from the display.
.IP "\fK(Save)\fR"
Append the \fIresource line\fR described above onto the end of the save file.
If no save file has been set,
.B editres
displays the \fK(Set_Save_File)\fR dialogue box.
.IP "\fK(Save_and_Apply)\fR"
Combine into one button the
.B Save
and
.B Apply
actions described above.
.IP "\fK(Set_Save_File)\fR"
Change the file into which the resources are saved.
When you press this button,
.B editres
displays a dialogue box that requests a file name.
Once the file name has been entered, either press \*(RT
or click on the button labelled \fK(okay)\fR.
To close the dialogue box without changing the file,
click the button labelled \fK(cancel)
.RE
.SH "Blocking editres Requests"
.II "Athena widget set"
.II "widget^Athena set"
The
.B editres
protocol has been built into the Athena Widget set.
.II Xaw
This allows all application that are linked against
.B Xaw
to be able to speak to the resource editor.
Although this provides great flexibility, and is a useful tool,
it can quite easily be abused.
It is therefore possible for any
.B Xaw
client to specify a value for the resource
.BR editresBlock ,
described below, to keep
.B editres
from divulging information about its internals, or to disable the
.B SetValues
part of the protocol.
.IP "\fBeditresBlock (\fRClass\fB EditresBlock)\fR"
Specify the type of blocking this client wishes to impose on the
.B editres
protocol.
The accepted values are as follows:
.RS
.IP \fBall\fR 0.75i
Block all requests.
.IS \fBsetValues\fR
Block all
.B setvalues
requests.
This is the only
.B editres
request that actually modifies the application;
in effect, it states that the application is read-only.
.IS \fBnone\fR
Allow all
.B editres
requests.
.RE
.PP
Remember that these resources are set on any
.B Xaw
client,
.I not
.BR editres .
They allow individual clients to stop some or all of the requests that
.B editres
makes from ever succeeding.
.PP
Note that
.B editres
is also an
.B Xaw
client, so it can view and modify itself;
these commands can be blocked by setting the
.B editresBlock
resource on
.B editres
itself.
.SH Resources
.B editres
uses the following application-specific resources:
.IP "\fBnumFlashes (\fRClass \fBNumFlashes)\fR"
Set the number of times
.B editres
flashes the widgets in the client application when you invoke the
command \fBShow Active Widgets\fR.
.IP "\fBflashTime (\fRClass\fB FlashTime)\fR"
Amount of time between the flashes described above.
.IP "\fBflashColor (\fRClass\fB flashColor)\fR"
Set the color used when
.B editres
flashes clients.
A bright color should be used, such as red or yellow \(em
one that immediately draws your attention to the area being flashed.
.IP "\fBsaveResourcesFile (\fRClass\fB SaveResourcesFile)\fR"
The file into which the resource line is append to when the you select
the \fBSave\fR button Resource box.
.SH Widgets
The following gives the widgets that
.B editres
uses:
.DM
Editres  editres
	Paned  paned
		Box  box
			MenuButton  commands
.DE
.DM
				SimpleMenu  menu
					SmeBSB  sendTree
					SmeBSB  refreshTree
					SmeBSB  dumpTreeToFile
					SmeLine  line
					SmeBSB  getResourceList
					SmeLine  line
					SmeBSB  quit
.DE
.DM
			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
.DE
.DM
		Paned  hPane
			Panner  panner
			Label  userMessage
			Grip  grip
.DE
.DM
		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
								     .
								     .
								     .
.DE
.DM
							Label  namesLabel
							List  namesList
							Label  constraintLabel
							List  constraintList
							Form  valueForm
								Label  valueLabel
								Text  valueText
.DE
.DM
							Box  commandBox
								Command  setFile
								Command  save
								Command  apply
								Command  saveAndApply
								Command  cancel
							Grip  grip
		Grip  grip
.DE
.SH Environment
.B editres
reads the following environmental variables:
.IP \fBDISPLAY\fR 0.75i
The default host and display number.
.IP \fBXENVIRONMENT\fR
The name of a resource file that overrides the global resources stored in the
property
.BR RESOURCE_MANAGER .
.SH Files
\fB/usr/X11/lib/app-defaults/Editres\fR \(em Required resources
.SH "See Also"
.B
bitmap,
X utilities
.R
.SH Notes
Copyright \(co 1990, Massachusetts Institute of Technology.
.PP
This program is a prototype.
.I "Caveat utilitor."
.PP
.II "Peterson, Chris"
.B editres
was written by
Chris D. Peterson, formerly of the MIT X Consortium.
