From 0d02b3888a6a0d5f7197c17ab4bfd9d31c8799df Mon Sep 17 00:00:00 2001 From: Gaetan Nadon Date: Wed, 19 Jan 2011 10:06:55 -0500 Subject: config: move man pages into their own directory Use services provided by XORG_MANPAGE_SECTIONS. Use standard Makefile for man pages. Signed-off-by: Gaetan Nadon --- Makefile.am | 20 +-- configure.ac | 5 +- editres.man | 423 -------------------------------------------------------- man/Makefile.am | 12 ++ man/editres.man | 423 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 441 insertions(+), 442 deletions(-) delete mode 100644 editres.man create mode 100644 man/Makefile.am create mode 100644 man/editres.man diff --git a/Makefile.am b/Makefile.am index e70e2a1..2169e87 100644 --- a/Makefile.am +++ b/Makefile.am @@ -19,6 +19,7 @@ # TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR # PERFORMANCE OF THIS SOFTWARE. +SUBDIRS = man bin_PROGRAMS = editres AM_CFLAGS = $(CWARNFLAGS) $(EDITRES_CFLAGS) @@ -37,9 +38,6 @@ editres_SOURCES = \ widgets.c \ wtree.c -appman_PRE = \ - editres.man - # App default files (*.ad) DISTCHECK_CONFIGURE_FLAGS = --with-appdefaultdir=\$${datadir}/X11/app-defaults @@ -50,7 +48,7 @@ dist_appdefault_DATA = \ app-defaults/Editres-color \ app-defaults/Editres - +MAINTAINERCLEANFILES = ChangeLog INSTALL .PHONY: ChangeLog INSTALL @@ -61,17 +59,3 @@ ChangeLog: $(CHANGELOG_CMD) dist-hook: ChangeLog INSTALL - -appmandir = $(APP_MAN_DIR) - -appman_DATA = $(appman_PRE:man=@APP_MAN_SUFFIX@) - -EXTRA_DIST = $(appman_PRE) autogen.sh -MAINTAINERCLEANFILES = ChangeLog INSTALL -CLEANFILES = $(appman_DATA) - -SUFFIXES = .$(APP_MAN_SUFFIX) .man - -# String replacements in MAN_SUBSTS now come from xorg-macros.m4 via configure -.man.$(APP_MAN_SUFFIX): - $(AM_V_GEN)$(SED) $(MAN_SUBSTS) < $< > $@ diff --git a/configure.ac b/configure.ac index 43f74d2..a585c2f 100644 --- a/configure.ac +++ b/configure.ac @@ -46,4 +46,7 @@ AC_ARG_WITH(appdefaultdir, [appdefaultdir="$withval"], [appdefaultdir="${xt_appdefaultdir}"]) AC_SUBST(appdefaultdir) -AC_OUTPUT([Makefile]) +AC_CONFIG_FILES([ + Makefile + man/Makefile]) +AC_OUTPUT diff --git a/editres.man b/editres.man deleted file mode 100644 index e43e55d..0000000 --- a/editres.man +++ /dev/null @@ -1,423 +0,0 @@ -'\" 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 -\\ - 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 - . - . - . - 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(__appmansuffix__), 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 - diff --git a/man/Makefile.am b/man/Makefile.am new file mode 100644 index 0000000..f43dece --- /dev/null +++ b/man/Makefile.am @@ -0,0 +1,12 @@ + +appmandir = $(APP_MAN_DIR) +appman_PRE = editres.man +appman_DATA = $(appman_PRE:man=$(APP_MAN_SUFFIX)) + +EXTRA_DIST = $(appman_PRE) +CLEANFILES = $(appman_DATA) +SUFFIXES = .$(APP_MAN_SUFFIX) .man + +# String replacements in MAN_SUBSTS now come from xorg-macros.m4 via configure +.man.$(APP_MAN_SUFFIX): + $(AM_V_GEN)$(SED) $(MAN_SUBSTS) < $< > $@ diff --git a/man/editres.man b/man/editres.man new file mode 100644 index 0000000..e43e55d --- /dev/null +++ b/man/editres.man @@ -0,0 +1,423 @@ +'\" 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 +\\ - 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 + . + . + . + 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(__appmansuffix__), 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 + -- cgit v1.2.3