editres(XC)

editres -- dynamic resource editor for X toolkit applications

Syntax

editres [-toolkitoption...]

Description

Use editres to view the full widget hierarchy of any X toolkit client that uses the editor's protocol. All clients built with Motif on SCO Open Desktop 3.0 will be able to communicate with the editres protocol. You can also use editres to construct resource specifications, apply the resource to the application, and view the results dynamically. After you are satisfied with a resource specification, editres will append the resource string to your X resources file.

Options

editres accepts all of the standard X Toolkit command line options (see X(X)). The order of the command line options is not important.

Using editres

editres provides a window consisting of the following three areas:

Menu Bar: A set of popup menus that gives access to all editres features.
Message Area: Displays information about the action expected from the user.
Application Widget Tree: Area used to display the selected client's widget tree.

To begin an editres session, select the Get Widget Tree menu item from the command menu. This changes the pointer cursor to crosshair. Next, select the application you want to look at by clicking on any of its windows. If this application understands the editres protocol, then editres will display the client's widget tree in its tree window. If the application does not understand the protocol, that fact appears in the message area after a few seconds.

Once you have a widget tree, you can select any of the other menu options, as described in the next section.

Commands

Get Widget Tree: Allows the user to click on any client that uses the editres protocol and receive its widget tree.
Refresh Current Widget Tree: editres only knows about the widgets that currently exist. Many applications create and destroy widgets "on-the-fly," that is, within a single session. Selecting this menu item will cause editres to ask the application to resend its widget tree, thus updating its information to the new state of the application. For example, xman only creates the widgets for its topbox when it starts up. None of the widgets for the manual page window are created until the user actually clicks on the Manual Page button. If you retrieved the xman widget tree before the manual page is active, you may want to refresh the widget tree after the manual page has been displayed. This will also let you edit the manual page's resources.
Dump Widget Tree to a File: When documenting applications it is often useful to be able to dump the entire application widget tree to an ascii file. This file can then be included in the manual page. When this menu item is selected, a popup dialog is activated. Type the name of the file in this dialog, and either select Okay, or press <Enter>. editres will now dump the widget tree to this file. To cancel the file dialog, select the Cancel button.
Show Resource Box: This command pops up a resource box for the current client. This resource box (described in detail below) will allow the user to see exactly which resources can be set for the widget currently selected in the widget tree display. Only one widget at a time may be selected; otherwise, the resource box will not pop up, and an error message will appear in the Message Area.
Set Resource: This command will pop up a simple dialog box for setting an arbitrary resource on all selected widgets. You must type in the resource name, as well as the value. You can use the <Tab> key to switch between the resource name field and resource value field.
Quit: Exits editres.

Tree commands

The Tree menu contains several commands that allow operations to be performed on the widget tree:

Select Widget in Client

This menu item allows you to select any widget in the application. editres will then highlight the corresponding element on the widget tree display. After you select this item, the pointer cursor again turns to a crosshair. Click any pointer button on the widget you wish to have displayed. Since some widgets are fully obscured by their children, it is not possible to get to every widget this way. However, this mechanism does give very useful feedback between the elements in the widget tree and those in the actual client.

Select All; Unselect All; Invert All

These functions allow the user to select, unselect, or invert all widgets in the widget tree.

Select Children; Select Parents

These functions select the immediate parent or children of each of the currently selected widgets.

Select Descendants; Select Ancestors

These functions select all parents or children of each of the currently selected widgets. This is a recursive search.

Show Widget Names; Show Class Names;

Show Widget IDs; Show Widget Windows

When the tree widget is initially displayed, the labels of each widget in the tree correspond to the widget names. These functions will cause the label of all widgets in the tree to be changed to show the class name, IDs, or window associated with each widget in the application. The widget IDs, and windows are shown as hex numbers. In addition, there are keyboard accelerators for each of the Tree operations. If the input focus is over an individual widget in the tree, then that operation will only affect that widget. If the input focus is in the Tree background, it will have exactly the same effect as the corresponding menu item. The translation entries shown may be applied to any widget in the application. If that widget is a child of the Tree widget, then it will only affect that widget, otherwise it will have the same effect as the commands in the tree menu.

Flash Active Widgets

This command is the inverse of the Select Widget in Client command. It will show the user each widget that is currently selected in the widget tree by flashing the corresponding widget in the application numFlashes (three by default) times in the flashColor.

Clicking button 1 on a widget acts as a toggle; for example, depending on the current state (selected or unselected), clicking button 1 on a widget could add that widget to a set of selected widgets.

Using the resource box

The resource box contains five different areas, discussed here in the order in which they appear onscreen:

The resource line

This area at the top of the resource box shows the current resource name exactly as it would appear if you were to save it to a file or apply it.

The widget names and classes

This area allows you to select exactly which widgets this resource will apply to. The area contains four lines, the first contains the name of the selected widget and all its ancestors, and the more restrictive dot (.) separator. The second line contains the Class names of each widget, and the less restrictive asterisk (*) separator. The third line contains a set of special buttons called Any Widget which will generalize this level to match any widget. The last line contains a set of special buttons called Any Widget Chain which will turn the single level into something that matches zero or more levels. The initial state of this area is the most restrictive, using the resource names and the dot separator. By selecting the other buttons in this area, you can ease the restrictions to allow more and more widgets to match the specification. The extreme case is to select all the Any Widget Chain buttons, which will match every widget in the application. As you select different buttons, the tree display will update to show you exactly which widgets will be affected by the current resource specification.

Normal and constraint resources

The next area allows you to select the name of the normal or constraint resources you wish to set. Some widgets may not have constraint resources, so that area will not appear.

Resource value

This next 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 it should contain no unescaped new-lines.

There are a few special character sequences for this file:

\n: This will be replaced with a newline.
\###: Where # is any octal digit. This will be replaced with a single byte that contains this sequence interpreted as an octal number. For example, a value containing a NULL byte can be stored by specifying nbsp;00.
\<new-line>: This will compress to nothing.
\\: This will compress to a single backslash.

Command Area

This area contains the following command buttons:

Set Save File: This button allows the user to modify the file to which the resources will be saved. This button will bring up a dialog box that will ask you for a filename. After the filename has been entered, either press <Enter> or click on the OK button. If you do not want to change this file, click on the Cancel button.
Save: This button will append the Resource line described above to the end of the current save file. If no save file has been set, the Set Save File dialog box will appear to prompt the user for a filename.
Apply: This button attempts to perform an XtSetValues call on all widgets that match the Resource line described above. The value specified is applied directly to all matching widgets. Because this feature allows users to put an application in states it may not be willing to handle, a hook has been provided to allow specific clients to block these SetValues requests (see the following section on blocking editres requests). Due to 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. The results of an apply may not be the same as the results from saving the value and restarting the application. This functionality is provided to give you an approximate idea of what your changes may accomplish, and the results obtained should be consequently considered approximations.
Save and Apply: This button combines the Save and Apply actions described above into one button.
Popdown Resource Box: This button will remove the resource box from the display.

Blocking editres requests

The editres protocol has been built into the Motif Widget set. This gives all applications that are linked against Motif the ability to speak to the resource editor. While this provides great flexibility and is a useful tool, it can be abused. It is therefore possible for any Motif client to specify a value for the editresBlock resource described below, to keep editres from divulging information about its internals, or to disable the SetValues part of the protocol.

editresBlock (Class: EditresBlock)

Specifies which type of blocking this client wishes to impose on the editres protocol. The accepted values are:

all: Block all requests.
setValues: Block all setValues requests. This is the only editres request that actually modifies the application. This is, in effect, stating that the application is read-only.
none: Allow all editres requests.

Remember that these resources are set on any Xaw client, not editres. They allow individual clients to keep all or some of the requests editres makes from succeeding. Because editres is also an Xaw client, it may also be viewed and modified by editres (in a recursive manner). These commands can be blocked by setting the editresBlock resource on editres itself.

Resources

For editres, the available application resources are:

numFlashes (Class: NumFlashes): Specifies the number of times the widgets in the client application will be flashed when the Show Active Widgets command is invoked.
flashTime (Class: FlashTime): Amount of time between the flashes described above.
flashColor (Class: flashColor): Specifies the color used to flash client widgets. A bright color should be used that will immediately draw your attention to the area being flashed, such as red or yellow.
saveResourcesFile (Class: SaveResourcesFile): This is the file the resource line will be appended to when the Save button is activated in the resource box.

Widget hierarchy

In order to specify resources, it is useful to know the hierarchy of the widgets which 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
     XmMainWindow  main
          XmSeparatorGadget  Separator1
          XmSeparatorGadget  Separator2
          XmSeparatorGadget  Separator3
          XmRowColumn  menuBar
               XmCascadeButton  cmds
               XmCascadeButton  tree
               XmMenuShell  popup_cmdsMenu
                    XmRowColumn  cmdsMenu
                         XmPushButton  sendTree
                         XmPushButton  refreshTree
                         XmPushButton  dumpTreeToFile
                         XmSeparator  sep1
                         XmPushButton  getResourceList
                         XmPushButton  setValues
                         XmSeparator  sep2
                         XmPushButton  quit
                         XmDialogShell  dialog_popup
                              XmFileSelectionBox  dialog
                                       XmLabelGadget  Items
                                       XmScrolledWindow  ItemsListSW
                                              XmScrollBar  VertScrollBar
                                              XmScrollBar  HorScrollBar
                                              XmList  ItemsList
                                       XmLabelGadget  Selection
                                       XmTextField  Text
                                       XmSeparatorGadget  Separator
                                       XmPushButtonGadget  OK
                                       XmPushButtonGadget  Apply
                                       XmPushButtonGadget  Cancel
                                       XmPushButtonGadget  Help
                                       XmLabelGadget  FilterLabel
                                       XmLabelGadget  Dir
                                       XmTextField  FilterText
                                       XmScrolledWindow  DirListSW
                                              XmScrollBar  VertScrollBar
                                              XmScrollBar  HorScrollBar
                                              XmList  DirList
                    XmRowColumn  treeMenu
                         XmPushButton  showClientWidget
                         XmPushButton  selectAll
                         XmPushButton  unselectAll
                         XmPushButton  invertAll
                         XmSeparator  sep1
                         XmPushButton  selectChildren
                         XmPushButton  selectParent
                         XmPushButton  selectDescendants
                         XmPushButton  selectAncestors
                         XmSeparator  sep2
                         XmPushButton  showWidgetNames
                         XmPushButton  showClassNames
                         XmPushButton  showWidgetIDs
                         XmPushButton  showWidgetWindows
                         XmSeparator  sep3
                         XmPushButton  flashActiveWidgets
          XmPanedWindow  paned
               XmLabel  userMessage
               XmScrolledWindow  workWin
                    XmDrawingArea  ScrolledWindowClipWindow
                         Tree  tree
                    XmScrollBar  VertScrollBar
                    XmScrollBar  HorScrollBar
               XmSash  sash
               XmSeparatorGadget  separator
               XmSash  sash
               XmSeparatorGadget  separator

Environment variables

DISPLAY: to get the default host and display number.
XENVIRONMENT: to get the name of a resource file that overrides the global resources stored in the RESOURCE_MANAGER property.

Files

/usr/lib/X11/app-defaults/Editres specifies required resources