<!-- jEdit 3.1 Plugin Guide, (C) 2001 John Gellene -->

<!-- jEdit buffer-local properties:                           -->
<!-- :indentSize=1:tabSize=2:noTabs=true:maxLineLen=72:       -->

<chapter id="api-message"><title>EditBus Classes</title>

<para>
    This section describes the <classname>EditBus</classname> class
    itself, as well as the abstract <classname>EBMessage</classname>
    class and all classes that derive from it.
    See <xref linkend="host-display-manager" /> for an overview
    of how the EditBus works.
</para>

<sect1 id="class-editbus"><title>Class EditBus</title>

  <para>
    This class provides a messaging system for all components that implement
    the	<classname>EBComponent</classname> interface, including
    <classname>View</classname> and <classname>EBPlugin</classname>
    objects.
  </para>

<itemizedlist>

  <listitem>
    <funcsynopsis>
      <funcprototype>
        <funcdef>public static void <function>addToBus</function></funcdef>
        <paramdef>EBComponent <parameter>component</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
  </listitem>

  <listitem>
    <funcsynopsis>
      <funcprototype>
        <funcdef>public static void <function>removeFromBus</function></funcdef>
        <paramdef>EBComponent <parameter>component</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
	<para>
		Adds or removes a subscribing component.
	</para>
  </listitem>

  <listitem>
    <funcsynopsis>
      <funcprototype>
        <funcdef>public EBComponent[] <function>getComponents</function></funcdef>
        <void/>
      </funcprototype>
    </funcsynopsis>
	<para>
		Returns an array of all components connected to the EditBus.
	</para>
  </listitem>

  <listitem>
    <funcsynopsis>
      <funcprototype>
        <funcdef>public void <function>send</function></funcdef>
        <paramdef>EBMessage <parameter>message</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
    <para>
        Send the specified message to all subscribers on the EditBus.
    </para>
  </listitem>

</itemizedlist>

</sect1>

<sect1 id="class-ebcomponent"><title>Interface EBComponent</title>
<para>
  This interface is required for any class that subscribes to messages
  published on the EditBus. It contains a single method.
</para>

<itemizedlist>
  <listitem>
    <funcsynopsis>
      <funcprototype>
        <funcdef>public void <function>handleMessage</function></funcdef>
        <paramdef>EBMessage <parameter>message</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
  </listitem>
</itemizedlist>

</sect1>

<sect1 id="class-ebmessage"><title>Class EBMessage</title>
<para>
    This abstract class defines a message that can be sent on the EditBus to
    subscribing components.  It contains two attributes that can be obtained
    with the following methods:
</para>

<itemizedlist>
  <listitem>
    <funcsynopsis>
      <funcprototype>
        <funcdef>public EBComponent <function>getSource</function></funcdef>
        <void/>
      </funcprototype>
    </funcsynopsis>
  </listitem>

  <listitem>
    <funcsynopsis>
      <funcprototype>
        <funcdef>public boolean <function>isVetoed</function></funcdef>
        <void/>
      </funcprototype>
    </funcsynopsis>
  </listitem>

  <listitem>
    <funcsynopsis>
      <funcprototype>
        <funcdef>public void <function>veto</function></funcdef>
        <void/>
      </funcprototype>
    </funcsynopsis>
    <para>
        This sets the <parameter>vetoed</parameter> state to
        <constant>true</constant>, which terminates circulation of the
        message to subscribers on the EditBus.  To prevent a message from being
        vetoed, the message object must be derived from the abstract class
        <classname>EBMessage.NonVetoable</classname>.  An object of this class
        will throw an <classname>InternalError</classname> if the
        <function>veto()</function> method is called on it.
    </para>
  </listitem>

</itemizedlist>

<para>
    A summary of classes derived from <classname>EBMessage</classname>
    can be found in the following sections.
</para>

</sect1>

<sect1 id="class-bufferupdate"><title>Class BufferUpdate</title>
<para>
    This message is sent when the status of a buffer changes.  It may
    not be vetoed by a subscriber, so that all subscribers are
    assured of receiving it regardless of an individual subscriber's
    response.
</para>

<itemizedlist>

  <listitem>
    <funcsynopsis>
      <funcprototype>
        <funcdef>public Buffer <function>getBuffer</function></funcdef>
        <void/>
      </funcprototype>
    </funcsynopsis>
  </listitem>

  <listitem>
    <funcsynopsis>
      <funcprototype>
        <funcdef>public View <function>getView</function></funcdef>
        <void/>
      </funcprototype>
    </funcsynopsis>
    <para>
      This may be <literal>null</literal> with some message types.
    </para>
  </listitem>

  <listitem>
    <funcsynopsis>
      <funcprototype>
        <funcdef>public Object <function>getWhat</function></funcdef>
        <void/>
      </funcprototype>
    </funcsynopsis>
    <para>
      Returns one of the following constants defined in the
      <classname>BufferUpdate</classname> class:
    </para>
    <itemizedlist>
      <listitem><para><varname>CREATED</varname></para></listitem>
      <listitem><para><varname>LOAD_STARTED</varname></para></listitem>
      <listitem><para><varname>DIRTY_CHANGED</varname></para></listitem>
      <listitem><para><varname>MARKERS_CHANGED</varname></para></listitem>
      <listitem><para><varname>MODE_CHANGED</varname></para></listitem>
      <listitem><para><varname>ENCODING_CHANGED</varname></para></listitem>
      <listitem><para><varname>SAVING</varname></para></listitem>
    </itemizedlist>
  </listitem>

</itemizedlist>

</sect1>

<sect1 id="class-editorexiting"><title>Class EditorExiting</title>

<para>
  This message signifies that the host application is about to exit.
  The message has no parameters and may not be vetoed.
</para>

</sect1>

<sect1 id="class-editorexitrequested"><title>Class EditorExitRequested</title>

<para>
  This message signifies that a request has been made for the host application
  to exit. The request is subject to cancellation in response to a request to
  write a modified buffer to storage. It may not be vetoed.
</para>

<itemizedlist>

  <listitem>
    <funcsynopsis>
      <funcprototype>
        <funcdef>public View <function>getView</function></funcdef>
        <void/>
      </funcprototype>
    </funcsynopsis>
  </listitem>

</itemizedlist>

</sect1>

<sect1 id="class-editorstarted"><title>Class EditorStarted</title>

<para>
  This message signifies that the host application has started. The
  message is sent before any views are created. The message has no
  parameters and it may not be vetoed.
</para>

</sect1>

<sect1 id="class-editpaneupdate"><title>Class EditPaneUpdate</title>
<para>
    This message is sent when the status of a edit pane changes.  It may
    not be vetoed.
</para>

<itemizedlist>

  <listitem>
    <funcsynopsis>
      <funcprototype>
        <funcdef>public EditPane <function>getEditPane</function></funcdef>
        <void/>
      </funcprototype>
    </funcsynopsis>
  </listitem>

  <listitem>
    <funcsynopsis>
      <funcprototype>
        <funcdef>public Object <function>getWhat</function></funcdef>
        <void/>
      </funcprototype>
    </funcsynopsis>
    <para>
      Returns one of the following constants defined in the
      <classname>EditPaneUpdate</classname> class:
    </para>
    <itemizedlist>
      <listitem><para><varname>CREATED</varname></para></listitem>
      <listitem><para><varname>DESTROYED</varname></para></listitem>
      <listitem><para><varname>BUFFER_CHANGED</varname> - a change in the buffer
        displayed in the edit pane</para></listitem>
    </itemizedlist>
  </listitem>

</itemizedlist>


</sect1>

<sect1 id="class-macroschanged"><title>Class MacrosChanged</title>

<para>
  This message signifies that the list of available macros have changed.
  The message has no parameters and may not be vetoed.
</para>

</sect1>

<sect1 id="class-propertieschanged"><title>Class PropertiesChanged</title>

<para>
  This message is sent when configuration settings have been changed through
  any of the option panes in the options dialog. The message has no
  parameters and may be vetoed.
</para>

</sect1>

<sect1 id="class-searchsettingschanged">
<title>Class SearchSettingsChanged</title>

<para>
  This message is sent when settings in the <quote>Search and
  Replace</quote> dialog have changed. The message has no
  parameters and may be vetoed.
</para>

</sect1>

<sect1 id="class-vfsupdate"><title>Class VFSUpdate</title>
<para>
    This message is sent when the status of a file or directory changes.
    This allows subscribers that display or operate upon files an
    opportunity to adjust their state.  This message may not be vetoed.
</para>

<itemizedlist>

  <listitem>
    <funcsynopsis>
      <funcprototype>
        <funcdef>public String <function>getPath</function></funcdef>
        <void/>
      </funcprototype>
    </funcsynopsis>
  </listitem>

</itemizedlist>


</sect1>

<sect1 id="class-viewupdate"><title>Class ViewUpdate</title>
<para>
    This message is sent when the status of a view changes. It may
    not be vetoed.
</para>

<itemizedlist>

  <listitem>
    <funcsynopsis>
      <funcprototype>
        <funcdef>public View <function>getView</function></funcdef>
        <void/>
      </funcprototype>
    </funcsynopsis>
  </listitem>

  <listitem>
    <funcsynopsis>
      <funcprototype>
        <funcdef>public Object <function>getWhat</function></funcdef>
        <void/>
      </funcprototype>
    </funcsynopsis>
    <para>
      Returns one of the following constants defined in the
      <classname>ViewUpdate</classname> class:
    </para>
    <itemizedlist>
      <listitem><para><varname>CREATED</varname></para></listitem>
      <listitem><para><varname>CLOSED</varname></para></listitem>
    </itemizedlist>
  </listitem>

</itemizedlist>

</sect1>

</chapter>