editres(1X) editres(1X)NAME editres - edits resources for X Toolkit applications SYNOPSIS editres [ toolkit-option ] ... DESCRIPTION editres allows you as a user or application developer to view the full widget hierarchy of any X Toolkit application client that understands the editres protocol. In addition, editres helps you construct resource specifications and al- lows you to apply the resource to the client application and view the results dynamically. Once you are happy with a resource specification, editres appends the resource string to your X resources file. Options The editres command accepts all of the standard X Toolkit command-line options. See X(1X)) for details. The order of the command-line options is not important. Using editres The editres command displays a window that has four areas: Menu bar This area provides a set of pop-up menus that allow full access to editres features. Panner This area provides an intuitive way to scroll the client application's widget tree display. Message area This area displays information about the action that editres expects. Application widget tree This area displays the selected client application's widget tree. To begin an editres session, start editres and chose the Get Widget Tree menu item from the Command menu. This changes the pointer to a crosshair. Select the client application you wish look at by clicking on any of its windows. If the application understands the editres protocol, editres displays the applications's widget tree in the editres tree window. If the application does not understand the editres protocol, editres writes in the Message area after a few seconds delay. Once you have a widget tree, you can choose items from any of the other editres menus. The effect of choosing these menu items is described in the following section. November, 1990 1
editres(1X) editres(1X)Command menu Get Widget Tree Allows you to click on the window of any client ap- plication that understands the editres protocol and receive the application's widget tree. Refresh Current Widget Tree Asks the client application to resend its widget tree, so editres updates its information to the new state of the application. This menu item is useful because editres only knows about the widgets that exist at the present time. The widget tree changes because many applications can create and destroy widgets at any time. For example, the xman client application only creates the widgets for its initial window when it starts up. None of the widgets for the manual page window are created until you actual- ly click the Manual Page button. If you retrieve the widget tree for xman before the manual page win- dow is active, you may wish to refresh the widget tree after the manual page window has been displayed. Then you can edit the manual page's resources. Select Widget in Client Allows you to select any widget in the client appli- cation to highlight the corresponding element of the widget tree display. Once you select this menu item, the pointer again turns to a crosshair, and you click any button in the widget you wish to have displayed. Because 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 client applica- tion. Dump Widget Tree to a File Dumps the client application's widget tree to a specified file. When you select this menu item, a pop-up dialog box is displayed. Type the name of the file in this dialog box, and either click the Okay button or press RETURN. The editres command now dumps the widget tree to this file. To cancel the dialog box, click the Cancel button. For docu- menting applications, it is often useful to be able to dump the entire application widget tree to an ASCII file. You can then include this file in the manual page. Show Active Widgets This menu item is the reverse of the Select Widget 2 November, 1990
editres(1X) editres(1X)in Client menu item. It highlights each widget that is currently selected in the widget tree by flashing the corresponding widget in the application the number of times specified by the numFlashes resource in the color specified by the flashColor resource. Show Resource Box Displays a pop-up resource box for the current client application. The resource box (described in detail later) allows you to see exactly which resources you can set for the widget that is currently selected in the widget tree display. Only one widget may be currently selected. If more than one or none is selected, editres refuses to display the resource box but displays an error message in the Message Area. Show Author Displays a message telling you who wrote this client application. Quit Quits editres. Tree menu Several items in the Tree menu allow operations to be per- formed on the widget tree. Select All Unselect All Invert All Allow you to select, de-select, or invert all widg- ets in the widget tree. Select Children Select Parent Select the immediate children or parent of each of the currently selected widgets. Select Descendants Select Ancestors Select all children or parents of each of the currently selected widgets by performing a recursive search. Show Widget Names Show Class Names November, 1990 3
editres(1X) editres(1X)Show Widget IDs Show Widget Windows When the tree widget is initially displayed, the la- bels of each widget in the tree correspond to the widget names. These menu items cause the label of all widgets in the tree to be changed to show the class name, IDs, or window associated with each corresponding widget in the client application. The widget IDs and windows are shown as hexadecimal numbers. In addition, there are keyboard equivalents for each of the Tree menu items. If the input focus is on an individual widget in the tree, that menu item's action only affects that widget. If the input focus is on the Tree background, it has the same effect as the corresponding menu item. The translation entries shown may be applied to any widget in the client application. If that widget is a child of the Tree widget, it only affects that widget; otherwise, it has the same effect as the items in the Tree menu. Key Menu item Translation entry <space> Unselect Select(nothing) 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) Using the resource box The resource box displayed by the Show Resource Box menu item contains five different areas. The Resource Line This area at the top of the resource box shows the current resource entry exactly as it would appear if you were to save it to a file. The Widget Names and Classes This area allows you to select exactly which widgets this resource applies to. The area contains three lines. The first line contains the name of the selected widget, all its ancestors, and the more restrictive dot (.) separator. The second line con- 4 November, 1990
editres(1X) editres(1X)tains the less specific class names of each widget, as well as the less restrictive asterisk (*) separa- tor. The third line contains a set of special but- tons called Allow Any Widget that completely compress this level of the widget hierarchy and re- place it with just the asterisk separator. As you select different buttons, the tree display updates to show you exactly which widgets are affected by the current resource specification. The initial state of this area is the most restric- tive, using the resource names and the dot separa- tor. By selecting the other buttons in this area, you can ease the restrictions to allow more and more widgets to match the specification. The least res- trictive case is to select all the Allow Any Widget buttons, which matches every widget in the applica- tion. Normal and Constraint Resources This area allows you to select the name of the nor- mal or constraint resources you wish to set. Some widgets may not have constraint resources, so the area does not appear. Resource Value This 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, the value should contain no unescaped newlines. There are a few special character sequences for this file: \n Replaces this sequence with a newline. ### Replaces this sequence with a single byte that contains this sequence interpreted as an octal number, where # is any octal digit. For example, you can store a value contain- ing a null byte by specifying \000. <new-line> Compresses this sequence to nothing. \\ Compresses this sequence to a single backslash. Command Area This area contains several buttons that perform operations related to resources. Set Save File Allows you to modify the file to which the November, 1990 5
editres(1X) editres(1X)resources are saved. Clicking this button displays a dialog box that asks you for a filename. Once you have typed the filename, press RETURN or click the Okay button. To cancel the dialog box without changing the save file, click the Cancel button. Save Appends the resource entry in The Resource Line area (described earlier) to the end of the current save file. If no save file has been set, the Set Save File dialog box is displayed to prompt you for a filename. Apply Performs an XtSetValues(3Xt) call on all widgets that match the resource line entry in The Resource Line area (described ear- lier). The value specified is applied directly to all matching widgets. This behavior is an attempt to give a dynamic feel to editres. Because this feature al- lows you to put a client application into an unknown state, a hook is provided to allow specific client applications to block XtSet- Values requests (see the next section ``Blocking editres Requests''). Unfortunately, because of 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 using Apply will be the same as what happens when you save the value and restart the applica- tion. This functionality is provided to try to give you a rough feel for what your changes will accomplish, and the results ob- tained should be considered suspect at best. Having said that, this is one of the neatest features of editres. Play with it, and see what it can do. Save and Apply Performs the Save and Apply actions previ- ously described, but you click only one but- ton. Popdown Resource Box Removes the resource box from the display. 6 November, 1990
editres(1X) editres(1X)Blocking editres requests The editres protocol is built into the Athena Widget Set and allows all applications that are linked with Xaw to communi- cate with editres. While this provides great flexibility and is a useful tool, it can quite easily be abused. To prevent abuse, any Xaw client application can specify a value for the editresBlock resource, described next, that prevents editres from divulging information about its inter- nals or disables the XtSetValues part of the protocol. editresBlock (Class EditresBlock) Specifies the type of blocking this client applica- tion wishes to impose on the editres protocol. The accepted values are: all Blocks all requests. setValues Blocks all XtSetValues requests, which are the only editres requests that actually modify the application. This value is in effect stating that the application is read-only. none Allows all editres requests. Remember that this resource value is set on the Xaw client, not on editres, and allows individual applications to prevent all or some editres requests from ever succeeding. Of course, editres is also an Xaw client application, so you can use editres to view and modify editres; XtSetValues re- quests can be blocked by setting the editresBlock resource on editres itself. Resources The editres command has five application resources. flashColor (Class flashColor) Specifies the color used to flash client application widgets. A bright color should be used, such as red or yellow, that immediately draws your attention to the area being flashed. flashTime (Class FlashTime) Specifies the amount of time between the number of flashes specified by numFlashes. numFlashes (Class NumFlashes) Specifies the number of times the widgets in the client application are flashed when the Show Active Widgets menu item is chosen. The default is 3. saveResourcesFile (Class SaveResourcesFile) November, 1990 7
editres(1X) editres(1X)Specifies the file to which the resource entry in The Resource Line area is appended when you click the Save button in the resource box. Widget hierarchy To specify resources, it is useful to know the hierarchy of the widgets that compose editres. In the notation below, indentation indicates hierarchical structure. The widget class name is given first, followed by the widget instance name. Editres editres Paned paned Box box MenuButton commands SimpleMenu menu SmeBSB sendTree SmeBSB refreshTree SmeBSB showClientWidget SmeLine line SmeBSB dumpTreeToFile SmeBSB flashActiveWidgets SmeBSB getResourceList SmeLine line SmeBSBshowAuthor SmeBSB quit MenuButton treeCommands SimpleMenu menu 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 Paned hPane Panner panner Label userMessage Grip grip Porthole porthole Tree tree Toggle <name of widget in client> . . . TransientShell resourceBox 8 November, 1990
editres(1X) editres(1X)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 Environment variables The editres command uses the following environment vari- ables: DISPLAY Specifies the default host, display number, and screen. XENVIRONMENT Specifies the name of a resource file that overrides the global resources stored in the RESOURCE_MANAGER property. LIMITATIONS This resource editor is a prototype. There are many nifty features that should be added, but editres at least shows you what a resource editor can do. NOTES Copyright 1990, Massachusetts Institute of Technology. See X(1X) for a full statement of rights and permissions. Author: Chris D. Peterson, formerly MIT X Consortium November, 1990 9
editres(1X) editres(1X)FILES /usr/lib/X11/app-defaults/Editres Required resources. SEE ALSO X(1X), xrdb(1X) Athena Widget Set - C Language Interface 10 November, 1990