The EditBus is a message passing system. Any number of components can be connected to the bus. Each component can send messages, as well as receive them.
jEdit itself sends various messages to the bus - buffers being opened and closed, and so on. Plugins can also define their own message types to communicate with each other. The jEdit core only includes a small set of messages that are meant to be sent by jEdit itself only; the EditBus plugin includes a wider range of messages that can be used for inter-plugin communication. Get the EditBus plugin from http://jedit.standmed.com.
Each message type is a subclass of EBMessage. All messages included with jEdit live in the org.gjt.sp.jedit.msg package. Because messages are full-fledged objects, they can carry any type of information.
public interface EBComponent { public void handleMessage(EBMessage msg); } |
Each component on the bus must implement this interface. When a message is sent to the bus, the handleMessage() method of each component is called in turn. Typically, this method will check if the message is of a known type using instanceof, and take appropriate action.
import org.gjt.sp.jedit.EBComponent; import org.gjt.sp.jedit.EditBus; |
public static void addToBus
(EBComponent comp);
This method adds the specified component to the bus. It will now receive all messages sent to the bus. Note that to avoid memory leaks, you must remember to remove components from the bus when they are no longer needed.
import org.gjt.sp.jedit.EBComponent; import org.gjt.sp.jedit.EditBus; |
public static void removeFromBus
(EBComponent comp);
This method removes the specified component from the bus, hence it will no longer receive any messages.
public abstract class EBPlugin extends EditPlugin implements EBComponent { public void handleMessage(EBMessage msg); } |
The EBPlugin class is identical to EditPlugin, except that the plugin is automatically added to the bus. If your plugin needs to receive messages, you can subclass EBPlugin.
public abstract class EBMessage { public EBMessage(EBComponent source); public EBComponent getSource(); public void veto(); public boolean isVetoed(); } |
The org.gjt.sp.jedit.EBMessage class is the common superclass of all EditBus messages. Most methods in this class should be self-explanatory, except for the vetoing methods. Here is how it works; once you veto() a message, it will not propogate further along the bus. The isVetoed() method returns if the method has already been vetoed.
The vetoing system is useful for messages that request some action to be taken; if some component on the bus can perform the action, it calls veto(). The sender will then check the return value of isVetoed() and display an error message if it is false (meaning no-one called veto()).
import org.gjt.sp.jedit.EBMessage; import org.gjt.sp.jedit.EditBus; |
public static void send
(EBMessage msg);
This method sends the specified message to the bus (ie, it calls the handleMessage() method of each component). Plugins should never send jEdit core messages (BufferUpdate, ViewUpdate, etc) directly; only send messages intended to be sent from plugins, for example the messages included in the EditBus plugin.
This message is sent by jEdit when a buffer-related update occurs. The getBuffer() method of the BufferUpdate class returns the buffer involved. The getWhat() method returns one of the following:
BufferUpdate.CREATED - a new buffer has been created
BufferUpdate.LOADED - a buffer has been loaded from disk
BufferUpdate.DIRTY_CHANGED - the "dirty" flag has changed; either the buffer has been saved, or some changes have been made
BufferUpdate.MARKERS_CHANGED - a marker has been added or removed
BufferUpdate.MODE_CHANGED - the buffer's edit mode has changed
BufferUpdate.SAVING - a buffer is about to be saved
BufferUpdate.CLOSED - a buffer has been closed
This message is sent by jEdit just before it exits. Hence, it is similar to the stop() method of a plugin, but it is not limited to plugins.
This message is sent by jEdit after it has finished starting, but before the initial view is created. Hence, it is similar to the start() method of a plugin, but it is not limited to plugins.
This message is sent by jEdit when an edit pane-related update occurs. The getEditPane() method of the EditPaneUpdate class returns the edit pane involved. The getWhat() method returns one of the following:
EditPaneUpdate.CREATED - a new edit pane has been created (ie, a view has been split)
EditPaneUpdate.DESTROYED - an edit pane has been destroyed (ie, a view has been unsplit)
EditPaneUpdate.BUFFER_CHANGED - an edit pane is now editing a different buffer
This message is sent by jEdit when the list of available macros changes. Its main use is to keep the Macros menu up to date; plugins will almost never need to handle this message.
This message is sent by jEdit after the Utilities>Global Options dialog box is closed; your plugin should reload any editable settings when it receives this message.
This message is sent by jEdit after a register is added, removed, or changed.
This message is sent by jEdit when search and replace flags (ignore case, regular expression, multiple file search) are changed. Its main use is to keep view's search bars up to date; plugins will almost never need to handle this message.
This message is sent by jEdit when a view-related update occurs. The getView() method of the ViewUpdate class returns the view involved. The getWhat() method returns one of the following:
ViewUpdate.CREATED - a new view has been created
ViewUpdate.CLOSED - a view has been closed