424 lines
17 KiB
Groff
424 lines
17 KiB
Groff
'\" t
|
|
.\" $Xorg: editres.man,v 1.4 2001/02/09 02:05:29 xorgcvs Exp $
|
|
.\" Copyright 1993, 1994, 1998 The Open Group
|
|
.\"
|
|
.\" Permission to use, copy, modify, distribute, and sell this software and its
|
|
.\" documentation for any purpose is hereby granted without fee, provided that
|
|
.\" the above copyright notice appear in all copies and that both that
|
|
.\" copyright notice and this permission notice appear in supporting
|
|
.\" documentation.
|
|
.\"
|
|
.\" The above copyright notice and this permission notice shall be included
|
|
.\" in all copies or substantial portions of the Software.
|
|
.\"
|
|
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
|
|
.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
|
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
|
.\" IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR
|
|
.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
|
|
.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
|
|
.\" OTHER DEALINGS IN THE SOFTWARE.
|
|
.\"
|
|
.\" Except as contained in this notice, the name of The Open Group shall
|
|
.\" not be used in advertising or otherwise to promote the sale, use or
|
|
.\" other dealings in this Software without prior written authorization
|
|
.\" from The Open Group.
|
|
.\"
|
|
.\" $XFree86: xc/programs/editres/editres.man,v 1.8 2001/12/14 20:00:42 dawes Exp $
|
|
.\"
|
|
.TH EDITRES 1 __xorgversion__
|
|
.SH NAME
|
|
editres \- a dynamic resource editor for X Toolkit applications
|
|
.SH SYNTAX
|
|
\fBeditres\fP [ \fI\-toolkitoption\fP .\|.\|. ]
|
|
.SH OPTIONS
|
|
.I Editres
|
|
accepts all of the standard X Toolkit command line
|
|
options (see \fIX(__miscmansuffix__)\fP). The order of the command line options is
|
|
not important.
|
|
.SH DESCRIPTION
|
|
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.
|
|
.SH USING EDITRES
|
|
.I Editres
|
|
provides a window consisting of the following four areas:
|
|
.IP "Menu Bar" 25
|
|
A set of popup menus that allow you full access to editres's features.
|
|
.IP "Panner"
|
|
The panner allows a more intuitive way to scroll the application tree display.
|
|
.IP "Message Area"
|
|
Displays information to the user about the action that editres expects
|
|
of her.
|
|
.IP "Application Widget Tree" 25
|
|
This area will be used to display the selected application's widget tree.
|
|
.LP
|
|
To begin an editres session select the \fBGet Widget Tree\fP 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.
|
|
.LP
|
|
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.
|
|
.SH COMMANDS
|
|
.IP "Get Widget Tree" 8
|
|
Allows the user to click on any application that speaks the editres
|
|
protocol and receive its widget tree.
|
|
.IP "Refresh Current 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.
|
|
.IP
|
|
For example,
|
|
xman only creates the widgets for its \fItopbox\fP when it
|
|
starts up. None of the widgets for the manual page window are created
|
|
until the user actually clicks on the \fIManual Page\fP 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.
|
|
.IP "Dump Widget Tree to a File"
|
|
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 \fIokay\fP, or type a carriage-return. Editres
|
|
will now dump the widget tree to this file. To cancel the file dialog,
|
|
select the \fIcancel\fP button.
|
|
.IP "Show Resource Box"
|
|
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 \fBMessage Area\fP.
|
|
.IP "Set Resource"
|
|
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.
|
|
.IP "Quit"
|
|
Exits editres.
|
|
.SH TREE COMMANDS
|
|
The \fBTree\fP menu contains several commands that allow operations to
|
|
be performed on the widget tree.
|
|
.IP "Select Widget in Client"
|
|
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.
|
|
.IP "Select All"
|
|
.IP "Unselect All"
|
|
.IP "Invert All"
|
|
These functions allow the user to select, unselect, or invert all
|
|
widgets in the widget tree.
|
|
.IP "Select Children"
|
|
.IP "Select Parents"
|
|
These functions select the immediate parent or children of each of the
|
|
currently selected widgets.
|
|
.IP "Select Descendants"
|
|
.IP "Select Ancestors"
|
|
These functions select all parents or children of each of the
|
|
currently selected widgets. This is a recursive search.
|
|
.IP "Show Widget Names"
|
|
.IP "Show Class Names"
|
|
.IP "Show Widget IDs"
|
|
.IP "Show Widget Windows"
|
|
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 \fBall\fP 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.
|
|
.LP
|
|
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.
|
|
.LP
|
|
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.
|
|
.IP "Flash Active Widgets"
|
|
This command is the inverse of the \fBSelect Widget in Client\fP
|
|
command, it will show the user each widget that is currently selected in
|
|
the widget tree, by flashing the corresponding widget in the
|
|
application \fInumFlashes\fP (three by default) times in the
|
|
\fIflashColor\fP.
|
|
.sp
|
|
.TS
|
|
lb lb lb
|
|
l l l.
|
|
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)
|
|
.TE
|
|
.sp
|
|
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.
|
|
.sp
|
|
.SH USING THE RESOURCE BOX
|
|
The resource box contains five different areas. Each of the areas,
|
|
as they appear on the screen, from top to bottom will be discussed.
|
|
.IP "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.
|
|
.IP "The Widget Names and Classes"
|
|
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 (\fB.\fP) separator. The second line contains less specific the
|
|
Class names
|
|
of each widget, and well as the less restrictive star (\fB*\fP) separator.
|
|
The third line contains a set of special buttons called \fBAny Widget\fP
|
|
which will generalize this level to match any widget.
|
|
The last line contains a set of special buttons called \fBAny
|
|
Widget Chain\fP which will turn the single level into something that
|
|
matches zero or more levels.
|
|
.sp
|
|
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
|
|
\fBAny Widget Chain\fP 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.
|
|
.IP "Normal and Constraint Resources"
|
|
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.
|
|
.IP "Resource Value"
|
|
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:
|
|
.sp
|
|
\\n - This will be replaced with a newline.
|
|
.sp
|
|
\\### - 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.
|
|
.sp
|
|
\\<new-line> - This will compress to nothing.
|
|
.sp
|
|
\\\\ - This will compress to a single backslash.
|
|
.IP "Command Area"
|
|
This area contains several command buttons, described in
|
|
this section.
|
|
.IP "Set Save File"
|
|
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 \fIokay\fP button. To pop down the
|
|
dialog box without changing the save file, click the \fIcancel\fP button.
|
|
.IP "Save"
|
|
This button will append the \fBresource line\fP described above to the
|
|
end of the current save file. If no save file has been set the \fBSet
|
|
Save File\fP dialog box will be popped up to prompt the user for a filename.
|
|
.IP "Apply"
|
|
This button attempts to perform a XtSetValues call on all widgets
|
|
that match the \fBresource line\fP 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 \fBBlocking Editres Requests\fP below).
|
|
.sp
|
|
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.
|
|
.IP "Save and Apply"
|
|
This button combines the Save and Apply actions described above into
|
|
one button.
|
|
.IP "Popdown Resource Box"
|
|
This button will remove the resource box from the display.
|
|
.SH BLOCKING EDITRES REQUESTS
|
|
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 \fBeditresBlock\fP
|
|
resource described below, to keep editres from divulging information
|
|
about its internals, or to disable the \fBSetValues\fP part of the protocol.
|
|
.TP 8
|
|
.B editresBlock (\fPClass\fB EditresBlock)
|
|
Specifies which type of blocking this application wishes to impose on the
|
|
editres protocol.
|
|
.LP
|
|
The accepted values are:
|
|
.IP all 15
|
|
Block all requests.
|
|
.IP setValues
|
|
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.
|
|
.IP none
|
|
Allow all editres requests.
|
|
.LP
|
|
Remember that these resources are set on any Xaw application, \fBnot
|
|
editres\fP. 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 \fBeditresBlock\fP resource on editres itself.
|
|
.SH RESOURCES
|
|
For \fIeditres\fP the available application resources are:
|
|
.TP 8
|
|
.B numFlashes (\fPClass\fB NumFlashes)
|
|
Specifies the number of times the widgets in the application
|
|
will be flashed when the \fBShow Active Widgets\fP command in invoked.
|
|
.TP 8
|
|
.B flashTime (\fPClass\fB FlashTime)
|
|
Amount of time between the flashes described above.
|
|
.TP 8
|
|
.B flashColor (\fPClass\fB flashColor)
|
|
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.
|
|
.TP 8
|
|
.B saveResourcesFile (\fPClass\fB SaveResourcesFile)
|
|
This is the file the resource line will be append to when the \fBSave\fP
|
|
button activated in the resource box.
|
|
.SH WIDGETS
|
|
In order to specify resources, it is useful to know the hierarchy of
|
|
the widgets which compose \fIeditres\fP. In the notation below,
|
|
indentation indicates hierarchical structure. The widget class name
|
|
is given first, followed by the widget instance name.
|
|
.sp
|
|
.nf
|
|
.TA .5i 1.0i 1.5i 2.0i
|
|
.ta .5i 1.0i 1.5i 2.0i
|
|
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
|
|
.fi
|
|
.sp
|
|
.SH ENVIRONMENT
|
|
.PP
|
|
.TP 8
|
|
.B DISPLAY
|
|
to get the default host and display number.
|
|
.TP 8
|
|
.B XENVIRONMENT
|
|
to get the name of a resource file that overrides the global resources
|
|
stored in the RESOURCE_MANAGER property.
|
|
.SH FILES
|
|
.TP
|
|
.I __apploaddir__/Editres
|
|
specifies required resources
|
|
.SH SEE ALSO
|
|
X(__miscmansuffix__), xrdb(1), Athena Widget Set
|
|
.SH RESTRICTIONS
|
|
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.
|
|
.SH AUTHOR
|
|
Chris D. Peterson, formerly MIT X Consortium
|
|
|