editres(X1)

Synopsis

Description

Options

Using editres

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 application'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 application'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 application 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 application. 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

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 application.

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 \000.

\<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 applications 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

editresBlock (Class: EditresBlock)

Specifies which type of blocking this application 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 application, not editres. They allow individual applications to keep all or some of the requests editres makes from succeeding. Because editres is also an Xaw application, 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.

Files

Resources

numFlashes (Class: NumFlashes)

Specifies the number of times the widgets in the 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 application 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

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.

References