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: Graphical Browsing,  Prev: Completing Names,  Up: Usage

Graphical OO-Browser Interfaces
===============================

   The X interface to the OO-Browser is called, "xoobr".  It provides a
simple but effective means of navigating through OO-Browser hierarchy
and element relations.  (The NEXTSTEP OO-Browser is very similar to the
X version, so use the documentation herein if you need any help with
it.)

   Any number of xoobr sessions may be established at the same time.
Each one is used to gain a particular view on an Environment.  The
textual OO-Browser is used to filter a set of classes for display in an
xoobr process.  For this reason, xoobr is invoked from within the
textual OO-Browser.

   If running under the X window system, Action Key click on the
following filename to view a picture of the X OO-Browser:
"im/oobr-x.xwd".

   {`M-g'} `(br-tree-graph)' displays the current listing buffer's
entries in a graphical form.  It ignores the show features setting so
that you can capture the current listing without the need to alter that
setting.

   {`M-d'} `(br-tree)' selects the current class and displays its
descendancy graph in tree-form by starting a new xoobr session.  With a
prefix argument, {`C-u M-d'}, displays descendancy trees for all
classes at the current browser level.  They are all grouped under some
imaginary joining node so as to maintain the concept of one tree per
xoobr view.

   {`M-f'} `(br-tree-features-toggle)' is used before creating a
graphical descendency view to determine whether or not to include the
features of each class in the listing as child nodes of the class.  It
toggles between showing features and not showing them in descendancy
views.  The setting applies across all OO-Browser languages.  The
default setting is to not add features to the view.

   Xoobr views are meant to complement the textual browser interface.
Therefore, the two most common actions used in the text browser are
performed in a similar manner within an xoobr view.  A click on a node
with the left mouse button highlights the node and then displays the
appropriate class text in the chosen editor, ready for editing.  A
click of the middle button performs similarly but displays the
associated class for viewing only.

   [The right mouse button is disable in this release of the X
OO-Browser because of an inability to debug a problem in limiting its
use to tree nodes.]  The right mouse button when depressed over a node
displays a short menu of commands that may be applied to the node.  The
only ones of real interest at this point are the collapse and expand
entries which let you hide and then restore the display of a node's
subtree.  This allows you precise control over the amount of detail you
receive in various parts of the hierarchy.

   The Help button in the upper right of the an xoobr session window
when selected displays a few pages of help text regarding the program
itself.

   The {`M-k'} `(br-tree-kill)' command will prompt to see if you want
to terminate all xoobr sessions started from within the current editor
session.  If you answer affirmatively, all such processes disappear, as
your screen will quickly indicate.

   The upper left of a session window contains a set of buttons which
display menus.  The only menu entry you need be concerned with at all is
found under the file menu, labelled "Quit".  xoobr processes may also be
terminated by issuing the kill command mentioned just before.  A third
menas of killing such processes is by sending the permanent `(br-quit)'
command, {`C-u q'}, to the textual browser.  You will then be prompted
as to whether you want to terminate all xoobr sessions started from
within the current editor session.


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

OO-Browser Options
******************

* Menu:

* 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


File: oo-browser.info,  Node: External Viewing,  Next: Keep Viewed Classes,  Prev: Options,  Up: Options

Using an External Viewer or Editor
==================================

   The OO-Browser allows you to select your desired editor and viewer
programs when you use a multi-windowed display.  By default, both of
these tasks are handled by Emacs so that the browser works on text
terminals.  If you choose an external editor or viewer, Emacs will still
automatically be used whenever you invoke the browser from a text
terminal.

   If you wish to edit classes displayed by the browser in an editor
other than Emacs, set the BR-EDITOR-CMD variable to the command with
which you wish to edit.  Arguments to the command should be placed in
the variables named BR-ED[1-9], with one string argument per variable.
Unused variables should have the value `nil'.  Bear in mind that the
command must generate a new window under your window system.  For
example, the vi editor under UNIX does not create its own window, it
runs within the window in which it is created.  Under X one would
create a new xterm window and then invoke vi.  The command line would
be *xterm -e vi*, the settings in your personal initialization file
would then be:

            `
     (setq br-editor-cmd "xterm" br-ed1 "-e" br-ed2 "vi"
           br-ed3 nil br-ed4 nil br-ed5 nil
           br-ed6 nil br-ed7 nil br-ed8 nil br-ed9 nil)'

   This editor will only be used when the browser is run under a window
system external to Emacs, like X.  (In such a case, the Emacs variable
WINDOW-SYSTEM will be non-nil).

   If you want to view classes in a read-only fashion outside of Emacs,
set the following BR-VIEWER-CMD and BR-VW[1-9] variables in a similar
manner as you did for the editor variables above.

   For example, to use `xmore', an X-compatible version of `more', as
your viewer, use the following settings (assuming all the BR-VW
variables are already null):

            `(setq br-viewer-cmd "xmore")'


File: oo-browser.info,  Node: Keep Viewed Classes,  Next: Inhibit Version,  Prev: External Viewing,  Up: Options

Keep Viewed Classes
===================

   The BR-KEEP-VIEWED-CLASSES flag is turned off by default, indicating
that each time a class is viewed immediately after another one, the
prior one is deleted.  If it is set to any non-nil value, all viewed
classes are left around for selection.

   In typical use, the burden of having to manage all viewed classes is
greater than the benefit of leaving them in memory.  This is why the
flag is off by default.  The class buffer menu can be used to delete
buffers when you want to trim down the number with which you are
dealing.  *Note Using the Mouse::, for details on this technique.

   The value of the BR-KEEP-VIEWED-CLASSES flag may be easily toggled
with the `(br-toggle-keep-viewed)' command bound to {`V'}.


File: oo-browser.info,  Node: Inhibit Version,  Next: Invert Ancestors,  Prev: Keep Viewed Classes,  Up: Options

Inhibit Version Screen
======================

   After you are familiar with the opening OO-Browser version screen,
you may want to disable its display each time the browser is started.
This is done by setting BR-INHIBIT-VERSION non-nil, as in the following
line that would go in your personal OO-Browser initialization file:

     	`(setq br-inhibit-version t)'

This option has no effect on the display of the help screen which
follows the version screen.  Even with this option set, you may display
the version screen at any time from within a browser listing window by
using {`C-c #'} `(br-version)'.


File: oo-browser.info,  Node: Invert Ancestors,  Next: Save All,  Prev: Inhibit Version,  Up: Options

Invert Ancestor Trees
=====================

   *Note Browsing Descendants and Ancestors: Descendants and Ancestors,
for more information.

   This is a global OO-Browser option, it affects all Environments.

   Ancestor trees are normally shown to emphasize how the trees branch
out from their origin.  An initialization file line such as:

     	`(setq br-invert-ancestors t)'

will cause the display of ancestor trees to be inverted such that the
further ancestors appear as roots of the trees and parents (the nearest
ancestors) appear as leaves in the trees.  This ensures that all
listing displays reflect the class inheritance structure with children
below parents.


File: oo-browser.info,  Node: Save All,  Next: Use Children,  Prev: Invert Ancestors,  Up: Options

Save All Lookup Tables
======================

   This is an Environment-specific option set during Environment
specification.  *Note Creating Environments::.

   Half of the browser lookup tables can be built whenever an
Environment is loaded.  If this option is set, these tables will be
stored in the Environment file instead.  This will speed Environment
loading somewhat, at the cost of doubling the file size per saved
Environment.


File: oo-browser.info,  Node: Use Children,  Next: Sort Options,  Prev: Save All,  Up: Options

Build Children Lookup Table
===========================

   This is an Environment-specific option set during Environment
specification.  *Note Creating Environments::.

   This is a highly recommended option that allows for fast descendant
lookups.  The only time one would turn off this option would be when a
file system is extremely short of space.


File: oo-browser.info,  Node: Sort Options,  Prev: Use Children,  Up: Options

Controlling Class Listing Order
===============================

   The OO-Browser normally orders classes and elements in listing
windows according to the ASCII character set.  This sort order is
controlled by the BR-SORT-OPTIONS variable which specifies the command
line options sent to the system `sort' command.  (Under any Emacs 19
variant, this variable is not used by the `br-order' command, bound to
{`o'}.)

   The value of this variable should be a single string of options such
as `-fu' (the default) or `nil' for no options.  The `-f' option folds
upper and lower case to the same character for sort comparisons.  The
`-u' option leaves only unique elements in the listing by eliminating
any duplicate entries.


File: oo-browser.info,  Node: Customization,  Next: Standalone,  Prev: Options,  Up: Top

Personal Customization
**********************

   The BR-SKIP-DIR-REGEXPS variable is a list of regular expressions
which match directory names that the OO-Browser will not descend when
scanning source code trees.

   The BR-FILE-DIR-REGEXP variable specifies a regular expression that
matches to file and directory names that the OO-Browser should scan.
Any others, including those matched by BR-SKIP-DIR-REGEXPS, are ignored.

   The following hook variables are provided so that one may customize
what happens each time the OO-Browser is invoked.  Set them as you
would any other Emacs Lisp hook variables in a personal OO-Browser
initialization file, `~/.br-init.el'.  They all default to null
operations.

   If you want a set of actions to occur each time after the OO-Browser
is invoked, attach them to BR-MODE-HOOK.  For language-specific
actions, a language-specific hook such as BR-EIF-MODE-HOOK, or
BR-C++-MODE-HOOK is run after BR-MODE-HOOK.

   If you want a set of actions to occur after each time that a new
browser listing buffer is created, set BR-CLASS-LIST-HOOK.


File: oo-browser.info,  Node: Standalone,  Next: Languages,  Prev: Customization,  Up: Top

Using Standalone OO-Browser Features
************************************

   A number of browser features may be used independently of the browser
user interface, assuming that a site-wide or personal OO-Browser
initialization file has been loaded into your current Emacs session.

   First, an Environment must be selected and loaded into the OO-Browser
via {`C-c C-o'}.  When the browser user interface is displayed, use
{`q'} to quit.

   Alternatively, you can load an Environment without invoking the
browser user interface by using {`M-x br-env-load RET'}.  The
standalone browser features will use the newly loaded Environment.

The commands that are available for standalone use include:
`br-add-class-file'
     Add a file of classes to the current Environment.  *Note Adding
     and Deleting Classes::.

`br-find'
     Interactively complete class or ELEMENT name and jump to its
     definition.

`br-find-class'
     Display file of class text matching CLASS-NAME in VIEW-ONLY mode
     if non-nil.

`br-complete-type'
     Perform in-buffer completion of a type or element identifier
     before point.

`br-class-path'
     Return full path, if any, to CLASS-NAME.  With optional prefix
     argument INSERT non-nil, insert path at point.

   All of these commands provide full completion.  *Note Completing
Names::, based upon the current OO-Browser Environment.

   When editing and debugging code, one often wants to look at a class
or element definition without having to invoke the browser to locate it.
The `(br-find)' command does exactly that by prompting for a name and
then displaying for editing the class or element definition given by
that name.

   The `(br-find-class)' command is similar. It prompts for a class name
and then displays its source file in a viewable, read-only mode.  To
display a class file in an editable mode, send a prefix argument to this
command.

   When writing code and entering class attribute definitions (variable
definitions), one often has to repetitively enter class names as the
static types for the attributes.  The `(br-complete-type)' command
completes and inserts a class name at point in the current buffer.  The
traditional key to bind such a command to is {`M-TAB'}.  The following
example illustrates its usage.
     	my_list: LIN<-- (point is here)
     
     {`M-TAB'} is hit:
     
     	my_list: LINKED_LIST

   The `(br-class-path)' command prompts for a class name and displays
the full path of the associated class source file in the minibuffer.
With a prefix argument, it inserts the path name at point in the
current buffer.

   The following key bindings are recommended when using these
standalone features:

       `(define-key eiffel-mode-map    "\C-c\C-f" 'br-find)'
       `(define-key c++-mode-map       "\C-c\C-f" 'br-find)'
       `(define-key lisp-mode-map      "\C-c\C-f" 'br-find)'
       `(define-key objc-mode-map      "\C-c\C-f" 'br-find)'
       `(define-key smalltalk-mode-map "\C-c\C-f" 'br-find)'
     
       ;; {`C-M-i'} means {`M-TAB'}.
       `(define-key eiffel-mode-map    "\C-\M-i" 'br-complete-type)'
       `(define-key c++-mode-map       "\C-\M-i" 'br-complete-type)'
       `(define-key lisp-mode-map      "\C-\M-i" 'br-complete-type)'
       `(define-key objc-mode-map      "\C-\M-i" 'br-complete-type)'
       `(define-key smalltalk-mode-map "\C-\M-i" 'br-complete-type)'
     
       `(define-key eiffel-mode-map    "\C-c\C-w" 'br-class-path)'
       `(define-key c++-mode-map       "\C-c\C-w" 'br-class-path)'
       `(define-key lisp-mode-map      "\C-c\C-w" 'br-class-path)'
       `(define-key objc-mode-map      "\C-c\C-w" 'br-class-path)'
       `(define-key smalltalk-mode-map "\C-c\C-w" 'br-class-path)'.

   *Note Eiffel Specifics::, for an Eiffel-specific standalone browser
feature.


File: oo-browser.info,  Node: Languages,  Next: Features,  Prev: Standalone,  Up: Top

Language-Specific Notes
***********************

* Menu:

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


File: oo-browser.info,  Node: C Specifics,  Next: C++ Specifics,  Prev: Languages,  Up: Languages

C Specifics
===========

   The BR-C-TAGS-FLAG variable controls whether or not C constructs are
included within C and C-based language Environments.  By default, this
flag is true.  Use `M-x br-toggle-c-tags RET' to toggle its value.  If
you set it false before building an Environment, then C constructs will
not be included in the Environment.  (Note that C functions are always
included in C++ Environments, regardless of this flag value.)

   If you wish to build an Environment whose source code is entirely C,
ensure that the BR-C-TAGS-FLAG is enabled and then select C++ when
asked for the language to browse.  In the future, a language setting for
C will probably be added.

   C constructs are grouped into default classes for browsing.  The
elements of each default class are the instances of the associated
construct within the Environment.  Use normal element/feature commands
to browse each instance.

              DEFAULT CLASS    C CONSTRUCT
              --------------------------------------
              [constant]       #define constant
              [enumeration]    enum {}
              [function]       non-member function()
              [macro]          #define macro()
              [structure]      struct {}
              [type]           typedef {}
              [union]          union {}


File: oo-browser.info,  Node: C++ Specifics,  Next: CLOS Specifics,  Prev: C Specifics,  Up: Languages

C++ Specifics
=============

   *Note C Specifics::, for details on C-specific support within C++
Environments.

* Menu:

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


File: oo-browser.info,  Node: C++ Element Selection,  Next: C++ Settings,  Prev: C++ Specifics,  Up: C++ Specifics

Source Code Element Selection
-----------------------------

   C++ pure virtual function declarations, which specify method
interfaces but no implementation, appear in class feature listings.
The function name is preceded by the `"> "' string to identify the
function as a pure virtual (deferred) function.  Pure virtuals may be
treated like any other member functions within the browser.  Since
there is no definition for such a function within the class in which it
is listed, its declaration will be shown instead, when requested.

   Friend functions and friend classes give members of another class
access to the private parts of the current class.  They appear in class
feature listings preceded by the `"% "' string.  The keys, {`v'} or
{`e'}, display the friend declaration within the current class.  Use
{`V'}, `(br-view-friend)' to view the definition of the friend class or
function.

   Methods and operators associated with creating and destroying objects
are preceded by the `"+ "' string in listing buffers.  All other method
listing entries are preceded by the `"- "' string.

   One can jump from a C++ declaration to its definition by clicking the
Action Key when within the declaration.  Most importantly, once a class
header file is displayed, simply click on a method declaration to see
its corresponding definition.  Each feature declaration should be
terminated with a semicolon to ensure accurate scanning.  If the method
is inherited from another class, a message at the bottom of the frame
will describe which class the method is defined in once the browser
displays the method definition.

   Parent classes may be browsed in a similar manner by clicking on
their names in an inheritance or declaration clause.  It is therefore
important to click on the method name part of a declaration when that is
the element desired.

   Include files may be browsed by selecting their inclusion
declarations (#include ...) within a source file.  Include files
delimited by double quotes are searched for in the following places:
first, the directory of the current source file, then the directories
listed in the variable C++-INCLUDE-DIRS, and then in any directories
included in the current environment.

   Include files delimited by angle brackets are searched for in the
following places:  first, the directories listed in the variable
C++-INCLUDE-DIRS, then the directories listed in the variable
C++-CPP-INCLUDE-DIRS, and then in any directories included in the
current environment.  The variable C++-CPP-INCLUDE-DIRS should hold a
list of the standard directories searched by your C++ pre-processor.
Each directory entry must end with a directory separator.  On UNIX
systems, this is the '/' character.


File: oo-browser.info,  Node: C++ Settings,  Prev: C++ Element Selection,  Up: C++ Specifics

C++ Settings
------------

   By default, `class', `struct' and `union' definitions all constitute
class definitions to the C++ OO-Browser.  If you prefer some other
criteria, you will need to modify the definition of C++-CLASS-KEYWORD
in `br-c++.el'.

   If you find that the browser is not scanning some of your C++ source
files, you may be using file suffixes which it does not recognize.
Examine the value of C++-SRC-FILE-REGEXP and add any special file
suffixes you use to it.


File: oo-browser.info,  Node: CLOS Specifics,  Next: Eiffel Specifics,  Prev: C++ Specifics,  Up: Languages

CLOS Specifics
==============

* Menu:

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


File: oo-browser.info,  Node: CLOS Method Handling,  Next: CLOS Settings,  Prev: CLOS Specifics,  Up: CLOS Specifics

Method Handling
---------------

   In CLOS, methods may have typed parameters of the form,
`(<parameter-name> <class>)'; these are called "specialized
parameters".  Each such parameter defines the method within `<class>'.
Thus, a single method definition can generate methods associated with
many classes.  The OO-Browser lets you navigate to a method definition
from any of the classes for which it is defined, since a method is
included as an element of each of its constituent classes.

   CLOS permits compile-time computation of the `<class>' of a
specialized parameter, through use of the expression, `(eql <form>)'.
Since the OO-Browser cannot perform this computation, it treats such a
parameter as non-specialized.

   Methods may also contain non-specialized parameters of the form,
`<parameter-name>'.  The type of each such parameter defaults to the
default root class `t' in CLOS.  But a method is only included in the
class `t' by the OO-Browser if none of its parameters are specialized.
Otherwise, methods with more specific types which happened to include
one or more non-specialized parameters would appear to not have a more
specific type than `t'.


File: oo-browser.info,  Node: CLOS Settings,  Prev: CLOS Method Handling,  Up: CLOS Specifics

CLOS Settings
-------------

   The OO-Browser automatically works with CLOS class and method
definitions.  But Lisp contains many other standard object types such as
functions, macros and variables which you may wish to browse.  These are
handled through a configuration variable as explained below.

   The CLOS-ELEMENT-TYPE-ALIST variable determines the Lisp definition
constructs that the browser looks for and the associated default class
under which instances of each construct type are grouped.  Each element
in the association list is a cons cell whose first part is the function
name string that defines an instance of a particular type, e.g.
`"defun"'.

   The second part is a default class name, a string, under which to
assign each instance of the type, e.g. `"function"'.  The OO-Browser
always displays default class names with square brackets around them,
e.g. `[function]', to distinguish them from classes defined within the
Environment.

Here is the default CLOS-ELEMENT-TYPE-ALIST setting:

       '(("defconstant"  . "constant")
         ("defconst"     . "constant")
         ("defun"        . "function")
         ("defgeneric"   . "generic")
         ("defmacro"     . "macro")
         ("defpackage"   . "package")
         ("defparameter" . "parameter")
         ("defsetf"      . "setfunction")
         ("defstruct"    . "structure")
         ("deftype"      . "type")
         ("defvar"       . "variable")
         ("fset"         . "function"))

   The CLOS-DEF-FORM-WITH-ARGS-REGEXP is a regular expression which
includes a subset of the definition symbol names from
CLOS-ELEMENT-TYPE-ALIST, namely those which require an argument list to
uniquely distinguish them from other elements, e.g. functions.


File: oo-browser.info,  Node: Eiffel Specifics,  Next: Java Specifics,  Prev: CLOS Specifics,  Up: Languages

Eiffel Specifics
================

   Eiffel support has now been updated to Eiffel version 3, to the best
of our knowledge.  If you find any problems, please report them to
<oo-browser@hub.ucsb.edu> (this is a public mailing list).

* Menu:

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


File: oo-browser.info,  Node: Eiffel Listings,  Next: Eiffel Element Selection,  Prev: Eiffel Specifics,  Up: Eiffel Specifics

Eiffel Listings
---------------

   Eiffel entities are categorized when shown within OO-Browser listing
buffers.  Classes are shown by name, without any prefix.  Features are
shown by name but are preceded by a special character that indicates
the kind of feature.  The following table describes each prefix.

`-'
     precedes regular routines;

`='
     precedes attributes;

`1'
     precedes once routines, which create shared objects;

`>'
     precedes deferred features, which are specified but not defined
     within this class;

`/'
     precedes external features, which are defined in a non-Eiffel
     language.


File: oo-browser.info,  Node: Eiffel Element Selection,  Next: Eiffel Settings,  Prev: Eiffel Listings,  Up: Eiffel Specifics

Source Code Element Selection
-----------------------------

   One can jump from an Eiffel element reference to its definition by
clicking the Action Key when within the reference.  Selection of a
feature name in an export clause displays the feature definition, even
if it is renamed several times within ancestors.  Parent classes may be
browsed in a similar manner by clicking on their names in an inheritance
or declaration clause.

   The following example of locating a renamed feature is taken from an
actual set of Eiffel library classes:

     User selects feature `subwindow' of `POPUP_MENU'
        inherited from `WINDOW' which renames `child' as `subwindow'
           inherited from `TWO_WAY_TREE' which renames `active' as `child'
              inherited from `TWO_WAY_LIST'
                 inherited from `LINKED_LIST' which defines `active'.

   The browser would display the feature `active' and explain to the
user that feature `subwindow' of class `POPUP_MENU' is inherited from
feature `active' of class `LINKED_LIST'.  Location of this sort of
feature definition would be incredibly tedious without programmatic
support.

   The algorithm used to locate features is dynamic, so if another class
were inserted into the inheritance structure given above, the feature
definition would still be located properly.


File: oo-browser.info,  Node: Eiffel Settings,  Prev: Eiffel Element Selection,  Up: Eiffel Specifics

Eiffel Settings
---------------

   Be sure that the 'inherit' and 'feature' clauses in your classes
begin in column 0; otherwise the browser parser will not work properly.
If you prefer some other indentation style, you will need to slightly
alter `(eif-get-parents-from-source)' in `br-eif.el'; specifically, the
lines that contain '^inherit' and '^feature'.

   Emacs has a feature called error parsing which lets one quickly jump
to the line of code that supposedly triggered an error.  (*Note
Compilation Errors: (emacs)Compilation, for information on error
parsing.)  Some object-oriented language compilers display the name of
the class and line number with each error message but do not include
the filename containing the class source code.  Emacs then has no way
of parsing the error message.  The browser class location facilities
enable one to perform error parsing across any set of classes in a
single Environment, given only this type of message.  Interactive
Software Engineering's Eiffel compiler is an example of a compiler that
produces this type of error.  The code for parsing these Eiffel error
messages is included in `eif-ise-err.el'.


File: oo-browser.info,  Node: Java Specifics,  Next: Objective-C Specifics,  Prev: Eiffel Specifics,  Up: Languages

Java Specifics
==============

   Java abstract method declarations, which specify method interfaces
but no implementation, appear in class feature listings.  The method
name is preceded by the `"> "' string to identify the method as an
abstract (deferred) method.  Abstract methods may be treated like any
other methods within the browser.  Since there is no definition for
such a method within the class in which it is listed, its declaration
will be shown instead, when requested.

   Native methods are like abstract methods in that only their
interfaces are specified in Java.  Unlike abstract methods, their
method bodies are defined in external languages such as C to allow for
machine-specific dependencies.  Native methods are listed in the
browser prefixed by the `"/ "' string, indicating that they are divided
between Java and another language.

   Methods associated with creating and destroying objects are preceded
by the `"+ "' string in listing buffers.  All other method listing
entries are preceded by the `"- "' string.

   Java interface specifications, which specify protocols to which
classes must conform, are treated just like class definitions in browser
listings. All the methods of such interfaces are abstract, however.


File: oo-browser.info,  Node: Objective-C Specifics,  Prev: Java Specifics,  Up: Languages

Objective-C Specifics
=====================

   *Note C Specifics::, for details on C-specific support within
Objective-C Environments.

   The OO-Browser supports browsing Objective-C classes, methods,
categories and formal protocols.  Earlier sections of this manual
explain how to browse these entities.  This section documents
Objective-C language specifics, including variable settings.

   Objective-C entities are categorized when shown within OO-Browser
listing buffers.  Classes are shown by name, without any prefix.
Methods are shown by name but are preceded by a special character that
indicates the kind of method.  The following table describes each
prefix.

`-'
     precedes instance methods;

`+'
     precedes class (factory) methods that affect the factory object
     for the class.

* Menu:

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


File: oo-browser.info,  Node: Objective-C Categories,  Next: Objective-C Protocols,  Prev: Objective-C Specifics,  Up: Objective-C Specifics

Objective-C Categories
----------------------

   An "Objective-C category" is an internal class grouping that
specifies and implements a set of related class features.  The
aggregation of all of the categories defined by a class and its
ancestors represents the complete class definition.

   The OO-Browser can list and browse the source for: the categories of
a class, all class categories in an Environment, and the classes which
implement a category.  *Note Browsing Categories::, for details.


File: oo-browser.info,  Node: Objective-C Protocols,  Next: Objective-C Element Selection,  Prev: Objective-C Categories,  Up: Objective-C Specifics

Objective-C Protocols
---------------------

   An "Objective-C protocol" is an interface specification to which a
class may conform.  The protocol includes a set of method signatures
which any conforming class must implement.  One protocol may inherit
from a list of other protocols, and thus expand the set of methods which
a conforming class must implement.  The OO-Browser can list and browse
the source for: the protocols to which a class conforms, all protocols
in an Environment, and the implementors of a protocol.  *Note Browsing
Protocols::, for details.


File: oo-browser.info,  Node: Objective-C Element Selection,  Next: Objective-C Settings,  Prev: Objective-C Protocols,  Up: Objective-C Specifics

Source Code Element Selection
-----------------------------

   One can jump from an Objective-C declaration to its definition by
clicking the Action Key when within the declaration.  Most importantly,
once a class header file is displayed, simply click on a method
declaration to see its corresponding definition.  If the method is
inherited from another class, a message at the bottom of the frame will
describe which class the method is defined in once the browser displays
the method definition.

   Parent classes may be browsed in a similar manner by clicking on
their names in an inheritance or declaration clause.  It is therefore
important to click on the method name part of a declaration when that is
the element desired.

   Include files may be browsed by selecting their inclusion
declarations (#import ...) within a source file.  Include files
delimited by double quotes are searched for in the following places:
first, the directory of the current source file, then the directories
listed in the variable OBJC-INCLUDE-DIRS, and then in any directories
included in the current environment.

   Include files delimited by angle brackets are searched for in the
following places:  first, the directories listed in the variable
OBJC-INCLUDE-DIRS, then the directories listed in the variable
OBJC-CPP-INCLUDE-DIRS, and then in any directories included in the
current environment.  The variable OBJC-CPP-INCLUDE-DIRS should hold a
list of the standard directories searched by your Objective-C
pre-processor.  Each directory entry must end with a directory
separator.  On UNIX systems, this is the '/' character.


File: oo-browser.info,  Node: Objective-C Settings,  Next: Python Specifics,  Prev: Objective-C Element Selection,  Up: Objective-C Specifics

Objective-C Settings
--------------------

   By default, the `@interface' keyword indicates a class definition to
the Objective-C OO-Browser.  If you prefer some other criteria, you
will need to modify the definition of OBJC-CLASS-KEYWORD in
`br-objc.el'.

   If you find that the browser is not scanning some of your Objective-C
source files, you may be using file suffixes which it does not
recognize.  Examine the value of OBJC-SRC-FILE-REGEXP and add any
special file suffixes you use to it.


File: oo-browser.info,  Node: Python Specifics,  Next: Python Module Lookup,  Prev: Objective-C Settings,  Up: Languages

Python Specifics
================

   The OO-Browser supports browsing Python classes, methods, and
documentation strings for both. The class info key 'i' is used to
display class or method documentation string, if that is available.

   Python methods appear in class feature listings.  The method name is
preceded by the `"- "' string.

   Global functions are grouped under the imaginary class `[functions]'
to distinguish them from classes or class methods.

   Known bugs: nested classes are not recognized.  As browsing is based
on analyzing the source code, run-time modifications are lost.

* Menu:

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


File: oo-browser.info,  Node: Python Module Lookup,  Next: Python Settings,  Prev: Python Specifics,  Up: Python Specifics

Python Module Lookup
--------------------

   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.

   Clicking on a module name in an import statement using the Action Key
will open the specified module, if it is found in the search path.


File: oo-browser.info,  Node: Python Settings,  Prev: Python Module Lookup,  Up: Python Specifics

Python Settings
---------------

   When a module name in an import statement is clicked using the
Action Key, OO-Browser tries to open the module.py file.  By default,
it looks for the module file in the environment directories, and from
the path `/usr/local/lib/python'. If you have installed Python libraries
elsewhere, or wish to include other modules in the search path, you will
need to modify the definition of PYTHON-IMPORT-DIRS in
`br-python-ft.el'.


File: oo-browser.info,  Node: Features,  Next: Commands,  Prev: Languages,  Up: Top

OO-Browser Features
*******************

   * Support for Eiffel, C++, Objective-C, Smalltalk, Java and Common
     Lisp and its Object System (CLOS) is included.  Additionally,
     support for browsing large amounts of material in Info format by
     node name (a popular online documentation format with cross
     references and hierarchical structure) is include.  All languages
     provide class browsing via either a textual or a graphical
     interface.

   * Method browsing is supported for C++, Objective-C, Eiffel and CLOS.
     CLOS supports browsing all elements defined with (def* constructs.
     In-source feature browsing is also supported for all of these
     languages.  One simply selects a feature name to jump to its
     corresponding source.  Method name overloading in C++ and
     inherited feature renaming in Eiffel are fully supported.

   * C code browsing is supported for C++, Objective-C and C source
     code.

   * Objective-C category and formal protocol browsing are supported.

   * C++ parameterized template classes and methods are supported.

   * Building Environments is fast compared to many other tools and
     browser startup once an Environment has been built is very fast.
     Response times on workstations are excellent; for example, in one
     test case, less than two real seconds were required to display a
     set of complex inheritance graphs involving over 400 classes.

   * Class inheritance networks may be displayed.  Either a single
     inheritance level (parents or children) or the entire inheritance
     network (ancestors or descendants) for a set of classes may be
     shown.

   * Multiple inheritance support is built-in, where applicable.

   * The user need not know the location of class source; the browser
     will display or edit a class source based solely upon its class
     name.

   * Immediate switching among languages is allowed.  One can switch
     from Eiffel browsing to C++ browsing in an instant, if so desired.
     Or simply run two browsers side by side.

   * Class files may be added, replaced or deleted one at a time or as a
     group by specifying a root directory below which all class files
     are found, including those in subdirectories.

   * The browser uses class source code only, hence no compiler is
     necessary for proper browser operation.

   * Library (stable) and System (in development) classes may be
     maintained and listed separately or together.  Any number of
     Libraries and Systems may be combined for listing in a single
     Environment.  There are no fixed limits on the number of classes
     per Environment nor on the number of Environments that may be
     browsed.

   * The number of listing windows is limited only by the frame width
     and the width setting used for listing windows.

   * Statistics on classes and Environments may be displayed.

   * Language-specific class information may be shown.  Presently this
     feature is supported only for Eiffel.  A listing of class parents,
     attributes, routines and best guess (highly accurate) list of
     routine calls may be displayed.  Outputs from the Eiffel 'short'
     and 'flat' commands may also be shown.

   * Machine-independent mouse support is included along with an
     extremely intuitive point and click interface.  The OO-Browser is
     pre-configured for use with the X window system, NEXTSTEP, Sunview
     or Apollo's DM window system under InfoDock, Emacs V19, XEmacs,
     Epoch, and Emacs V18.

   * Popup and pulldown command menus are available under InfoDock,
     Emacs V19 and XEmacs.

   * All browser outputs are text which may be edited as desired or
     saved to files.

   * A single key provides ASCII ordering of class names, ascending or
     descending, including those from inheritance trees.  Classes may be
     easily located by matching a regular expression or string to the
     set of class names in an Environment, with repeated searches
     incrementally narrowing the selected set.

   * Browser functions may be used standalone within the editor without
     using the multi-windowed browser interface.  One useful example is
     to point to a class name such as a parent class in the text of
     another class and have the parent's source appear in an editable
     fashion.  An alternative editor and viewer may be selected to
     adapt the browser to personal taste.

   * The browser is adaptable to any class-based object-oriented
     language.  It works best with languages that focus on static class
     creation such as Eiffel and C++.  Those that use dynamic (runtime)
     class creation such as CLOS must be interfaced to the browser so
     that classes created at runtime are added to the browser's
     Environment.

   * The OO-Browser is integrated with the powerful GNU Emacs editor;
     it works on any UNIX system display supported by Emacs.  Most
     browser commands may be executed by direct selection, providing a
     very natural interface.

   * All source code, over 400 kilobytes, is included and is heavily
     documented.

