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       Unselect All
115       Invert All
116              These functions allow the user to select,  unselect,  or  invert
117              all widgets in the widget tree.
118
119       Select Children
120       Select Parents
121              These  functions select the immediate parent or children of each
122              of the currently selected widgets.
123
124       Select Descendants
125       Select Ancestors
126              These functions select all parents or children of  each  of  the
127              currently selected widgets.  This is a recursive search.
128
129       Show Widget Names
130       Show Class Names
131       Show Widget Windows
132              When  the  tree widget is initially displayed the labels of each
133              widget in the tree correspond to the widget names.  These  func‐
134              tions  will  cause  the  label  of all widgets in the tree to be
135              changed to show the class name, IDs, or window  associated  with
136              each widget in the application.  The widget IDs, and windows are
137              shown as hex numbers.
138
139       In addition there are keyboard accelerators for each of the Tree opera‐
140       tions.   If  the  input focus is over an individual widget in the tree,
141       then that operation will only effect that widget.  If the  input  focus
142       is  in  the Tree background it will have exactly the same effect as the
143       corresponding menu item.
144
145       The translation entries shown may be  applied  to  any  widget  in  the
146       application.   If  that  widget  is a child of the Tree widget, then it
147       will only affect that widget, otherwise it will have the same effect as
148       the commands in the tree menu.
149
150       Flash Active Widgets
151              This  command is the inverse of the Select Widget in Client com‐
152              mand, it will show  the  user  each  widget  that  is  currently
153              selected  in the widget tree, by flashing the corresponding wid‐
154              get in the application numFlashes (three by  default)  times  in
155              the flashColor.
156
157                   Key       Option                   Translation Entry
158
159                   space     Unselect                 Select(nothing)
160                   w         Select                   Select(widget)
161                   s         Select                   Select(all)
162                   i         Invert                   Select(invert)
163                   c         Select Children          Select(children)
164                   d         Select Descendants       Select(descendants)
165                   p         Select Parent            Select(parent)
166                   a         Select Ancestors         Select(ancestors)
167                   N         Show Widget Names        Relabel(name)
168                   C         Show Class Names         Relabel(class)
169                   I         Show Widget IDs          Relabel(id)
170                   W         Show Widget Windows      Relabel(window)
171                   T         Toggle Widget/Class Name Relabel(toggle)
172
173              Clicking  button  1  on  a widget adds it to the set of selected
174              widgets.  Clicking button 2 on a widget deselects all other wid‐
175              gets  and then selects just that widget.  Clicking button 3 on a
176              widget toggles its label between the widget's instance name  the
177              widget's class name.
178
179

USING THE RESOURCE BOX

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

BLOCKING EDITRES REQUESTS

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

RESOURCES

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

WIDGETS

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

ENVIRONMENT

407       DISPLAY to get the default host and display number.
408
409       XENVIRONMENT
410               to  get  the  name of a resource file that overrides the global
411               resources stored in the RESOURCE_MANAGER property.
412

FILES

414       /usr/share/X11/app-defaults/Editres
415              specifies required resources
416

SEE ALSO

418       X(7), xrdb(1), Athena Widget Set
419

RESTRICTIONS

421       This is a prototype, there are lots of nifty features I would  love  to
422       add,  but  I  hope  this will give you some ideas about what a resource
423       editor can do.
424

AUTHOR

426       Chris D. Peterson, formerly MIT X Consortium
427
428
429
430
431X Version 11                     editres 1.0.1                      EDITRES(1)
Impressum