This is Info file ../info/oo-browser.info, produced by Makeinfo-1.63
from the input file oo-browser.texi.


File: oo-browser.info,  Node: Top,  Next: Introduction,  Prev: (dir),  Up: (dir)

Preface
*******

Copyright (C) 1989-1996  Free Software Foundation, Inc.

   All trademarks referenced herein are trademarks of their respective
holders.

   This edition of the OO-Browser User Manual is for use with any
version 2.9.12 or greater of the OO-Browser.  The OO-Browser is
available for free use, distribution, and modification under the terms
of version 2 or later of the GNU Public License (GPL).  No
representations are made about the suitability of this software for any
purpose.  It is provided "as is" without express or implied warranty.

   The OO-Browser was designed and written by Bob Weiner.  Motorola,
Inc. funded and donated this work for free redistribution as part of the
InfoDock integrated productivity toolset.  Torgeir Veimo and Mark Stern
helped write the X OO-Browser core.  Don Yacktman helped write the
NEXTSTEP OO-Browser core.  Jeff Sparkes helped with the Java language
support.  Harri Pasanen implemented the Python language support, and
updated the documentation to reflect that addition.

   The OO-Browser and InfoDock can be obtained via anonymous ftp on the
Internet from: `/anonymous@ftp.xemacs.org:/pub/infodock'.  Installation
instructions for the OO-Browser can be found in the `BR-README' file in
the OO-Browser distribution.

   This manual documents the user interface and operation of the
OO-Browser multi-language browser.  It assumes a very basic familiarity
in the use of the GNU Emacs editor as documented in `[Stallman 87]'.
It also assumes familiarity with object-oriented software concepts.
However, many technical terms used in this manual are given precise
meaning in the glossary.  *Note Glossary::.  The OO-Browser is meant to
be easy to use, so you can point and click to use it, rather than
learning all of the key stroke commands.

   Chapter 1 of the manual focuses on OO-Browser Environments to provide
the reader with a picture of how to organize work for use with the
OO-Browser (*note Working with Environments: Environments.).  *Note
Using the OO-Browser: Usage, if you would rather start with the
interactive features of the browser.  *Note OO-Browser Features:
Features, for a quick overview of the browser's features.

   Throughout this manual, sequences of key strokes are delimited by
braces, {}, command names are delimited by parentheses, (), and
variable names are emphasized.

   We hope that you enjoy using the OO-Browser and that it improves your
productivity.

* Menu:

* Introduction::                Introduction
* Environments::                Working with Environments
* Usage::                       Using the OO-Browser
* Options::                     OO-Browser Options
* Customization::               Personal Customization
* Standalone::                  Using Standalone OO-Browser Features
* Languages::                   Language-Specific Notes
* Features::                    OO-Browser Features
* Commands::                    OO-Browser Command Descriptions
* Glossary::                    Glossary
* References::                  References
* Keys::                        Key Binding Index
* Command Index::               Command and Variable Index
* Concepts::                    Concept Index

 -- The Detailed Node Listing --

Working with Environments

* Creating Environments::
* Building Environments::
* Loading Environments::
* Saving Environments::

Using the OO-Browser

* Invoking::                    Invoking the OO-Browser
* Top-Level Classes::           Displaying Top-Level Classes
* Moving to Entries::
* Saving Listings::             Writing a Listing to a File
* Children and Parents::        Browsing Children and Parents
* Descendants and Ancestors::   Browsing Descendants and Ancestors
* Viewing and Editing::         Viewing and Editing Classes
* Browsing Elements::
* Browsing Categories::
* Browsing Protocols::
* Browsing Implementors::
* Exiting a Listing::
* Quitting and Refreshing::     Quitting and Refreshing the OO-Browser
* Using the Mouse::
* Getting Help::
* Locating Entries::
* Filtering Entries::
* Ordering Entries::
* Statistics::                  Environment and Class Summaries
* Class Info::                  Language-Specific Class Information
* Adding and Deleting Classes::
* Completing Names::
* Graphical Browsing::          Graphical OO-Browser Interfaces

OO-Browser Options

* External Viewing::            Using An External Viewer or Editor
* Keep Viewed Classes::
* Inhibit Version::             Inhibit Version Screen
* Invert Ancestors::            Invert Ancestor Trees
* Save All::                    Save All Lookup Tables
* Use Children::                Build Children Lookup Table
* Sort Options::                Controlling Class Listing Order

Language-Specific Notes

* C Specifics::
* C++ Specifics::
* CLOS Specifics::
* Eiffel Specifics::
* Java Specifics::
* Objective-C Specifics::
* Python Specifics::

C++ Specifics

* C++ Element Selection::       Source Code Element Selection
* C++ Settings::

CLOS Specifics

* CLOS Method Handling::        Method Handling
* CLOS Settings::

Eiffel Specifics

* Eiffel Listings::
* Eiffel Element Selection::    Source Code Element Selection
* Eiffel Settings::

Objective-C Specifics

* Objective-C Categories::
* Objective-C Protocols::
* Objective-C Element Selection::  Source Code Element Selection
* Objective-C Settings::

Python Specifics

* Python Module Lookup::       Source Code Element Selection
* Python Settings::


File: oo-browser.info,  Node: Introduction,  Next: Environments,  Prev: Top,  Up: Top

Introduction
************

   The "OO-Browser" is a multi-windowed, interactive, object-oriented
class browser designed for professional use.  Its user interface is
similar to the well-known Smalltalk browsers `[Goldberg 83]', yet it is
much more flexible and easy to use.

The OO-Browser is unique in several respects:
   * It currently supports seven object-oriented languages (Eiffel, C++,
     Objective-C, CLOS (Lisp), Java, Python and Smalltalk), one
     non-object-oriented language (C), and one documentation language,
     (GNU Info).

   * It may be used for both system exploration and for browsing
     purposes as part of a professional software development tool chest.

   * It quickly displays and provides views of complicated inheritance
     trees, making it an important tool for understanding
     object-oriented systems.

   * It has a completely direct-manipulation interface with multiple
     modalities.

   * It is integrated with a powerful editing environment that can be
     customized to meet personal work styles.

   The picture on the following page highlights the major components of
the OO-Browser user interface.  (If you are reading the online Info
version of this manual, see the last paragraph of this node for a link
to the aforementioned picture.)

   The windows across the top of the OO-Browser frame are called "class
listing windows"; they display "listing buffers" with a single class
name per line.  The "viewer window" fills the bottom half of the frame.
It is used to display class source and summary information.  It is
also used to display help on the OO-Browser command set.  Pictured here
in the viewer window is part of the browser help buffer, summarizing
its command key bindings.

   All key bindings described throughout this manual are effective only
within listing buffers, unless otherwise indicated.  This means that
the keys may not be used within the buffers displayed in the class
viewer window.  Instead, all normal editing keys are available in most
buffers displayed in the viewer window.

   Mouse click on the following filename to view a picture of the
textual OO-Browser: "im/oobr-text.eps".  Under InfoDock, use the middle
mouse button.  Under Emacs with the Hyperbole system loaded, use the
shift-middle mouse button or shift-left on a two button mouse.
Otherwise, there is no built-in way to view the picture.


File: oo-browser.info,  Node: Environments,  Next: Usage,  Prev: Introduction,  Up: Top

Working with Environments
*************************

   Whenever the OO-Browser is in use, an Environment is selected.  An
Environment may be built or simply specified.  An "Environment
specification" tells the browser what to include in the construction of
an Environment.  (*Note Creating Environments::, for more information.)
An OO-Browser "Environment" includes a set of inter-class relationships
together with a few browser settings.  The phrase, "the Environment",
refers to the current OO-Browser Environment.  Many browser commands
depend on information in the Environment.

   The set of classes included in an Environment is specified by two
lists of directories, below which all of the Environment's class source
files are to be found.  (The OO-Browser will automatically search
sub-directories below the directories specified.)  The first list of
directories is called the "Library search list"; it defines the
locations of stable, typically reusable classes that have been released
for general use.  The second list is called the "System search list";
it defines the locations of unreleased classes being developed, often
for a particular system.  All class names within a single Environment
must be unique to ensure proper operation of the browser.

   The OO-Browser lets one create, update and save Environments.  Once
an Environment file has been created, it may be loaded at any time.  The
browser will then use this Environment for all of its operations until
another one is loaded.

   The browser maintains a separate Environment for each programming
language on which it is used.  Thus, if one switches from Eiffel to C++
browsing and then back to Eiffel browsing, the Eiffel environment will
not need to be reloaded; it will appear immediately and the frame will
appear as if the Eiffel OO-Browser were invoked for the first time.

   The recommended default name for Environment files is, `OOBR'.  We
recommend that you store each Environment in the top-level directory of
the first system pathname in the Environment, i.e. the root directory
of a system's code.

   Environment files are automatically created and loaded by the
OO-Browser so that you need never become familiar with their format.
You are responsible for remembering which Environment files you create
and for requesting their use whenever desired.  *Note Invoking the
OO-Browser: Invoking, for information on how to specify a different
Environment file for use.

* Menu:

* Creating Environments::
* Building Environments::
* Loading Environments::
* Saving Environments::


File: oo-browser.info,  Node: Creating Environments,  Next: Building Environments,  Prev: Environments,  Up: Environments

Creating Environments
=====================

   Environment specifications are useful when one wants to describe a
number of Environments to the OO-Browser but wants to defer their
construction until later.  Large environments then can be built
overnight.  *Note Building Environments::, for more information.

   Every Environment must be specified before it can be built or used.
Thus, specifying an Environment is the first step in creating it.
Environment specifications are created with the {`C-c C-c'}
`(br-env-create)' command, which prompts for all necessary information.
This command may be invoked repeatedly to quickly specify a number of
different Environments.

Here are the Environment specification components for which you will be
prompted:
`System search directories'
     List of directories below which other System directories containing
     class source code and directories of class source files may be
     found.

`Library search directories'
     List of directories below which Library files of class source code
     and directories of class source files may be found.

     *EIFFEL NOTE: We strongly suggest that if you have previous
     versions of library class source below any of these directories,
     that you move them elsewhere, e.g. ISE's Eiffel version "2.1"
     directory of source.  These will cause class naming conflicts that
     the browser will not resolve to your satisfaction.  The basic rule
     is that every class name within a single Environment should be
     unique.  Use {`M-e'} to help find duplicate classes.*


File: oo-browser.info,  Node: Building Environments,  Next: Loading Environments,  Prev: Creating Environments,  Up: Environments

Building Environments
=====================

   An Environment specification tells the OO-Browser what to include in
the Environment, but the Environment still must be built before use.
When a new Environment must be built or when a large number of changes
have been made to classes in the Environment, the following commands are
useful:

`{C-c C-e}'
     build all Env classes `(br-env-rebuild)'  (This prompts for whether
     or not to use a background process to build the Environment.)

`{L}'
     build Env Library classes only `(br-lib-rebuild)'

`{S}'
     build Env System classes only `(br-sys-rebuild)'

   When class names or locations have changed or the Environment's
inheritance structure is modified, the Environment must be rebuilt.  For
small Environment changes, one may use the class addition and deletion
features of the browser.  *Note Adding and Deleting Classes::, for more
information.

   The OO-Browser lets you build large environments in the background so
you can go on to other work while waiting on a build.  When the build is
complete, it will ask you whether you want to browse the built
Environment.

   Alternatively, very large Environments may be built overnight by
invoking Emacs in batch mode at a scheduled time.  To do this, you must
first create an Environment specification so that the browser knows what
to build.  *Note Creating Environments::.  Then use a shell command
line of the form below (substitute your local OO-Browser installation
directory for *<BR-DIR>*):
     emacs -batch -l <BR-DIR>/br-start.el *Env-Spec-File* \
           ... *Spec File* -f br-env-batch-build > log-file

for example:
     emacs -batch -l br-start.el OOBR -f br-env-batch-build > log-file

   Typically when using the above command line, one should redirect the
standard output stream to a log file for later examination, as is done
in the above example.  This helps ensure that either the Environment
built successfully or a message indicating the cause of failure is
provided.


File: oo-browser.info,  Node: Loading Environments,  Next: Saving Environments,  Prev: Building Environments,  Up: Environments

Loading Environments
====================

   A new Environment may be loaded for use at any time within the
OO-Browser.  One may either select the load Environment command from the
OO-Browser command summary or may use the {`C-c C-o'} `(oo-browser)'
command to select a language and environment to load.  When prompted
for the Environment file to load or create, an immediate {RET} will
browse the most recently loaded Environment, if any.  Otherwise, it
will create and load the Environment file in the current directory
whose name is given by the BR-ENV-DEFAULT-FILE variable (default is
`OOBR').


File: oo-browser.info,  Node: Saving Environments,  Prev: Loading Environments,  Up: Environments

Saving Environments
===================

   The OO-Browser automatically builds and saves Environments in most
cases.  Occasionally one may find a need to force the Environment to be
saved to a file, as in the case when one wants to save an Environment
under a different file name.

   Use {`C-c C-s'}, the `(br-env-save)' command to force an Environment
save to occur.  The command will prompt for a file to save to, with the
default as the current Environment file name.


File: oo-browser.info,  Node: Usage,  Next: Options,  Prev: Environments,  Up: Top

Using the OO-Browser
********************

* Menu:

* Invoking::                    Invoking the OO-Browser
* Top-Level Classes::           Displaying Top-Level Classes
* Moving to Entries::
* Saving Listings::             Writing a Listing to a File
* Children and Parents::        Browsing Children and Parents
* Descendants and Ancestors::   Browsing Descendants and Ancestors
* Viewing and Editing::         Viewing and Editing Classes
* Browsing Elements::
* Browsing Categories::
* Browsing Protocols::
* Browsing Implementors::
* Exiting a Listing::
* Quitting and Refreshing::     Quitting and Refreshing the OO-Browser
* Using the Mouse::
* Getting Help::
* Locating Entries::
* Filtering Entries::
* Ordering Entries::
* Statistics::                  Environment and Class Summaries
* Class Info::                  Language-Specific Class Information
* Adding and Deleting Classes::
* Completing Names::
* Graphical Browsing::          Graphical OO-Browser Interfaces


File: oo-browser.info,  Node: Invoking,  Next: Top-Level Classes,  Prev: Usage,  Up: Usage

Invoking the OO-Browser
=======================

   The OO-Browser supports the following languages: C++ or G++, C, Info
(the online manual format), CLOS (Lisp), Eiffel, Objective-C, Java (as
documented in `[Java 95]'), Python and Smalltalk.  The OO-Browser may be
used on source written in any of these languages by using {`C-c C-o'}
or, if that key has not been setup, by using {`M-x oo-browser RET'}.
This command will prompt for the language to browse, the Environment
specification of directories to browse, and then will either load the
Environment or build it.  After the Environment is built, it will
display the set of classes (or nodes) in the Environment.  (Choose C++
if you are browsing plain C code.)

   If you have exited the browser using {`q'} and wish to browse the
same Environment again, use {`C-u C-c C-o'}, which will immediately
redisplay the browser just as you left it.

   Alternatively, you can invoke the browser on a specific language
Environment, e.g. to bring back the last Environment browsed under that
language.  The language-specific browser invocation commands are: {`M-x
eif-browse RET'}, {`M-x c++-browse RET'}, {`M-x info-browse RET'},
{`M-x clos-browse RET'}, {`M-x objc-browse RET'}, {`M-x python-browse
RET'}.

A prefix argument given to any of these commands will cause it to prompt
for an Environment file to use as the current Environment.

   On startup, if the selected Environment has been saved to a file, it
will be loaded; otherwise, the user will be asked to specify the
Environment.  The specification will be saved under the previously given
file name.  The browser will then load this Environment specification
file.

   If the browser loads an Environment file and finds only a
specification, it will prompt the user in the minibuffer window with a
request to build the Environment.  It will continue to prompt the user
until a full Environment is built or loaded and then the browser will
start, displaying its multi-windowed interface.  To abort from these
prompts and to cancel the browser invocation request at any time, use
{`C-g'} `(keyboard-quit)', the standard way to abort an unfinished
command within Emacs.

   Once an Environment has been loaded, entering and quitting the
browser are rapid actions, allowing a smooth transition between editing
and browsing.


File: oo-browser.info,  Node: Top-Level Classes,  Next: Moving to Entries,  Prev: Invoking,  Up: Usage

Displaying Top-Level Classes
============================

   The OO-Browser starts by displaying all top-level classes in the
Environment.  "Top-level classes" are those that do not inherit from
any others.  The browser can show all top-level classes or System or
Library classes only.  Once in the browser, use:

`{s}'
     System top-level classes only

`{l}'
     Library top-level classes only

`{t}'
     all top-level classes in Environment

   Note that selection of any of these commands does not affect the
ancestry or descendancy trees for any given class.  Each simply limits
which trees are easily accessible for browsing.  For example, selection
of Library top-level classes only, followed by the browser show
children command, {`c'} `(br-children)', would display the name of a
System class if the System class directly inherits from the selected
Library class.

   To see an ordered listing of all of the classes in a particular part
of an Environment, use a prefix argument with the commands given above:

`{C-u s}'
     all System classes

`{C-u l}'
     all Library classes

`{C-u t}'
     all Environment classes.


File: oo-browser.info,  Node: Moving to Entries,  Next: Saving Listings,  Prev: Top-Level Classes,  Up: Usage

Moving to Entries
=================

   Many browser commands operate on the current entry in a listing
window.  {`C-n'} `(br-next-entry)' moves point to the next entry in a
listing buffer.  {`C-p'} `(br-prev-entry)' moves to the previous entry.
Both take prefix arguments and use them as the number of entries by
which to move.


File: oo-browser.info,  Node: Saving Listings,  Next: Children and Parents,  Prev: Moving to Entries,  Up: Usage

Writing a Listing to a File
===========================

   Many standard editing keys are rebound in listing buffers to provide
a useful set of accessible commands.  Nonetheless, one needs to be able
to store and to edit listing buffers.  The {`C-c C-w'}
`(br-write-buffer)' command provides this capability.  The command
prompts for a file name under which to save the current buffer.  One
may then quit the browser, read in the file and edit it as a plain text
file.


File: oo-browser.info,  Node: Children and Parents,  Next: Descendants and Ancestors,  Prev: Saving Listings,  Up: Usage

Browsing Children and Parents
=============================

   {`c'} displays the children of the class at point; {`p'} displays
its parents.  {`C-u c'} displays the children of all classes in the
present listing window; {`C-u p'} does the same for parents.


File: oo-browser.info,  Node: Descendants and Ancestors,  Next: Viewing and Editing,  Prev: Children and Parents,  Up: Usage

Browsing Descendants and Ancestors
==================================

   The OO-Browser is very fast at computing ancestor and descendant
hierarchies, accounting for multiple inheritance and cycles where
permitted.  Descendant and ancestor listings provide an immediate
overview of some key relationships among class groupings.

   With point on any class entry line in a listing buffer, {`d'} shows
descendants for the class and {`a'} shows ancestors.  {`C-u d'} shows
the descendant trees for all classes in the current listing buffer and
{`C-u a'} does the same for ancestors.

   The ancestor tree for a given root class is normally shown branching
out from the root class.  This means that higher-level ancestors, those
further away from the root class, are shown in descending trees below
lower-level ancestors.  The leaves of the tree represent the ancestors
furthest from the root, as one might expect.

   This, however, is the inverse of inheritance trees.  Some people
prefer to see ancestor trees like inheritance trees, with parents above
children.  This is an "inverted ancestor tree".  To obtain this view of
ancestors use {`M- -1 a'} for ancestors of the current class.  For
ancestors of all classes in the current buffer, use {`M- -2 a'}, or any
negative prefix argument lest than -1.  Inverted ancestor trees may be
made the default by setting `br-invert-ancestors' non-nil, as in:

     	{`M-x set-variable RET br-invert-ancestors RET t RET'}

This is a personal setting that affects all Environments used by the
browser.


File: oo-browser.info,  Node: Viewing and Editing,  Next: Browsing Elements,  Prev: Descendants and Ancestors,  Up: Usage

Viewing and Editing Classes
===========================

   One of the major uses of the OO-Browser is to view or edit class
source texts.  {`v'} will view the source for the class or element name
at point in a read-only mode in the viewer window; it will not select
the viewer window.  {`e'} does the same, except that it edits the
element source in a read-write mode, if the user has write permission
for the source file.  It also selects the viewer window.

   A prefix argument to either of these commands, as in {`C-u v'} or
{`C-u e'}, causes them to prompt for the entry to display.  Full class
and element name completion is provided once an Environment has been
loaded and built.  *Note Completing Names::.

   The value of the variable BR-EDIT-FILE-FUNCTION is the function that
the browser calls when a source file entity is displayed for editing.
The value of BR-VIEW-FILE-FUNCTION is the function called to view a
source file entity.  *Note Using an External Viewer or Editor: External
Viewing, for information on using non-Emacs editors and viewers with
the browser.

   If a user has no read access rights to a file, this will be apparent
when the browser tries to display the file and fails.  If the user does
not have write permission to the class source file, the standard
BR-EDIT-FILE-FUNCTION may display the file in a read-only mode
(indicated by two percent signs, %%, at the front of the buffer mode
line).  This is a warning that one should not attempt to edit the file.
In some cases, one really wants to try to edit such a file; in those
cases, the buffer may be toggled between read-only and read-write modes
via the Emacs command, `(toggle-read-only)', usually bound to {`C-x
C-q'}.

   Once a class has been displayed for viewing, {SPC} will scroll its
source text up (forward) almost a windowful; {DEL} will scroll it down
(backward) almost a windowful.  In fact, this is a general means for
scrolling the OO-Browser viewer window whenever point, as shown by the
Emacs cursor, is in a listing window.  When a class is selected for
editing, {`C-v'} will scroll up, {`M-v'} will scroll down, assuming the
standard Emacs key bindings.

   Sometimes one needs to quickly switch back and forth between the
viewer window and the current listing window.  The normal Emacs window
movement commands often are cumbersome in such instances.  Instead
`(br-to-from-viewer)' bound to {`C-c C-v'}, allows the desired back and
forth movement.  It acts as a toggle switch, alternately moving between
the buffer in the viewer window and the prior listing buffer.

   By default, the OO-Browser displays class definition files in their
entirety.  If there are multiple classes in a file, you will be able to
scroll through all of them.  If you prefer that only the selected class
be visible, enable the `br-narrow-view-to-class' option flag.  When set
to a non-nil value, this flag narrows the source buffer so that only
the class of interest and its preceding comments are visible.  To
examine other classes in the same file, you must execute a {`C-x n w'}
`(widen)' command when in the narrowed buffer.  (Use {`C-x w'} under
Emacs 18.)

   If the browser is used on a small screen, it may be helpful to use
the a full frame to view or edit a buffer of source code.  If point is
in a listing buffer, pressing {`1'}, the number one, will expand the
viewer window buffer to the full frame.  When the browser is
re-invoked, it will look just as it did before.  If point is in the
viewer window, {`C-x 1'} `(delete-other-windows)', will do practically
the same thing, except that when the browser is re-invoked it will not
look precisely as it did before.

   If point is in a listing window, the buffer displayed in the viewer
window may be killed with the {`C-c C-k'} `(br-kill)' command.  (A
killed buffer is removed from the current Emacs session.)

   If point is in the viewer window, as it will be after editing a class
buffer, use the standard Emacs command {`C-x k'} `(kill-buffer)'
instead.


File: oo-browser.info,  Node: Browsing Elements,  Next: Browsing Categories,  Prev: Viewing and Editing,  Up: Usage

Browsing Elements
=================

   A "feature" of a class is either a routine or attribute defined in
the class.  An "element" is either a feature or an instance of a class.
A number of OO-Browser languages support feature browsing, as
documented in *Note Languages::.  Instance browsing is only supported
in very limited form, for class instances which exist within the code
itself.  For example, under Common Lisp and CLOS, a default class called
`[function]' is defined whose instances are all named functions defined
within the environment.  A "default class" is a class created to
categorize elements of the Environment for browsing; default classes
are not specified within the Environment source code.

   Use {`f'} to display a listing of the features or elements of the
class at point, including inherited features.  Generally, this includes
only routines.  Use {`M-0 f'} to turn off the display of inherited
features; use the same command again to re-enable display of inherited
features.

   If inherited features are off and there are no feature definitions
for the class, the class definition is displayed instead, so that its
feature declarations may be browsed.

   Use {`C-u f'} to display a listing of the features or elements of
all classes in the present listing window.  Prior versions of the
OO-Browser used {`r'} to display features.  This key remains for
backward compatibility but may be used for another purpose in the
future.

   Move point to an element name and use {`v'} to view its source
definition or {`e'} to edit its source.  Use {`F'} to see the full
signature tag of an element, which includes its argument names and
types, if any.  {`C-u F'} lists the signatures of all elements in the
current listing.  This is handy when several elements from the same
class have the same name but differ in signature.

   *Note Using the Mouse::, for how the Action and Assist Keys may be
used for browsing elements.


File: oo-browser.info,  Node: Browsing Categories,  Next: Browsing Protocols,  Prev: Browsing Elements,  Up: Usage

Browsing Categories
===================

   The definition of a "category" is language-specific.  Some languages
such as Smalltalk use categories to group related classes together.  The
OO-Browser does not yet support this kind of category.

   A set of Objective-C categories segments a single class into
groupings of related features.  When a class category is defined, the
category name appears within a set of parentheses, so the OO-Browser
displays category names with parentheses around them to distinguish
them from classes.  The aggregation of all of the categories defined by
a class and its ancestors represents the complete class definition.  The
OO-Browser does support this kind of category.

   Use the {`C'} key when point is on a class listing entry to obtain a
list of the categories defined for the class within the Environment
source code (this excludes inherited categories).  Use {`C-u C'} to
list the categories for all classes in the current listing.  Thus, to
see the full set of categories for a class, use {`a'} to list the
ancestors of the current class and then {`C-u C'} to show all direct
and inherited categories of the class.

   Use {`v'} or {`e'} to view or edit the class category definition
associated with a category entry at point.  *Note Browsing
Implementors::, for an explanation of how to browse the classes that
directly implement a category.

   Use {`f'} with point on the default `[category]' class to list all
categories defined in the Environment.


File: oo-browser.info,  Node: Browsing Protocols,  Next: Browsing Implementors,  Prev: Browsing Categories,  Up: Usage

Browsing Protocols
==================

   The definition of a "protocol" is language-specific.  It generally
refers to an interface specification to which a class is said to
conform.  A class conforms to a protocol by implementing the set of
features defined in the protocol.

   Presently, the OO-Browser support protocols only under Objective-C.
Objective-C protocols are sometimes called *formal protocols*.
Protocol interfaces are specified in a manner similar to classes but
their features are only implemented in conforming classes.  A single
protocol can inherit from any number of other protocols; thus, any
conforming class must conform to all of its ancestor protocols.

   Class definitions list the protocols to which they directly conform,
within a set of angle brackets.  So the OO-Browser displays protocol
names with angle brackets around them to distinguish them from classes.

   Use the {`P'} key when point is on a class listing entry to obtain a
list of the protocols to which the class directly conforms (this
excludes inherited protocols).  Use {`C-u P'} to list the direct
protocols for all classes in the current listing.  There is not yet a
way to show the complete set of protocols to which a class conforms,
which includes all protocols inherited from other protocols and all
protocols inherited from ancestor classes.

   If you use {`P'} when point is on a class' protocol entry, the
specification of the protocol will be displayed.  Use {`v'} or {`e'} to
view or edit the class or class category definition associated with a
protocol entry at point.

   Use standard class browsing keys when on a protocol entry to examine
its parents, children, ancestors or descendants.  *Note Browsing
Implementors::, for an explanation of how to browse the classes that
directly conform to a protocol.

   Use {`f'} with point on the default `[protocol]' class to list all
protocols defined in the Environment.


File: oo-browser.info,  Node: Browsing Implementors,  Next: Exiting a Listing,  Prev: Browsing Protocols,  Up: Usage

Browsing Implementors
=====================

   Sometimes it is important to see the list of classes that define a
particular element name.  These are called the element's
"implementors".  With point on an element listing, {`I'} will compute
and display the element's implementor list.  {`C-u I'} will do the same
for all elements in the present listing.

   Move point to an implementor class name and then use {`v'} or {`e'}
to view or edit the element associated with the class.  If an element
name is defined with different signatures in a single class, the class
will be listed as an implementor multiple times.  Each class entry can
be used to display a different element.  {`C-u F'} will display the
element signature associated with each class entry in the same order as
the class entries in the present listing buffer.


File: oo-browser.info,  Node: Exiting a Listing,  Next: Quitting and Refreshing,  Prev: Browsing Implementors,  Up: Usage

Exiting a Listing
=================

   When done with a browser listing buffer, one should clear and exit
from the buffer's display with {`x'}.  This command also displays the
previous listing level, if any, and moves point to its previous
position within this buffer.

   In this way, the command provides a quick and clean way to exit back
to a previous listing level; you may exit a single level at a time or
all the way back to the top-level listing buffer through repeated
invocation of the command or by sending a prefix argument value to the
command.

   There is no need to exit from listing buffers to quit from the
browser.  You may quit, perform other actions, and then re-invoke the
browser at the same point from which you left.


File: oo-browser.info,  Node: Quitting and Refreshing,  Next: Using the Mouse,  Prev: Exiting a Listing,  Up: Usage

Quitting and Refreshing the OO-Browser
======================================

   {`q'} quits from the browser temporarily.  The same command with a
prefix argument quits from the browser permanently and kills all
non-modified browser buffers.  It will not kill any of the class source
buffers.

   If you are familiar with Emacs windowing, you may quickly alter the
window configuration of the frame while in the browser, either
intentionally or more likely unintentionally.  If you execute
non-browser Emacs commands while in the browser, you may find other
buffers have taken the place of your browser buffers.  In either case,
you may refresh the browser display and restore it to the way it was
when you originally invoked it, by using {`M-x br-refresh RET'} or with
{`C-c C-r'} when in a browser listing buffer.


File: oo-browser.info,  Node: Using the Mouse,  Next: Getting Help,  Prev: Quitting and Refreshing,  Up: Usage

Using the Mouse
===============

   Once configured, mouse control within the OO-Browser is helpful and
easy to use.  Under InfoDock, XEmacs and Emacs 19, the right mouse
button, called the Menu Key, pops up a menu of OO-Browser commands when
clicked within an OO-Browser listing buffer.  Under XEmacs and Emacs
19, the same menu is added to the menubar used in listing buffers.
Under InfoDock with mode-specific menus turned on, the menubar is
devoted to OO-Browser commands.

   Even if the above features are not available to you, if you have
mouse support in your Emacs, the following features are available.  A
single mouse button, called the "Action Key", is used for most purposes.
The Action Key is bound to the shift-middle mouse button under standard
Emacs, to the middle mouse button under InfoDock, or to the shift-left
button on a two-button mouse.

   A second button, called the "Assist Key", is used for help and other
ancillary functions.  The Assist Key is bound to the shift-right button.
The `br-help-ms' file uses a table format to summarize mouse control
within the browser, it may be displayed within the browser via the
{`H'} `(br-help-ms)' command.

   Within an empty listing buffer, clicking the Action Key displays the
browser command menu; the Assist Key displays a menu listing
language-specific source files.  Within this menu, the Action Key
selects a buffer for display, the Assist Key marks the buffer for
deletion.  To perform the deletes, click the Action Key after the last
line of the menu.  If the Assist Key is clicked after the last line, the
deletes are undone and a list of all current editor buffers is shown,
allowing you to select buffers other than those containing classes.

   The mouse buttons can be used to scroll the viewer window a page at a
time by clicking after the end of any line.  The Action Key scrolls the
window up (forward) a windowful and the Assist Key scrolls it down
(backward) a windowful.

   The Action Key acts as follows when in an OO-Browser listing buffer.
If the button is pressed:

   * on a blank line following all entries or in a blank listing
     buffer, the browser command help menu is displayed in the viewer
     window exited;

   * at the beginning of a (non-single character) class name, the class'
     ancestors are listed;

   * at the end of an entry line, the listing is scrolled up;

   * on the `...', following a class name, point is moved to the class
     descendency expansion;

   * before an element name, the implementor classes of the name are
     listed;

   * anywhere else on an entry line (i.e. on the entry), the entry's
     source is displayed for editing.

   The Assist Key acts as follows when in a listing buffer.  If it is
pressed:

   * in a blank buffer, a selection list of buffer files is displayed;

   * at the beginning of a (non-single character) class, the class'
     descendants are listed;

   * at the end of an entry line, the listing is scrolled down;

   * on the `...', following a class name, point is moved to the class
     expansion;

   * anywhere else on a class line, the class' elements are listed;

   * anywhere else on an element line, the element's implementor
     classes are listed;

   * on a blank line following all entries, the current listing buffer
     is exited.


File: oo-browser.info,  Node: Getting Help,  Next: Locating Entries,  Prev: Using the Mouse,  Up: Usage

Getting Help
============

   The OO-Browser is very intuitive to operate, but help is always a
key or button press away when needed.  Besides the online and printed
versions of this manual, there is an online quick reference built into
the OO-Browser.  Once the browser windows appear, press {`h'} at any
time to bring up a buffer full of command help.

   For more extensive documentation on each browser key, use the Emacs
command {`C-h k KEY-SEQUENCE'}.


File: oo-browser.info,  Node: Locating Entries,  Next: Filtering Entries,  Prev: Getting Help,  Up: Usage

Locating Entries
================

   The {`w'} `(br-where)' command can be used to locate the source file
associated with a listing entry.  It prints the full pathname of the
source file in the minibuffer window.  A prefix argument as in, {`C-u
w'}, causes the command to prompt for the class or element name to
locate.  Full completion is provided.  *Note Completing Names::.

   The {`m'} `(br-match)' command provides a quick mechanism for
locating any classes in the Environment whose names match to an
expression in part or in whole.  The browser will prompt for the
expression to use.  All matching names are displayed in ascending order.

   By default the expression is treated as a regular expression.  A
prefix argument sent to the command tells it to treat the expression as
a string.

   After each search, the command reports the number of matching classes
found and displays them in the current listing window.  It then prompts
for another expression to key on.  The selected set is then filtered
once again.  This cycle continues until the {RET} is pressed without
giving an expression.  This process allows for easy location of desired
classes.

   When the command is invoked (first time through the loop), if the
{RET} key is pressed without giving a match expression, the search will
match to all classes referenced in the Environment.

   If you want a regular expression to match to whole class names
exclusively, begin it with a '^' and end it with a '$' character which
match to beginning of name and end of name, respectively.  Thus,
"^....$" would match to class names with exactly four characters.  A
string match always matches to any class name that contains the matching
string.


File: oo-browser.info,  Node: Filtering Entries,  Next: Ordering Entries,  Prev: Locating Entries,  Up: Usage

Filtering Entries
=================

   The {`M'} `(br-match-entries)' command works much like the
`(br-match') command described in, *Note Locating Entries::, except
that it matches only to entries in the current listing buffer.  It thus
allows you to filter a listing to just those entries that you care to
browse.  It prompts you for a regular expression of entries to match
and then deletes entries that don't match.  A prefix argument sent to
the command tells it to treat the match expression as a string.

   After each search, the command reports the number of matching entries
found and displays them in the current listing window.  It then prompts
for another expression to match.  The selected set is then filtered
once again.  This cycle continues until the {RET} is pressed without
giving an expression.  This process allows for easy incremental
filtering of listings.

   When the command is invoked (first time through the loop), if the
{RET} key is pressed without giving a match expression, the search will
match to all entries in the listing, so no filtering will be done.

   If you want a regular expression to match to whole entries
exclusively, begin it with a '^' and end it with a '$' character which
match to beginning of line and end of line, respectively.  Thus,
"^....$" would match to entry lines with exactly four characters.  A
string match always matches to any entry that contains the matching
string.


File: oo-browser.info,  Node: Ordering Entries,  Next: Statistics,  Prev: Filtering Entries,  Up: Usage

Ordering Entries
================

   Once you have a desired set of names in a browser listing window, you
may want to re-order.  For a simple ascending order sort by name, use
{`o'}.  To sort the lines in the current listing window accounting for
leading whitespace, use a positive prefix argument.  To sort the lines
in descending order accounting for leading whitespace, use a negative
prefix argument.  Note that all of the top-level class display commands
automatically order their output lists.  *Note Displaying Top-Level
Classes: Top-Level Classes.

   To sort in descending order, first sort into ascending order with
{`o'} to strip any leading whitespace and then use a negative prefix
argument to sort the names into descending order.


File: oo-browser.info,  Node: Statistics,  Next: Class Info,  Prev: Ordering Entries,  Up: Usage

Environment and Class Summaries
===============================

   The {`#'} `(br-count)' command displays in the minibuffer the number
of entries in the present listing buffer.

   The {`M-c'} `(br-class-stats)' command displays in the minibuffer
window the number of parents and children for the selected class; with
a prefix argument, it prompts for the class name to use.

   The {`M-e'} `(br-env-stats)' command displays the specification for
the current Environment along with a few Environment statistics
(OO-Browser version used to build the Environment, total classes,
number of System and Library classes, number of duplicate and undefined
classes) in the viewer window.  With a prefix argument, it displays in
the minibuffer window the basic statistics only, leaving the contents
of the viewer window intact.


File: oo-browser.info,  Node: Class Info,  Next: Adding and Deleting Classes,  Prev: Statistics,  Up: Usage

Language-Specific Class Information
===================================

   Presently, this feature is available only for Eiffel browsing.

   With point on a class name in a listing buffer, the command, {`i'}
`(br-entry-info)', displays the class' parents, attributes and routines
with routine call summaries.  This is its default behavior.

   {`M-x eif-info-use-short'} will instead cause the `(br-entry-info)'
command to run the Eiffel 'short' command on a class, thereby
displaying its specification.  {`M-x eif-info-use-flat'}, will cause
the command to run the Eiffel 'flat' command on a class, thereby
displaying its complete feature set.  Use {`M-x eif-info-use-calls'} to
reset this command to its default behavior.


File: oo-browser.info,  Node: Adding and Deleting Classes,  Next: Completing Names,  Prev: Class Info,  Up: Usage

Adding and Deleting Classes
===========================

   A file containing class definitions may be added to the Environment
with the {`C-c ^'} `(br-add-class-file)' command.  This will prompt for
the file name, scan the file, and then update the Environment.  If a
class defined in the file is already in the Environment, its
information will be replaced with the information gathered from the
file; otherwise, the class will be added to the Environment.  This
command does not update the browser display; one must issue a browser
command after the add command in order to see any change.

   To add a single class from a file containing multiple classes, read
the file into an Emacs buffer, narrow the buffer to the desired class
and then execute the add command.  *Note Narrowing: (emacs)Narrowing.

   {`C-c ^'} is normally globally bound in the OO-Browser
initialization file, `br-init.el', so that it may be used outside of
the browser when editing classes.

   To delete a class from the Environment, display the class name in a
listing window using the {`m'} `(br-match)' command if necessary.
(*Note Locating Entries::.)  Move point to the desired class name and
hit {`C-c C-d'} `(br-delete)' to delete the class.  This will remove
the class name at point after the class is deleted from the Environment.


File: oo-browser.info,  Node: Completing Names,  Next: Graphical Browsing,  Prev: Adding and Deleting Classes,  Up: Usage

Completing Names
================

   Whenever the browser prompts for a name and an Environment has
already been loaded or built, one may use the browser's identifier name
completion facilities to help in entering the name.  These features
allow you to type as much of the name as you know and then have the
browser fill in what it can.  The relevant keys are:

{TAB}
     complete as much as possible of a class or element name

{SPC}
     complete up to one word of the class or element name

{`?'}
     show all possible completions for class or element name

   You may also use the browser's completion facilities outside of the
browser, for example, when editing code.  *Note Using Standalone
OO-Browser Features: Standalone, and the description of
`(br-complete-type)'.

