1EDITRES(1) General Commands Manual EDITRES(1)
2
6 editres - a dynamic resource editor for X Toolkit applications
7
9 editres [ -toolkitoption ... ]
10
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
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
25 Editres provides a window consisting of the following four areas:
26 Menu Bar A set of popup menus that allow you full ac‐
28 cess to editres's features.
29 Panner The panner allows a more intuitive way to
31 scroll the application tree display.
32 Message Area Displays information to the user about the ac‐
34 tion that editres expects of her.
35 Application Widget Tree This area will be used to display the selected
37 application's widget tree.
38 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 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
52 Get Widget Tree
53 Allows the user to click on any application that speaks the ed‐
54 itres protocol and receive its widget tree.
55 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 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 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 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 Set Resource
90 This command will popup a simple dialog box for setting an ar‐
91 bitrary resource on all selected widgets. You must type in the
92 resource name, as well as the value. You can use the Tab key
93 to switch between the resource name field the resource value
94 field.
95 Quit Exits editres.
97
99 The Tree menu contains several commands that allow operations to be
100 performed on the widget tree.
101 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 Select All
114 Unselect All
116 Invert All
118 These functions allow the user to select, unselect, or invert
119 all widgets in the widget tree.
120 Select Children
122 Select Parents
124 These functions select the immediate parent or children of each
125 of the currently selected widgets.
126 Select Descendants
128 Select Ancestors
130 These functions select all parents or children of each of the
131 currently selected widgets. This is a recursive search.
132 Show Widget Names
134 Show Class Names
136 Show Widget IDs
138 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 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 The translation entries shown may be applied to any widget in the ap‐
154 plication. If that widget is a child of the Tree widget, then it will
155 only affect that widget, otherwise it will have the same effect as the
156 commands in the tree menu.
157 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 se‐
161 lected in the widget tree, by flashing the corresponding widget
162 in the application numFlashes (three by default) times in the
163 flashColor.
164 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 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
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 The Resource Line
194 This area at the top of the resource box shows the current re‐
195 source name exactly as it would appear if you were to save it to
196 a file or apply it.
197 The Widget Names and Classes
199 This area allows you to select exactly which widgets this re‐
200 source 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 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 al‐
214 low more and more widgets to match the specification. The ex‐
215 treme case is to select all the Any Widget Chain buttons, which
216 will match every widget in the application. As you select dif‐
217 ferent buttons the tree display will update to show you exactly
218 which widgets will be effected by the current resource specifi‐
219 cation.
220 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 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 \n - This will be replaced with a newline.
234 \### - 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 \<new-line> - This will compress to nothing.
241 \\ - This will compress to a single backslash.
243 Command Area
245 This area contains several command buttons, described in this
246 section.
247 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 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 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 be‐
264 havior is an attempt to give a dynamic feel to the resource edi‐
265 tor. Since this feature allows users to put an application in
266 states it may not be willing to handle, a hook has been provided
267 to allow specific applications to block these SetValues requests
268 (see Blocking Editres Requests below).
269 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 ed‐
279 itres, and I strongly suggest that you play with it, and see
280 what it can do.
281 Save and Apply
283 This button combines the Save and Apply actions described above
284 into one button.
285 Popdown Resource Box
287 This button will remove the resource box from the display.
288
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 re‐
295 source described below, to keep editres from divulging information
296 about its internals, or to disable the SetValues part of the protocol.
297 editresBlock (Class EditresBlock)
299 Specifies which type of blocking this application wishes to im‐
300 pose on the editres protocol.
301 The accepted values are:
303 all Block all requests.
305 setValues Block all SetValues requests. As this is the only ed‐
307 itres request that actually modifies the application,
308 this is in effect stating that the application is read-
309 only.
310 none Allow all editres requests.
312 Remember that these resources are set on any Xaw application, not ed‐
314 itres. 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 ed‐
317 itres (rather recursive, I know), these commands can be blocked by set‐
318 ting the editresBlock resource on editres itself.
319
321 For editres the available application resources are:
322 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 in‐
326 voked.
327 flashTime (Class FlashTime)
329 Amount of time between the flashes described above.
330 flashColor (Class flashColor)
332 Specifies the color used to flash application widgets. A
333 bright color should be used that will immediately draw your at‐
334 tention to the area being flashed, such as red or yellow.
335 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
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 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
416 DISPLAY to get the default host and display number.
417 XENVIRONMENT
419 to get the name of a resource file that overrides the global
420 resources stored in the RESOURCE_MANAGER property.
421
423 /usr/share/X11/app-defaults/Editres
424 specifies required resources
425
427 X(7), xrdb(1), Athena Widget Set
428
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 ed‐
432 itor can do.
433
435 Chris D. Peterson, formerly MIT X Consortium
436X Version 11 editres 1.0.8 EDITRES(1)