501 lines
22 KiB
HTML
501 lines
22 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of EDITRES</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>EDITRES</H1>
|
|
Section: User Commands (1)<BR>Updated: editres 1.0.7<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
editres - a dynamic resource editor for X Toolkit applications
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNTAX</H2>
|
|
|
|
<B>editres</B> [ <I>-toolkitoption</I> ... ]
|
|
<A NAME="lbAD"> </A>
|
|
<H2>OPTIONS</H2>
|
|
|
|
<I>Editres</I>
|
|
|
|
accepts all of the standard X Toolkit command line
|
|
options (see <I><A HREF="/cgi-bin/man/man2html?7+X">X</A>(7)</I>). The order of the command line options is
|
|
not important.
|
|
<A NAME="lbAE"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
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.
|
|
<A NAME="lbAF"> </A>
|
|
<H2>USING EDITRES</H2>
|
|
|
|
<I>Editres</I>
|
|
|
|
provides a window consisting of the following four areas:
|
|
<DL COMPACT>
|
|
<DT id="1">Menu Bar<DD>
|
|
A set of popup menus that allow you full access to editres's features.
|
|
<DT id="2">Panner<DD>
|
|
The panner allows a more intuitive way to scroll the application tree display.
|
|
<DT id="3">Message Area<DD>
|
|
Displays information to the user about the action that editres expects
|
|
of her.
|
|
<DT id="4">Application Widget Tree<DD>
|
|
This area will be used to display the selected application's widget tree.
|
|
</DL>
|
|
<P>
|
|
|
|
To begin an editres session select the <B>Get Widget Tree</B> 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.
|
|
<P>
|
|
|
|
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.
|
|
<A NAME="lbAG"> </A>
|
|
<H2>COMMANDS</H2>
|
|
|
|
<DL COMPACT>
|
|
<DT id="5">Get Widget Tree<DD>
|
|
Allows the user to click on any application that speaks the editres
|
|
protocol and receive its widget tree.
|
|
<DT id="6">Refresh Current Widget Tree<DD>
|
|
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.
|
|
<DT id="7"><DD>
|
|
For example,
|
|
xman only creates the widgets for its <I>topbox</I> when it
|
|
starts up. None of the widgets for the manual page window are created
|
|
until the user actually clicks on the <I>Manual Page</I> button. If
|
|
you retrieved
|
|
xman's widget tree before the 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.
|
|
<DT id="8">Dump Widget Tree to a File<DD>
|
|
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 <I>okay</I>, or type a carriage-return. Editres
|
|
will now dump the widget tree to this file. To cancel the file dialog,
|
|
select the <I>cancel</I> button.
|
|
<DT id="9">Show Resource Box<DD>
|
|
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 <B>Message Area</B>.
|
|
<DT id="10">Set Resource<DD>
|
|
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.
|
|
<DT id="11">Quit<DD>
|
|
Exits editres.
|
|
</DL>
|
|
<A NAME="lbAH"> </A>
|
|
<H2>TREE COMMANDS</H2>
|
|
|
|
The <B>Tree</B> menu contains several commands that allow operations to
|
|
be performed on the widget tree.
|
|
<DL COMPACT>
|
|
<DT id="12">Select Widget in Client<DD>
|
|
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.
|
|
<DT id="13">Select All<DD>
|
|
<DT id="14">Unselect All<DD>
|
|
<DT id="15">Invert All<DD>
|
|
These functions allow the user to select, unselect, or invert all
|
|
widgets in the widget tree.
|
|
<DT id="16">Select Children<DD>
|
|
<DT id="17">Select Parents<DD>
|
|
These functions select the immediate parent or children of each of the
|
|
currently selected widgets.
|
|
<DT id="18">Select Descendants<DD>
|
|
<DT id="19">Select Ancestors<DD>
|
|
These functions select all parents or children of each of the
|
|
currently selected widgets. This is a recursive search.
|
|
<DT id="20">Show Widget Names<DD>
|
|
<DT id="21">Show Class Names<DD>
|
|
<DT id="22">Show Widget IDs<DD>
|
|
<DT id="23">Show Widget Windows<DD>
|
|
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 <B>all</B> 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.
|
|
</DL>
|
|
<P>
|
|
|
|
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.
|
|
<P>
|
|
|
|
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.
|
|
<DL COMPACT>
|
|
<DT id="24">Flash Active Widgets<DD>
|
|
This command is the inverse of the <B>Select Widget in Client</B>
|
|
command, it will show the user each widget that is currently selected in
|
|
the widget tree, by flashing the corresponding widget in the
|
|
application <I>numFlashes</I> (three by default) times in the
|
|
<I>flashColor</I>.
|
|
<P>
|
|
<TABLE>
|
|
<TR VALIGN=top><TD><B>Key</B></TD><TD><B>Option</B></TD><TD><B>Translation Entry</B><BR></TD></TR>
|
|
<TR VALIGN=top><TD>-</TD><TD></TD><TD><BR></TD></TR>
|
|
<TR VALIGN=top><TD>space</TD><TD>Unselect</TD><TD>Select(nothing)<BR></TD></TR>
|
|
<TR VALIGN=top><TD>w</TD><TD>Select</TD><TD>Select(widget)<BR></TD></TR>
|
|
<TR VALIGN=top><TD>s</TD><TD>Select</TD><TD>Select(all)<BR></TD></TR>
|
|
<TR VALIGN=top><TD>i</TD><TD>Invert</TD><TD>Select(invert)<BR></TD></TR>
|
|
<TR VALIGN=top><TD>c</TD><TD>Select Children</TD><TD>Select(children)<BR></TD></TR>
|
|
<TR VALIGN=top><TD>d</TD><TD>Select Descendants</TD><TD>Select(descendants)<BR></TD></TR>
|
|
<TR VALIGN=top><TD>p</TD><TD>Select Parent</TD><TD>Select(parent)<BR></TD></TR>
|
|
<TR VALIGN=top><TD>a</TD><TD>Select Ancestors</TD><TD>Select(ancestors)<BR></TD></TR>
|
|
<TR VALIGN=top><TD>N</TD><TD>Show Widget Names</TD><TD>Relabel(name)<BR></TD></TR>
|
|
<TR VALIGN=top><TD>C</TD><TD>Show Class Names</TD><TD>Relabel(class)<BR></TD></TR>
|
|
<TR VALIGN=top><TD>I</TD><TD>Show Widget IDs</TD><TD>Relabel(id)<BR></TD></TR>
|
|
<TR VALIGN=top><TD>W</TD><TD>Show Widget Windows</TD><TD>Relabel(window)<BR></TD></TR>
|
|
<TR VALIGN=top><TD>T</TD><TD>Toggle Widget/Class Name</TD><TD>Relabel(toggle)<BR></TD></TR>
|
|
</TABLE>
|
|
|
|
<P>
|
|
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.
|
|
<P>
|
|
</DL>
|
|
<A NAME="lbAI"> </A>
|
|
<H2>USING THE RESOURCE BOX</H2>
|
|
|
|
The resource box contains five different areas. Each of the areas,
|
|
as they appear on the screen, from top to bottom will be discussed.
|
|
<DL COMPACT>
|
|
<DT id="25">The Resource Line<DD>
|
|
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.
|
|
<DT id="26">The Widget Names and Classes<DD>
|
|
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 (<B>.</B>) separator. The second line contains less specific the
|
|
Class names
|
|
of each widget, and well as the less restrictive star (<B>*</B>) separator.
|
|
The third line contains a set of special buttons called <B>Any Widget</B>
|
|
which will generalize this level to match any widget.
|
|
The last line contains a set of special buttons called <B>Any
|
|
Widget Chain</B> which will turn the single level into something that
|
|
matches zero or more levels.
|
|
<P>
|
|
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
|
|
<B>Any Widget Chain</B> 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.
|
|
<DT id="27">Normal and Constraint Resources<DD>
|
|
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.
|
|
<DT id="28">Resource Value<DD>
|
|
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:
|
|
<P>
|
|
\n - This will be replaced with a newline.
|
|
<P>
|
|
\### - 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.
|
|
<P>
|
|
\<new-line> - This will compress to nothing.
|
|
<P>
|
|
\\ - This will compress to a single backslash.
|
|
<DT id="29">Command Area<DD>
|
|
This area contains several command buttons, described in
|
|
this section.
|
|
<DT id="30">Set Save File<DD>
|
|
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 <I>okay</I> button. To pop down the
|
|
dialog box without changing the save file, click the <I>cancel</I> button.
|
|
<DT id="31">Save<DD>
|
|
This button will append the <B>resource line</B> described above to the
|
|
end of the current save file. If no save file has been set the <B>Set
|
|
Save File</B> dialog box will be popped up to prompt the user for a filename.
|
|
<DT id="32">Apply<DD>
|
|
This button attempts to perform a XtSetValues call on all widgets
|
|
that match the <B>resource line</B> 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 <B>Blocking Editres Requests</B> below).
|
|
<P>
|
|
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.
|
|
<DT id="33">Save and Apply<DD>
|
|
This button combines the Save and Apply actions described above into
|
|
one button.
|
|
<DT id="34">Popdown Resource Box<DD>
|
|
This button will remove the resource box from the display.
|
|
</DL>
|
|
<A NAME="lbAJ"> </A>
|
|
<H2>BLOCKING EDITRES REQUESTS</H2>
|
|
|
|
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 <B>editresBlock</B>
|
|
resource described below, to keep editres from divulging information
|
|
about its internals, or to disable the <B>SetValues</B> part of the protocol.
|
|
<DL COMPACT>
|
|
<DT id="35"><B>editresBlock (</B>Class<B> EditresBlock)</B>
|
|
|
|
<DD>
|
|
Specifies which type of blocking this application wishes to impose on the
|
|
editres protocol.
|
|
</DL>
|
|
<P>
|
|
|
|
The accepted values are:
|
|
<DL COMPACT>
|
|
<DT id="36">all<DD>
|
|
Block all requests.
|
|
<DT id="37">setValues<DD>
|
|
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.
|
|
<DT id="38">none<DD>
|
|
Allow all editres requests.
|
|
</DL>
|
|
<P>
|
|
|
|
Remember that these resources are set on any Xaw application, <B>not
|
|
editres</B>. 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 <B>editresBlock</B> resource on editres itself.
|
|
<A NAME="lbAK"> </A>
|
|
<H2>RESOURCES</H2>
|
|
|
|
For <I>editres</I> the available application resources are:
|
|
<DL COMPACT>
|
|
<DT id="39"><B>numFlashes (</B>Class<B> NumFlashes)</B>
|
|
|
|
<DD>
|
|
Specifies the number of times the widgets in the application
|
|
will be flashed when the <B>Show Active Widgets</B> command in invoked.
|
|
<DT id="40"><B>flashTime (</B>Class<B> FlashTime)</B>
|
|
|
|
<DD>
|
|
Amount of time between the flashes described above.
|
|
<DT id="41"><B>flashColor (</B>Class<B> flashColor)</B>
|
|
|
|
<DD>
|
|
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.
|
|
<DT id="42"><B>saveResourcesFile (</B>Class<B> SaveResourcesFile)</B>
|
|
|
|
<DD>
|
|
This is the file the resource line will be append to when the <B>Save</B>
|
|
button activated in the resource box.
|
|
</DL>
|
|
<A NAME="lbAL"> </A>
|
|
<H2>WIDGETS</H2>
|
|
|
|
In order to specify resources, it is useful to know the hierarchy of
|
|
the widgets which compose <I>editres</I>. In the notation below,
|
|
indentation indicates hierarchical structure. The widget class name
|
|
is given first, followed by the widget instance name.
|
|
<P>
|
|
|
|
|
|
<PRE>
|
|
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
|
|
</PRE>
|
|
|
|
<P>
|
|
<A NAME="lbAM"> </A>
|
|
<H2>ENVIRONMENT</H2>
|
|
|
|
<P>
|
|
|
|
<DL COMPACT>
|
|
<DT id="43"><B>DISPLAY</B>
|
|
|
|
<DD>
|
|
to get the default host and display number.
|
|
<DT id="44"><B>XENVIRONMENT</B>
|
|
|
|
<DD>
|
|
to get the name of a resource file that overrides the global resources
|
|
stored in the RESOURCE_MANAGER property.
|
|
</DL>
|
|
<A NAME="lbAN"> </A>
|
|
<H2>FILES</H2>
|
|
|
|
<DL COMPACT>
|
|
<DT id="45"><I>/etc/X11/app-defaults/Editres</I>
|
|
|
|
<DD>
|
|
specifies required resources
|
|
</DL>
|
|
<A NAME="lbAO"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
<A HREF="/cgi-bin/man/man2html?7+X">X</A>(7), <A HREF="/cgi-bin/man/man2html?1+xrdb">xrdb</A>(1), Athena Widget Set
|
|
<A NAME="lbAP"> </A>
|
|
<H2>RESTRICTIONS</H2>
|
|
|
|
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.
|
|
<A NAME="lbAQ"> </A>
|
|
<H2>AUTHOR</H2>
|
|
|
|
Chris D. Peterson, formerly MIT X Consortium
|
|
<P>
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="46"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="47"><A HREF="#lbAC">SYNTAX</A><DD>
|
|
<DT id="48"><A HREF="#lbAD">OPTIONS</A><DD>
|
|
<DT id="49"><A HREF="#lbAE">DESCRIPTION</A><DD>
|
|
<DT id="50"><A HREF="#lbAF">USING EDITRES</A><DD>
|
|
<DT id="51"><A HREF="#lbAG">COMMANDS</A><DD>
|
|
<DT id="52"><A HREF="#lbAH">TREE COMMANDS</A><DD>
|
|
<DT id="53"><A HREF="#lbAI">USING THE RESOURCE BOX</A><DD>
|
|
<DT id="54"><A HREF="#lbAJ">BLOCKING EDITRES REQUESTS</A><DD>
|
|
<DT id="55"><A HREF="#lbAK">RESOURCES</A><DD>
|
|
<DT id="56"><A HREF="#lbAL">WIDGETS</A><DD>
|
|
<DT id="57"><A HREF="#lbAM">ENVIRONMENT</A><DD>
|
|
<DT id="58"><A HREF="#lbAN">FILES</A><DD>
|
|
<DT id="59"><A HREF="#lbAO">SEE ALSO</A><DD>
|
|
<DT id="60"><A HREF="#lbAP">RESTRICTIONS</A><DD>
|
|
<DT id="61"><A HREF="#lbAQ">AUTHOR</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:11 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|