1EDITRES(1)                  General Commands Manual                 EDITRES(1)
2
3
4

NAME

6       editres - a dynamic resource editor for X Toolkit applications
7

SYNTAX

9       editres [ -toolkitoption ... ]
10

OPTIONS

12       Editres accepts all of the standard X Toolkit command line options (see
13       X(7)).  The order of the command line options is not important.
14

DESCRIPTION

16       Editres is a tool that allows users and application developers to  view
17       the  full widget hierarchy of any X Toolkit application that speaks the
18       Editres protocol.  In addition, editres will help  the  user  construct
19       resource  specifications,  allow  the user to apply the resource to the
20       application and view the results dynamically.  Once the user  is  happy
21       with  a  resource specification editres will append the resource string
22       to the user's X Resources file.
23

USING EDITRES

25       Editres provides a window consisting of the following four areas:
26
27       Menu Bar                 A set of  popup  menus  that  allow  you  full
28                                access to editres's features.
29
30       Panner                   The  panner  allows  a  more  intuitive way to
31                                scroll the application tree display.
32
33       Message Area             Displays information to  the  user  about  the
34                                action that editres expects of her.
35
36       Application Widget Tree  This area will be used to display the selected
37                                application's widget tree.
38
39       To begin an editres session select the Get Widget Tree menu  item  from
40       the  command  menu.  This will change the pointer cursor to cross hair.
41       You should now select the application you wish look at by  clicking  on
42       any of its windows.  If this application understands the editres proto‐
43       col then editres will display the application's widget tree in its tree
44       window.   If  the  application does not understand the editres protocol
45       editres will inform you of this fact in the message area  after  a  few
46       seconds delay.
47
48       Once  you  have  a widget tree you may now select any of the other menu
49       options. The effect of each of these is described below.
50

COMMANDS

52       Get Widget Tree
53               Allows the user to click on any  application  that  speaks  the
54               editres protocol and receive its widget tree.
55
56       Refresh Current Widget Tree
57               Editres  only knows about the widgets that exist at the present
58               time.  Many applications create and destroy widgets on the fly.
59               Selecting this menu item will cause editres to ask the applica‐
60               tion to resend its widget tree, thus updating  its  information
61               to the new state of the application.
62
63               For  example, xman only creates the widgets for its topbox when
64               it starts up.  None of the widgets for the manual  page  window
65               are  created  until the user actually clicks on the Manual Page
66               button.  If you retrieved xman's widget  tree  before  the  the
67               manual  page is active, you may wish to refresh the widget tree
68               after the manual page has been displayed.  This will allow  you
69               to also edit the manual page's resources.
70
71       Dump Widget Tree to a File
72               For  documenting  applications it is often useful to be able to
73               dump the entire application widget tree to an ASCII file.  This
74               file  can  then be included in the manual page.  When this menu
75               item is selected a popup dialog is activated.  Type the name of
76               the file in this dialog, and either select okay, or type a car‐
77               riage-return.  Editres will now dump the widget  tree  to  this
78               file.  To cancel the file dialog, select the cancel button.
79
80       Show Resource Box
81               This command will popup a resource box for the current applica‐
82               tion.  This resource box (described in detail below) will allow
83               the user to see exactly which resources can be set for the wid‐
84               get that is currently selected  in  the  widget  tree  display.
85               Only  one widget may be currently selected; if greater or fewer
86               are selected editres will refuse to pop up the resource box and
87               put an error message in the Message Area.
88
89       Set Resource
90               This  command  will  popup  a  simple dialog box for setting an
91               arbitrary resource on all selected widgets.  You must  type  in
92               the  resource  name, as well as the value.  You can use the Tab
93               key to switch between the  resource  name  field  the  resource
94               value field.
95
96       Quit    Exits editres.
97

TREE COMMANDS

99       The  Tree  menu  contains  several commands that allow operations to be
100       performed on the widget tree.
101
102       Select Widget in Client
103              This menu item allows you to select any widget in  the  applica‐
104              tion;  editres will then highlight the corresponding element the
105              widget tree display.   Once  this  menu  item  is  selected  the
106              pointer  cursor  will  again  turn  to a crosshair, and you must
107              click any pointer button in the widget you  wish  to  have  dis‐
108              played.   Since  some  widgets are fully obscured by their chil‐
109              dren, it is not possible to get to every widget  this  way,  but
110              this  mechanism  does give very useful feedback between the ele‐
111              ments in the widget tree and those in the actual application.
112
113       Select All
114
115       Unselect All
116
117       Invert All
118              These functions allow the user to select,  unselect,  or  invert
119              all widgets in the widget tree.
120
121       Select Children
122
123       Select Parents
124              These  functions select the immediate parent or children of each
125              of the currently selected widgets.
126
127       Select Descendants
128
129       Select Ancestors
130              These functions select all parents or children of  each  of  the
131              currently selected widgets.  This is a recursive search.
132
133       Show Widget Names
134
135       Show Class Names
136
137       Show Widget IDs
138
139       Show Widget Windows
140              When  the  tree widget is initially displayed the labels of each
141              widget in the tree correspond to the widget names.  These  func‐
142              tions  will  cause  the  label  of all widgets in the tree to be
143              changed to show the class name, IDs, or window  associated  with
144              each widget in the application.  The widget IDs, and windows are
145              shown as hex numbers.
146
147       In addition there are keyboard accelerators for each of the Tree opera‐
148       tions.   If  the  input focus is over an individual widget in the tree,
149       then that operation will only effect that widget.  If the  input  focus
150       is  in  the Tree background it will have exactly the same effect as the
151       corresponding menu item.
152
153       The translation entries shown may be  applied  to  any  widget  in  the
154       application.   If  that  widget  is a child of the Tree widget, then it
155       will only affect that widget, otherwise it will have the same effect as
156       the commands in the tree menu.
157
158       Flash Active Widgets
159              This  command is the inverse of the Select Widget in Client com‐
160              mand, it will show  the  user  each  widget  that  is  currently
161              selected  in the widget tree, by flashing the corresponding wid‐
162              get in the application numFlashes (three by  default)  times  in
163              the flashColor.
164
165
166              Key     Option                     Translation Entry
167              -
168              space   Unselect                   Select(nothing)
169              w       Select                     Select(widget)
170              s       Select                     Select(all)
171              i       Invert                     Select(invert)
172              c       Select Children            Select(children)
173              d       Select Descendants         Select(descendants)
174              p       Select Parent              Select(parent)
175              a       Select Ancestors           Select(ancestors)
176              N       Show Widget Names          Relabel(name)
177              C       Show Class Names           Relabel(class)
178              I       Show Widget IDs            Relabel(id)
179              W       Show Widget Windows        Relabel(window)
180              T       Toggle Widget/Class Name   Relabel(toggle)
181
182              Clicking  button  1  on  a widget adds it to the set of selected
183              widgets.  Clicking button 2 on a widget deselects all other wid‐
184              gets  and then selects just that widget.  Clicking button 3 on a
185              widget toggles its label between the widget's instance name  the
186              widget's class name.
187
188

USING THE RESOURCE BOX

190       The  resource box contains five different areas.  Each of the areas, as
191       they appear on the screen, from top to bottom will be discussed.
192
193       The Resource Line
194              This area at the top of  the  resource  box  shows  the  current
195              resource  name exactly as it would appear if you were to save it
196              to a file or apply it.
197
198       The Widget Names and Classes
199              This area allows  you  to  select  exactly  which  widgets  this
200              resource will apply to.  The area contains four lines, the first
201              contains the name of the selected widget and all its  ancestors,
202              and  the  more  restrictive  dot (.) separator.  The second line
203              contains less specific the Class names of each widget, and  well
204              as the less restrictive star (*) separator.  The third line con‐
205              tains a set of special buttons called Any Widget which will gen‐
206              eralize  this level to match any widget.  The last line contains
207              a set of special buttons called Any Widget Chain which will turn
208              the  single  level into something that matches zero or more lev‐
209              els.
210
211              The initial state of this area is the  most  restrictive,  using
212              the  resource  names  and  the  dot separator.  By selecting the
213              other buttons in this area you  can  ease  the  restrictions  to
214              allow  more  and  more  widgets to match the specification.  The
215              extreme case is to select all  the  Any  Widget  Chain  buttons,
216              which  will  match  every  widget  in  the application.   As you
217              select different buttons the tree display will  update  to  show
218              you  exactly  which  widgets  will  be  effected  by the current
219              resource specification.
220
221       Normal and Constraint Resources
222              The next area allows you to select the name  of  the  normal  or
223              constraint resources you wish to set.  Some widgets may not have
224              constraint resources, so that area will not appear.
225
226       Resource Value
227              This next area allows you to enter  the  resource  value.   This
228              value  should  be  entered exactly as you would type a line into
229              your resource file.  Thus it should contain  no  unescaped  new-
230              lines.   There  are  a  few special character sequences for this
231              file:
232
233              \n - This will be replaced with a newline.
234
235              \### - Where # is any octal digit.  This will be replaced with a
236              single  byte that contains this sequence interpreted as an octal
237              number.  For example, a value containing  a  NULL  byte  can  be
238              stored by specifying \000.
239
240              \<new-line> - This will compress to nothing.
241
242              \\ - This will compress to a single backslash.
243
244       Command Area
245              This  area  contains  several command buttons, described in this
246              section.
247
248       Set Save File
249              This button allows the user to modify file  that  the  resources
250              will  be  saved to.  This button will bring up a dialog box that
251              will ask you for a filename; once the filename has been entered,
252              either  hit carriage-return or click on the okay button.  To pop
253              down the dialog box without changing the save  file,  click  the
254              cancel button.
255
256       Save   This button will append the resource line described above to the
257              end of the current save file.  If no save file has been set  the
258              Set  Save  File  dialog box will be popped up to prompt the user
259              for a filename.
260
261       Apply  This button attempts to perform a XtSetValues call on  all  wid‐
262              gets  that  match  the resource line described above.  The value
263              specified is applied directly to  all  matching  widgets.   This
264              behavior  is  an  attempt to give a dynamic feel to the resource
265              editor.  Since this feature allows users to put  an  application
266              in  states it may not be willing to handle, a hook has been pro‐
267              vided to allow specific applications to  block  these  SetValues
268              requests (see Blocking Editres Requests below).
269
270              Unfortunately  due  to design constraints imposed on the widgets
271              by the X Toolkit and the Resource Manager, trying to  coerce  an
272              inherently static system into dynamic behavior can cause strange
273              results.  There is no guarantee that the  results  of  an  apply
274              will be the same as what will happen when you save the value and
275              restart the application.  This functionality is provided to  try
276              to  give you a rough feel for what your changes will accomplish,
277              and the results obtained should be considered suspect  at  best.
278              Having  said  that,  this  is  one  of  the  neatest features of
279              editres, and I strongly suggest that you play with it,  and  see
280              what it can do.
281
282       Save and Apply
283              This  button combines the Save and Apply actions described above
284              into one button.
285
286       Popdown Resource Box
287              This button will remove the resource box from the display.
288

BLOCKING EDITRES REQUESTS

290       The editres protocol has been built into the Athena Widget  set.   This
291       allows all applications that are linked against Xaw to be able to speak
292       to the resource editor.  While this provides great flexibility, and  is
293       a useful tool, it can quite easily be abused.  It is therefore possible
294       for any Xaw  application  to  specify  a  value  for  the  editresBlock
295       resource  described  below,  to keep editres from divulging information
296       about its internals, or to disable the SetValues part of the protocol.
297
298       editresBlock (Class EditresBlock)
299               Specifies which type of blocking  this  application  wishes  to
300               impose on the editres protocol.
301
302       The accepted values are:
303
304       all            Block all requests.
305
306       setValues      Block  all  SetValues  requests.   As  this  is the only
307                      editres request that actually modifies the  application,
308                      this  is in effect stating that the application is read-
309                      only.
310
311       none           Allow all editres requests.
312
313       Remember that these resources are  set  on  any  Xaw  application,  not
314       editres.  They allow individual applications to keep all or some of the
315       requests editres makes from ever succeeding.   Of  course,  editres  is
316       also  an  Xaw  application,  so  it  may also be viewed and modified by
317       editres (rather recursive, I know), these commands can  be  blocked  by
318       setting the editresBlock resource on editres itself.
319

RESOURCES

321       For editres the available application resources are:
322
323       numFlashes (Class NumFlashes)
324               Specifies  the  number  of times the widgets in the application
325               will be  flashed  when  the  Show  Active  Widgets  command  in
326               invoked.
327
328       flashTime (Class FlashTime)
329               Amount of time between the flashes described above.
330
331       flashColor (Class flashColor)
332               Specifies  the  color  used  to  flash  application widgets.  A
333               bright color should be used that  will  immediately  draw  your
334               attention to the area being flashed, such as red or yellow.
335
336       saveResourcesFile (Class SaveResourcesFile)
337               This  is  the file the resource line will be append to when the
338               Save button activated in the resource box.
339

WIDGETS

341       In order to specify resources, it is useful to know  the  hierarchy  of
342       the  widgets which compose editres.  In the notation below, indentation
343       indicates hierarchical structure.   The  widget  class  name  is  given
344       first, followed by the widget instance name.
345
346       Editres  editres
347            Paned  paned
348                                       Box  box
349                                                             MenuButton  commands
350                                                             SimpleMenu  menu
351                                                             SmeBSB  sendTree
352                                                             SmeBSB  refreshTree
353                                                             SmeBSB  dumpTreeToFile
354                                                             SmeLine  line
355                                                             SmeBSB  getResourceList
356                                                             SmeLine  line
357                                                             SmeBSB  quit
358                                                             MenuButton  treeCommands
359                                                             SimpleMenu  menu
360                                                             SmeBSB  showClientWidget
361                                                             SmeBSB  selectAll
362                                                             SmeBSB  unselectAll
363                                                             SmeBSB  invertAll
364                                                             SmeLine  line
365                                                             SmeBSB  selectChildren
366                                                             SmeBSB  selectParent
367                                                             SmeBSB  selectDescendants
368                                                             SmeBSB  selectAncestors
369                                                             SmeLine  line
370                                                             SmeBSB  showWidgetNames
371                                                             SmeBSB  showClassNames
372                                                             SmeBSB  showWidgetIDs
373                                                             SmeBSB  showWidgetWindows
374                                                             SmeLine  line
375                                                             SmeBSB  flashActiveWidgets
376                                       Paned  hPane
377                                                             Panner  panner
378                                                             Label  userMessage
379                                                             Grip  grip
380                                       Porthole  porthole
381                                                             Tree  tree
382                                                             Toggle  <name of widget in application>
383                                                             .
384                                                             .
385                                                             .
386                                                             TransientShell  resourceBox
387                                                             Paned  pane
388                                                             Label  resourceLabel
389                                                             Form  namesAndClasses
390                                                             Toggle  dot
391                                                             Toggle  star
392                                                             Toggle  any
393                                                             Toggle  name
394                                                             Toggle  class
395                                                                  .
396                                                                  .
397                                                                  .
398                                                             Label  namesLabel
399                                                             List  namesList
400                                                             Label  constraintLabel
401                                                             List  constraintList
402                                                             Form  valueForm
403                                                             Label  valueLabel
404                                                             Text  valueText
405                                                             Box  commandBox
406                                                             Command  setFile
407                                                             Command  save
408                                                             Command  apply
409                                                             Command  saveAndApply
410                                                             Command  cancel
411                                                             Grip  grip
412                                       Grip  grip
413
414

ENVIRONMENT

416       DISPLAY to get the default host and display number.
417
418       XENVIRONMENT
419               to  get  the  name of a resource file that overrides the global
420               resources stored in the RESOURCE_MANAGER property.
421

FILES

423       /usr/share/X11/app-defaults/Editres
424              specifies required resources
425

SEE ALSO

427       X(7), xrdb(1), Athena Widget Set
428

RESTRICTIONS

430       This is a prototype, there are lots of nifty features I would  love  to
431       add,  but  I  hope  this will give you some ideas about what a resource
432       editor can do.
433

AUTHOR

435       Chris D. Peterson, formerly MIT X Consortium
436
437
438
439
440X Version 11                     editres 1.0.7                      EDITRES(1)
Impressum