last revised: 10/04/2002

This files gives some instructions on extending, building and
deploying the bluej source editor.

NOTE: This separate editor release needs to be compiled with the
bluej.jar file from BlueJ version 1.1.2 or higher.  It will not
 work with earlier versions.  It is recommended that you compile
 it using the matching BlueJ version eg. editor source release 
 1.2.0 should be compiled against BlueJ version 1.2.0.

At the moment this editor does not operate as a stand-alone
editor, it needs a minimal number of support classes from BlueJ.  It 
could however be fairly easily converted to a standalone editor if 
you want to.  (It was originally designed to operate as both 
integrated and standalone).


INTEGRATION WITH BLUEJ

The bluej editor (sometimes referred to as "Moe") has a fairly loose
coupling to the main part of the environment.  It is designed so that
alternative editor implementations can be slotted in to BlueJ without
affecting BlueJ itself.  The main BlueJ code communicates through
three interfaces with the source editing framework.  These interfaces
are bluej.editor.EditorManager, bluej.editor.Editor and 
bluej.editor.EditorWatcher. These should not be changed (much) - see 
below.

EditorManager
  EditorManager provides editor management, creation and removal.  In
  the moe editor implementation this abstract class is extended by the
  MoeEditorManager class.

Editor
  The Editor interface is the public interface to editor functionality
  that BlueJ uses to communicate with the editor.

EditorWatcher
  EditorWatcher interface is implemented by classes in BlueJ that wish
  to be notified of editor related events.

It is possible to customise the existing editor or substitute your own 
editor implementation that communicates to BlueJ using these three 
interfaces.


CUSTOMISING THE EDITOR

To customise the existing editor, all your work will be inside the 
"moe" subdirectory. This directory provides the current editor 
implementation.


REPLACING THE EDITOR

You can completely replace the BlueJ editor. To do this, create your
own subdirectory with your editor implementation. Your editor must
provide implementations for the "EditorManager" and "Editor" 
interfaces, and it should call the "EditorWatcher" methods to 
communicate with the BlueJ system. You will need to change one line
in the "EditorManager" class (line 25) to create your own editor
instead of Moe (the default editor).


BUILDING THE EDITOR

You can build by hand by running javac on the editor source files. 
Alternatively, you may use "ant" to build the editor.

Included in the distribution is a build file (build.xml) for building
and deploying the editor using the Ant build tool.  Ant is a build
tool similar to "make" that is implemented in Java.  

This script was built for use with ant version 1.2.  It has not been
tested on earlier versions.  For information on the Ant tool see 
http://jakarta.apache.org/ant/index.html. 

The build.xml file has only a few simple targets: prepare, compile, 
dist and clean.  (Compile is the default target)

Before using ant, you need to change the "bluej_home" property in 
the build.xml file for your system.

Ant commands (assuming correct installation of ant) act in a similar 
way to make:

ant
    calls default target,will compile editor classes into a "build" 
    directory.

ant dist
    compiles and creates an editor.jar in a "dist" sub directory.

ant clean
    removes "build" directory and class files.

The following sections describe the build process by hand.

Compilation
    The bluej.jar file found in BlueJ's lib directory needs to be in 
    your classpath for compilation.

Deployment
    The editor class files need to be archived into a jar file called 
    editor.jar and placed in the BlueJ lib directory 
    (BLUEJ_INSTALL_DIR)/lib, replacing the existing editor.jar.


CONFIGURATION

The moe editor implementation uses several Java properties file in 
the BlueJ lib directory. These are moe.defs, bluej.defs and 
<language>/labels.

moe.defs contains some implementation specific properties. bluej.defs
holds some general editor properties. The "labels" files hold language
specific user interface texts.


EDITOR ENHANCEMENTS

We welcome any enhancements that you may make to the editor or
alternative implementations you may wish to share.  There are no
guarantees that any enhancements you provide will be used in the
official release.  One of the challenges we face with a learning tool
such as BlueJ is to avoid "feature creep" that may provide extra
functionality but at the cost of simplicity and ease of use.


QUESTIONS

If you have questions about the existing editor implementation, bluej
editor integration or other editor issues, contact:

Bruce Quig
bluej-support@bluej.org
