The X/Motif Analyzer provides specific debugging support for X/Motif applications. There are various examiners for different X/Motif objects, such as widgets and X Window System graphics context, that might be difficult or impossible to inspect using ordinary debugger functionality. See ProDev WorkShop: Debugger User's Guide for a comprehensive discussion and tutorial regarding the X/Motif Analyzer.
To access the X/Motif Analyzer window, pull down the Views menu and select X/Motif Analyzer .
Though the X/Motif Analyzer is made up of several different examiner windows, a number of objects, such as the Admin menu, Examine menu, Help menu and several text bars, remain constant throughout window changes. The following examiners are available and discussed:
The Admin menu offers the following menu selections:
Active: Activates the current window in a set of cloned windows. In the current release, this toggle is always active.
Clone: Creates a clone of the current window. This action is not supported in the current release and the option is grayed out.
Save As Text: Launches the Save Text dialog. This dialog allows you to save your current session as text in a file you designate. This selection is not available for examiners that are graphical displays, such as the Breakpoints Examiner, the Tree Examiner, and the Pixmap Examiner.
The Examine menu offers the following options:
Selection: Selects the currently highlighted object for examination. You must first highlight the name of an object before you select this option.
Widget: Uses the current selection as input to the widget examiner, then opens that examiner (see “Widget Examiner”, for information).
Widget Tree: Switches the window view to the widget tree examiner (see “Tree Examiner”, for information).
Widget Class: Switches the window view to the widget class examiner (see “Widget Class Examiner”, for information).
Window: Switches the window view to the window examiner (see “Window Examiner”, for information).
X Event: Switches the window view to the X Event examiner (see “Event Examiner”, for information).
X Graphics Context: Switches the window view to the X graphics context examiner (see “Graphics Context Examiner”, for information).
X Pixmap: Switches the window view to the X pixmap examiner (see “Pixmap Examiner”, for information).
In addition to access through the Examine menu, each examiner can be accessed through a tab at the bottom of each view (see Figure 4-1).
When first launched, the X/Motif Analyzer has the following four tabs from left-to-right:
Breakpoints
Trace
Widget
Tree
As you select other examiners through the Examine menu, new tabs are added for the new examiners.
To delete a tab:
Select the tab you want to delete.
Right-click and select Remove Examiner from the pop-up menu.
The selected tab disappears.
Note: You can not remove the first four tabs.
The X/Motif Analyzer also brings up new examiner windows whenever they are needed. Click on the collapsed tabs to the right to display them.
Both the Widget and Name text fields have return buttons (see Figure 4-2) just to the right. Clicking these buttons causes the X/Motif Analyzer to respond exactly as if you had pressed Return on your keyboard.Only the Breakpoint Examiner and Widget Examiner have a Return button.
The Breakpoints examiner is not really an examiner, but a control area where you can set widget-level breakpoints. The breakpoints examiner is divided into three areas (see Figure 4-2):
The widget specification area that contains the same information as that in the Widget examiner. You can select a widget address, name, or class in this area, as well as move to the widgets parents or children, or select a widget in the application. In cases where the breakpoint type does not apply to widgets (for example, input-handler breakpoints), this area is blank.
The parameter specification area, the contents of which vary according to the type of breakpoint you are setting. For example, for callback breakpoints, this area contains the callback name and client data; for event-handler breakpoints, it contains the event type and the client data, and so on.
The breakpoint area, which contains the breakpoint name, a search field, and the Add, Modify, Delete, and Step To buttons. Because the Search text field and the four buttons appearing in the Breakpoints area function the same way no matter which Breakpoint Type is selected, descriptions for these items are included here, and are not described in each of the remaining subsections. These are:
Search text field: Allows you to perform a text search through your breakpoints.
Add button: Allows you to add a new breakpoint.
Modify button: Allows you to change the selected breakpoint's settings.
Delete button: Deletes the selected breakpoint.
Step To button: Allows you to step to the next condition. Step To creates a temporary breakpoint, resumes the process, and waits until the process stops. This temporary breakpoint acts exactly like an ordinary breakpoint, save that the Step To button automatically resumes the process and puts up a busy cursor until the condition becomes true.
The control area has eight different breakpoint types that it can examine. These types are set through the Breakpoint Type options. The following Breakpoint Type options are available:
Callback: Widget callback installed by XtAddCallback. Parameters include callback name and client_data XtPointer value. See “Callback Breakpoints Examiner”, for more information.
Event-Handler: Widget event handler installed by XtAddEventHandler. Parameters include X event type and client_data XtPointer value. See “Event-Handler Breakpoints Examiner”, for more information.
Resource-Change: Resource change caused by XtSetValues or XtVaSetValues. Parameters include resource name and resource value, both strings. See “Resource-Change Breakpoints Examiner”, for more information.
Timeout-Procedure: Timeout callback installed by XtAppAddTimeOut. Parameters include client_data XtPointer value. See “Timeout-Procedure Breakpoints Examiner”, for more information.
Input-Handler: Input callback installed by XtAppAddInput. Parameters include client_data XtPointer value. See “Input-Handler Breakpoints Examiner”, for more information.
State-Change: Various widget state changes (for example, managed or realized). Parameters include widget state. See “State-Change Breakpoints Examiner”, for more information.
X-Event: X event received by target application. Parameters include X event type. See “X-Event Breakpoints Examiner”, for more information.
X-Request: X request received by target application. Parameters include X request type. See “X-Request Breakpoints Examiner”, for more information.
When the Callback option of the Breakpoint Type option button in the Breakpoints Examiner is selected, the Callback Breakpoints Examiner is displayed.
The Callback Breakpoints examiner contains the following items:
Widget text field: Allows you to choose a widget to examine by entering the widget address.
Name text field: Allows you to choose a widget to examine by entering the widget name.
Class text field: Allows you to choose a widget to examine by entering the widget's class. Leave the field blank or enter Any to select all widgets.
Parent text field: Allows you to move to the parent of the currently selected widget.
Previous button: Moves you to the previously selected widget.
Children button: Shows you the widget's children (it is grayed out if the selected widget cannot have children).
Select button: Allows you to select the widget in the target process.
Breakpoint Type option button: Allows you to select the type of breakpoint you wish to set. In this section, Callback is selected.
Clear button: Clears all the current breakpoint selections and text fields.
Callback Name text field: Allows you to set the Name of the callback for the breakpoint.
Client_Data text field: Allows you to pass and get back pointer values for Client_Data.
When the Event-Handler option of the Breakpoint Type option button in the Breakpoint Examiner is selected, then Event-Handler examiner appears.
The Event-Handler Breakpoints examiner contains the following items:
Widget text field: Allows you to choose a widget to examine by entering the widget address.
Name text field: Allows you to choose a widget to examine by entering the widget name.
Class text field: Allows you to choose a widget to examine by entering the widget's class. Leave the field blank or enter Any to select all widgets.
Parent text field: Allows you to move the parent of the currently selected widget.
Previous button; Moves you to the previously selected widget.
Children button: Shows you the widget's children (it is grayed out if the selected widget cannot have children).
Select button: Allows you to select the widget in the target process.
Breakpoint Type option button: Allows you to select the type of breakpoint you wish to set. In this section, Event-Handler is selected.
Clear button: Clears all the current breakpoint selections and text fields.
Event Type option button: Allows you to set the event type for a given breakpoint.
Client_Data text field: Allows you to pass and get back pointer values for the Client_Data.
When the Resource-Change option of the Breakpoint Type option button in the Breakpoint Examiner is selected, the examiner appears.
The Resource-Change Breakpoints examiner contains the following items:
Widget text field: Allows you to choose a widget to examine by entering the widget address.
Name text field: Allows you to choose a widget to examine by entering the widget name.
Class text field: Allows you to choose a widget to examine by entering the widget's class. Leave the field blank or enter Any to select all widgets.
Parent text field: Allows you to move the parent of the currently selected widget.
Previous button: Moves you to the previously selected widget.
Children button: Shows you the widget's children (it is grayed out if the selected widget cannot have children).
Select button: Allows you to select the widget in the target process.
Breakpoint Type option button: Allows you to select the type of breakpoint you wish to set. In this section, Resource-Change is selected.
Clear button: Clears all the current breakpoint selections and text fields.
Resource Name text field: Allows you to set the resource name for the breakpoint.
Resource Value text field: Allows you to set the resource value for the breakpoint.
When the Timeout Procedure option of the Breakpoint Type option button in the Breakpoint Examiner is selected, the examiner appears as shown in Figure 4-3.
The Timeout-Procedure Breakpoints examiner contains the following items:
Breakpoint Type option button: Allows you to select the type of breakpoint you wish to set. In this section, Timeout-Procedure is selected.
Clear button: Clears all the current breakpoint selections and text fields.
Client_Data text field: Allows you to pass in and get back pointer values for the Client_Data.
When the Input-Handler option of the Breakpoint Type option button in the Breakpoint Examiner is selected, the examiner appears.
The Input-Handler Breakpoints examiner contains the following items:
Breakpoint Type option button: Allows you to select the type of breakpoint you wish to set. In this section, Input-Handler is selected.
Clear button: Clears all the current breakpoint selections and text fields.
Client_Data text field: Allows you to pass in and get back pointer values for the Client_Data.
When the State-Change option of the Breakpoint Type option button in the Breakpoint Examiner is selected, the examiner appears.
The State-Change Breakpoints examiner contains the following items:
Widget text field: Allows you to choose a widget to examine by entering the widget address.
Name text field: Allows you to choose a widget to examine by entering the widget name.
Class text field: Allows you to choose a widget to examine by entering the widget's class. Leave the field blank or enter Any to select all widgets.
Parent button: Allows you to move the parent of the currently selected widget.
Previous button: Moves you to the previously selected widget.
Children button: Shows you the widget's children (it is grayed out if the selected widget cannot have children).
Select button: Allows you to select the widget in the target process.
Breakpoint Type option button: Allows you to select the type of breakpoint you wish to set. In this section, State-Change is selected.
Clear button: Clears all the current breakpoint selections and text fields.
State Type option button: Allows you to set the state change type for a given breakpoint.
When you select the X-Event option of the Breakpoint Type option button in the Breakpoint Examiner, the examiner appears as shown in Figure 4-4.
The X-Event Breakpoints examiner contains the following items:
Breakpoint Type button: Allows you to select the type of breakpoint you wish to set. In this section, X-Event is selected.
Clear button: Clears all the current breakpoint selections and text fields.
Event Type button: Allows you to set the event type for a given breakpoint.
Window ID text field: Allows you to set the Window ID value for the breakpoint.
When the X-Request option of the Breakpoint Type option button in the Breakpoint Examiner is selected, the examiner appears.
The X-Request Breakpoints examiner contains the following items:
Breakpoint Type option button: Allows you to select the type of breakpoint you wish to set. In this section, X-Request is selected.
Clear button: Clears all the current breakpoint selections and text fields.
Request Type button: Launches the Request Type Selection dialog (see Figure 4-5). This dialog allows you to select the type of X-Request used for your breakpoint. The information displayed is in outline form; selecting a given item selects all its subitems. For example, if you select Window-Category, CreateWindow, ChangeWindowAttributes, GetWindowAttributes, and so on are also selected.
The Trace examiner (see Figure 4-6) is a control area where you can trace the execution of your application and collect the following date:
X Server Events
X Server Requests
Widget Event Dispatch Information
Widget Resource Changes (through XtSetValues)
Widget State Changes (create, destroy, manage, realize, and unmanage)
Xt Callbacks (widget, event handler, work proc, timeout, input, and signal)
The Trace examiner contains the following items:
Collect Trace toggle: Allows you to turn the tracing on and off.
File text field: Allows you to select the file name for the trace. If no file is selected, a default filename for the trace is chosen.
Search text field: Allows you to perform an incremental, textural search for the trace list.
Filter button: Launches a dialog that allows you to select the trace entry types you want displayed in the list.
Clear File button: Erases the trace file. Any subsequent trace information goes to the beginning of the file.
The Widget examiner displays the internal Xt widget structure, as well as the Xt inheritance implementation using nested C constructs.
The Widget examiner contains the following items:
Widget text field; Allows you to choose a widget to examine by entering the widget address.
Name text field: Allows you to choose a widget to examine by entering the widget name.
Parent button: Allows you to move the parent of the currently selected widget.
Previous button: Moves you to the previously selected widget.
Children button: Shows you the widget's children. (It is grayed out if the selected widget does not have children.)
Select button: Allows you to select the widget in the target process.
The Tree examiner (see Figure 4-7) displays the widget hierarchy.
You can double-click a node to view that widget in the Widget examiner.
If the Tree examiner is currently selected, it does not automatically fetch the current widget tree each time the process stops. To force retrieval of the widget tree, select another examiner and then go back to the Tree examiner. Or, click on the Tree tab.
The graphical buttons across the bottom of the Tree Examiner window from left-to-right have the following functions.
Zoom percentage indicator: Click on this indicator to bring up a submenu from which you can select a different percentage.
Zoom Out button: Decreases the zoom percentage.
Zoom In button: Increases the zoom percentage.
Overview button: Shows the entire tree structure in another window along with an indication of which portion of the tree is currently being displayed in the full-sized Tree Examiner window.
Multiple Arcs button: This button shows/hides multiple connections between nodes on the graph. For example, if main calls foo several times, you see a line (arc) for all calls made.
Realign button: This button resets the graph back to its original configuration (before you began working with it). Also, hidden nodes reappear.
Rotate button: Change the format of the window from up-down to left-right, or vice-versa.
Search button: Search for text in the tree using a Widget Hierarchy Search Text window.
Widget View Type Option button: Click on this indicator to change the kind of information being displayed in the nodes of the tree. This brings up a submenu which allows you to choose Name, Class, ID (widget address) or Window (indicate <gadget> or address).
The Callback examiner automatically appears when the process is stopped somewhere in a callback. It first displays the callstack frame. Then it displays information about the widget in the callback. Finally, it displays the proper callback structure contained in the call_data argument to the callback procedure, based on the widget type and the callback name.
The Window examiner displays window attributes for an X window and the parent and children window IDs. These attributes are returned by XGetWindowAttributes, with decoding of the visual structure, enums, and masks.
The Window examiner contains the Window text field that displays the address of the window that is being examined. You may change to a different window by entering a new address and pressing Enter.
The Event examiner displays the event structure for an XEvent pointer. The proper XEvent union member is used, and enums and masks are decoded.
The Event examiner contains the X Event text field, which displays the address of the X event that is being examined. You may change to a different X event by entering a new address and pressing Enter.
The Graphics Context examiner displays the X graphics context attributes that are cached by Xlib in the form of an XGCValues structure. Enums and masks are decoded.
The Graphics Context examiner contains the GC text field that displays the address of the graphics context that is being examined. You may change to a different context by entering a new address and pressing Enter.
The Pixmap examiner displays basic attributes of an X pixmap, like size and depth. It also attempts to provide an ASCII display of small pixmaps, using the units digit of the pixel values.
The Pixmap examiner displays the contents of an X pixmap. To specify an X pixmap identifier, enter a numeric expression in the top text field of the window. Then, use default as the colormap identifier to specify the default X colormap for your screen. In the pixmap display, left-click on a pixel to see the pixel value, position, and red-green-blue intensities.
The Widget Class examiner displays the Xt widget class structure, as well as the Xt inheritance implementation using nested C constructs.
The Widget Class examiner contains the W Class text field, which displays the address of the widget class that is being examined. You may change to a different widget class by entering a new address and pressing Enter.