The EditBus maintains a list of objects that have requested to receive messages. When a message is sent using this class, all registered components receive it in turn.
Plugins register with the EditBus to receive messages reflecting changes in the application's state, including changes in buffers, views and editing panes, changes in the set of properties maintained by the application, and the closing of the application. A full list of message classes used by the EditBus are summarized beginning with the section called "Class EBMessage".
Classes for objects that subscribe to the EditBus must implement the EBComponent interface, which defines the single method handleMessage(). A View, for example, can receive and handle EditBus messages because it also implements EBComponent.
Any class in a plugin can receive messages by implementing the EBComponent interface. A "plugin core class" that extends the EBPlugin abstract class (and whose name ends with "Plugin" for identification purposes) will automatically be added to the EditBus during jEdit's startup routine. Any other class - for example, a docking window component that needs to receive notification of buffer changes - must perform its own registration by calling EditBus.addToBus(this) during its initialization. If this class if derived from JComponent, a convenient place to register would be in an implementation of the JComponent method addNotify().
Every plugin class that uses the EditBus for receiving messages must implement this interface.
The EBComponent interface contains a single method that an implementing class (including any class derived from EBPlugin) must provide:
public void handleMessage( | EBMessage | message) ; |
The parameter's type, EBMessage, is another abstract class which establishes the core elements of any message that is published to the EditBus. It has two attributes: an EBComponent that is the source of the message (the source will be null in some cases), and a boolean data member, vetoed. This flag indicates whether a prior recipient of the message has determined that the message has been handled and need not be passed on to other subscribers. The flag is set by a call to the veto() method of the EBMessage. Some message classes, however, are configured so that they cannot be vetoed, to ensure they are received by all subscribers.
Message classes extending EBMessage typically add other data members and methods to provide subscribers with whatever is needed to handle the message appropriately. Descriptions of specific message classes can be found in Chapter 21.
The handleMessage() method must specify the type of responses the plugin will have for various subclasses of the EBMessage class. Typically this is done with one or more if blocks that test whether the message is an instance of a derived message class in which the plugin has an interest, as in the following example:
if(msg instanceof BufferUpdate) { // a buffer's state has changed! } else if(msg instanceof ViewUpdate) { // a view's state has changed! } // ... and so on |
Note that any object, whether or not derived from EBComponent, can send a message to the EditBus by calling the static method EditBus.send(). This method takes a single parameter, an EBMessage object that is the message being sent. Most plugins, however, will only concern themselves with receiving, not sending, messages.