wbr.gml

来自「开放源码的编译器open watcom 1.6.0版的源代码」· GML 代码 · 共 1,349 行 · 第 1/4 页

tree format option (see section(Options)).(FIXME- currently no such menu
item)
.*
.np
In either the text format or the graphical format, a left to right
connection between nodes indicates a direct inheritance relationhip.
.*
.np
See section(Graph Displays) for a detailed description of the inheritance
tree display and its interaction mechanism.
.*
.section Decomposition
.*
.np
The Decomposition checkbox controls the display of a pushpin window for selective
viewing of the composition of the data fields of a structure.
.*
.np
When it first appears, the decomposition window shows the name of the structure,
followed by an indented list of all of its data members (see
:figref refid=decomp.).
.*
:fig id='decomp' frame=box place=inline.
:graphic depth='2.0i'
    file='decomp.eps'
:figcap.Structure Decomposition
:efig.
.*
.np
If a displayed item has a '+' symbol in the extreme left column,
this indicates that the item is itself a structure type. Double clicking on
the item will cause an indented expansion of the structure in place.
.*
.np
If a displayed item has a '*' symbol in the extreme left column,
this indicates that the item is a pointer to some type.
Double clicking on the entries will 'follow the pointer'; the entry will
be replaced by the type that was pointed to, with its name preceded by a '*'
to indicate that it has been dereferenced.  The extreme left  column of the
starting item will now contain either a '-' to indicate that the item cannot be
expanded further, or a '*' to indicate that the dereferenced type is also a
pointer, which may be followed further.
.*
.np
If a displayed item has a '-' symbol in the extreme left column,
this indicates that the item has been expanded (this symbol does not appear
for pointer types until the end of chain of pointers has been reached.).
Clicking on the item will cause the expansion to collapse.  For example,
clicking on the top row (the root type of this decomposition) while collapse
the view to a single line holding the name of the root structure, preceded by
a '+'.
.*
.np
Double clicking on an item will create a Detail View of the item.
.*
.endlevel
.*
.section Macro Detail Views
.*
.np
Macro Detail Views simply add a Definition checkbox to the basic Symbol Detail
View.  This controls the display of a text box holding the definition of the
macro.
.*
.np
Note that the definition is simply the first encountered definition for that
macro;  if the macro is defined more than once, the contents of the
definition text box will not be correct for some scopes.
.*
.endlevel
.*
.section Graph Displays
.*
.np
&brname provides information on three types of graphs:
.begbull
.bull
Function Call Graphs
.bull
Class Inheritance Tree
.bull
Structure Decomposition
.endbull
.*
.np
Structure Decomposition is described in the section(Class Detail
Views/Decomposition). Call graphs and inheritance trees are handled
identically , so they will both be described here.
.*
.np
Either of these graphs can be displayed in a text or graphical format; while
the graphical format is be easier to use and interpret, it takes longer to
display and update than the text format.
.*
.np
The form that newly created graph windows will take depends up the current
setting of the appropriate item under the main Options menu (existing graph
windows are not affected by setting changes).
.*
.np
The following description uses the function call graph for illustration.
However, if the concepts 'function call', 'calling function', and 'called
function' are replaced with 'derivation', 'base class', and 'derived class',
this same description may be applied to a class inheritance tree.
.*
.beglevel
.section Text Format Graph Display
.*
.np
In text form, the call graph is represented as three columns (see
:figref refid=funtxttr.) .
.*
:fig id='funtxttr' frame=box place=inline.
:graphic depth='1.5i'
    file='funtxttr.eps'
:figcap.Text Format Function Call Graph
:efig.
.*
.np
The center column lists a number of functions, starting with the detail view's
function, in an indented format.  Read from top to bottom, this list indicates
path that has been followed in browsing up and down the call graph.  If an item
is indented further than an adjacent item, it is called by that item (and
vice versa).
.*
.np
One of the items in the center column will always be highlighted, indicating
the current position in the call graph. The left column lists direct callers
of the highlighted function in the center column, and the right column lists
functions that are directly called by it.
.*
.np
Movement to a new point in the call graph can be done by selecting an item
from any of the three columns to be the new focal point.  This selection may
be done with a mouse click in any column.  In the center column, up
and down cursor movement will dynamically change the focal point. (FIXME -
need to test performance of this; may need to use enter key to force refresh)
In either side column, a press of the enter key is needed to indicate a new
selection.
.*
.np
Selection of a new focal point will cause a refresh of the two outer columns
to indicate the direct calls to and from the new focal point.  The new focal
point will be highlighted in the center column.


If the new focal point was already on the existing browse path, that item on
the center column's path will just be highlighted. If the new focal point
represents an extension to the previous browse path, the new function will be
added to the end of the path in the center column. Otherwise, the new focal
point represents a fork off of an item in the existing browse path;  the path
below that item will be cleared, and the new focal point will be added to the
bottom of the path.
.*
.np
If a node is double clicked, a Detail View for the node will appear.
.*
.section Graphical Format Graph Display
.*
.np
In graphical form, the call graph is represented as two trees, fanning out
to the left and the right of the detail view's function (see
:figref refid=fungrptr.) .
Connections between nodes indicate direct function calls, calling from left
to right.  Dotted connection lines indicate functions that directly connect to
this function which are not shown.
.*
:fig id='fungrptr' frame=box place=inline.
:graphic depth='2.5i'
    file='fungrptr.eps'
:figcap.Graphical Format Function Call Graph
:efig.
.*
.np
The trees may be expanded outwards from the focal point, and selectively
collapsed back inwards, using mouse clicks on the connection lines, or using
pop-up menus on the tree nodes.
.*
.np
If the mouse is clicked on a solid connection, the nodes that that tree
branch connect to will be hidden, and the connection will change from a
solid line to a dotted line.  If the mouse is clicked on a dotted connection,
the next level of functions will be displayed.
.*
.np
The same operations may be performed with the pop-up menu on a given node,
activated with a right mouse click (FIXME - need hot key for keyboard)
(see
:figref refid=treemenu.) .
.*
:fig id='treemenu' frame=box place=inline.
:graphic depth='2.5i'
    file='treemenu.eps'
:figcap.Graph Node Popup Menu
:efig.
.np
The menu items work as follows:
.*
.begnote
.note Hide
hides this node, and any branches originating from it
.note Hide Children
hides any branches originating from the node
.note Show Children
shows any hidden branches originating from the node
.note Show Details
creates a Detail View of the node
.endnote
.*
.np
If a node is doubleClicked, a Detail View for the node will appear.
.*
.endlevel
.section Menu Versus Editor Interaction
.*
.np
The &brname presents a two major entry points for navigating an
application.
.*
.np
The menu bar in the main &brname window represents one of two methods for
navigating an application; this is the preferred way to get an overview of
a development project.
.*
.np
The other method for browsing an application begins with an &edname session
running as a slave to &vmakenm.  In this mode, a particular word in the file can
be selected, and the editor can direct a query on that word to the &brname.
.*
.np
The information presented is identical in both cases, with the difference
that editor queries must originate with a piece of text in a file and may
only follow the symbol relationship paths from that point, while the main
&brname menu bar allows arbitrary queries of all the symbols in the
application.  In addition, the &brname menus provide some overviews and
reports not available through the editor interface.
.*
.np
In either mode, the &edname is used as the means of displaying and changing
symbol definitions, and any editor session opened to display a symbol
definition may be used as the source of further queries.
.*
.np
The next two major sections cover menu bar and editor interaction, respectively.
.*
.endlevel
.*
.section The Menu Bar
.*
.np
The menu bar appears on the main &brname window. This window is initially in
the upper left of the screen, or it may be minimized if the &brname has been
started as a slave to &vmakenm.
.*
.np
The contents of the menu bar are described in the following
sections.
.*
.beglevel
.section File
.*
.np
File groups together those actions that load, save, and change '.wbr' project
files, as well as providing for exit from the application.
.*
:fig id='filemenu' frame=box place=inline.
:graphic depth='1.3i'
    file='filemenu.eps'
:figcap.File Menu Items
:efig.
.*
.beglevel
.section Open
.*
.np
Open allows the selection of a &wbrfile for loading into the browser.  This
is done through a standard Windows file selection dialog, as in
:figref refid=opendlg. .
.*
:fig id='opendlg' frame=box place=inline.
:graphic depth='2.2i'
    file='opendlg.eps'
:figcap.Open File Dialog
:efig.
.*
.np
Selection of 'Cancel' will leave the current browse project (if any)
unchanged.
.*
.np
If a valid .wbr is selected and 'Ok' pressed, the current project (if any)
will be unloaded.  If the current project has been changed since loading, a
'Save? YES/NO' dialog will appear.  Finally the new .wbr will be loaded.
While it is loading, all browsing operations are disabled, and a loading
progress indicator is displayed.
.*
.np
A sample &wbrfile is available in the (SAMPLES?) directory, called
'test.wbr'.  This is the project that was used for generating the screens
that are seen throughout this text.
.*
.section New
.*
.np
New creates a new browse project with no name, though it can be saved under
any name, using Save or SaveAs.  If a project is currently loaded and it has
unsaved changes, a 'Save? YES/NO' dialog will allow it to be saved before the
project is replaced with the new one.
.*
.np
The new, empty project must be populated with at least one &mbrfile (see
section(File/Modules) below) before anything useful can be done.
.*
.section Save
.*
.np
Save will write the current project configuration to the current &wbrfile..
If the project has no name yet, selection of this item will result in the
same file selection dialog box used by SaveAs, described in the next
section.
.*
.np
The Save menu item will be enabled only if the current project has unsaved
changes; otherwise it will appear shaded.
.*
.section SaveAs
.*
.np
SaveAs allows the selection of any valid file destination for saving the
project.  This effectively saves a copy of the current state of the project.
It does not rename the current project, unless the project is unnamed.
.*
.np
SaveAs might be used to create a few &wbrfile.s for a given project, each
support browsing of a different part or view of the project.  This has two
benefits: query processing will be faster due to fewer symbols, and the results
of queries will be more focussed
.*