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
28 access 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
34 action 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
54 editres 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
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 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
115 Invert All
116 These functions allow the user to select, unselect, or invert
117 all widgets in the widget tree.
118 Select Children
120 Select Parents
121 These functions select the immediate parent or children of each
122 of the currently selected widgets.
123 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 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 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 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 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 Key Option Translation Entry
158 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 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
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 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 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 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 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 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 \n - This will be replaced with a newline.
225 \### - 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 \<new-line> - This will compress to nothing.
232 \\ - This will compress to a single backslash.
234 Command Area
236 This area contains several command buttons, described in this
237 section.
238 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 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 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 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 Save and Apply
274 This button combines the Save and Apply actions described above
275 into one button.
276 Popdown Resource Box
278 This button will remove the resource box from the display.
279
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 editresBlock (Class EditresBlock)
290 Specifies which type of blocking this application wishes to
291 impose on the editres protocol.
292 The accepted values are:
294 all Block all requests.
296 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 none Allow all editres requests.
303 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
312 For editres the available application resources are:
313 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 flashTime (Class FlashTime)
320 Amount of time between the flashes described above.
321 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 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
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 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
407 DISPLAY to get the default host and display number.
408 XENVIRONMENT
410 to get the name of a resource file that overrides the global
411 resources stored in the RESOURCE_MANAGER property.
412
414 /usr/share/X11/app-defaults/Editres
415 specifies required resources
416
418 X(7), xrdb(1), Athena Widget Set
419
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
426 Chris D. Peterson, formerly MIT X Consortium
427X Version 11 editres 1.0.1 EDITRES(1)