<!-- jEdit 3.2 Macro Guide, (C) 2001 John Gellene                -->
<!-- Thu Jun 21 23:49:14 EDT 2001 @200 /Internet Time/           -->
<!--                                                             -->
<!-- jEdit buffer-local properties:                              -->
<!-- :indentSize=1:noTabs=yes:maxLineLen=72:tabSize=2:           -->
<!--                                                             -->
<!-- This file contains the jEdit API Quick Reference            -->


<chapter id="api-macro"><title>General jEdit Classes</title>

<sect1 id="class-jedit"><title>Class jEdit</title>

<para>
    This is the main class of the application. All the methods in this
    class are static methods, so
    they are called with the following syntax, from both macros and
    plugins:
</para>
<programlisting>jEdit.<replaceable>method</replaceable>(<replaceable>parameters</replaceable>)
</programlisting>

<para>
    Here are a few key methods:
</para>

<itemizedlist>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public static Buffer <function>openFile</function></funcdef>
  <paramdef>View <parameter>view</parameter></paramdef>
  <paramdef>String <parameter>path</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
<para>
    Opens the file named <varname>path</varname> in the given
    <classname>View</classname>. To open a file in the current view, use the
    predefined variable <varname>view</varname> for the first parameter.
</para>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public static Buffer <function>newFile</function></funcdef>
  <paramdef>View <parameter>view</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
<para>
    This creates a new buffer captioned
    <guimenu>Untitled-&lt;n&gt;</guimenu>in the given
    <classname>View</classname>.
</para>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public static boolean <function>closeBuffer</function></funcdef>
  <paramdef>View  <parameter>view</parameter></paramdef>
  <paramdef>Buffer  <parameter>buffer</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
<para>
    Closes the buffer named <varname>buffer</varname> in the view named
    <varname>view</varname>. The user will be prompted to save the buffer
    before closing if there are unsaved changes.
</para>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public static void <function>saveAllBuffers</function></funcdef>
  <paramdef>View <parameter>view</parameter></paramdef>
  <paramdef>boolean <parameter>confirm</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
<para>
    This saves all open buffers with unsaved changes in the given
    <classname>View</classname>. The parameter <parameter>confirm</parameter>
    determines whether jEdit initially asks for confirmation of the save
    operation.
</para>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public static boolean <function>closeAllBuffers</function></funcdef>
  <paramdef>View <parameter>view</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
<para>
    Closes all buffers in the given <classname>View</classname>. A dialog
    window will be displayed for any buffers with unsaved changes to
    obtain user instructions.
</para>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public static void <function>exit</function></funcdef>
  <paramdef>View <parameter>view</parameter></paramdef>
  <paramdef>boolean <parameter>reallyExit</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
<para>
    This method causes jEdit to exit. If <parameter>reallyExit</parameter> is
    false and jEdit is running in background mode, the application will simply
    close all  buffers and views and remain in background mode.
</para>
</listitem>


<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public static String <function>getProperty</function></funcdef>
  <paramdef>String <parameter>name</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
<para>
    Returns the value of the property named by <varname>name</varname>, or
    <constant>null</constant> if the property is undefined.
</para>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public static boolean <function>getBooleanProperty</function></funcdef>
  <paramdef>String <parameter>name</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
<para>
    Returns a <type>boolean</type> value of <constant>true</constant> or
    <constant>false</constant> for the property named by <varname>name</varname> by
    examining the contents of the property; returns
    <constant>false</constant> if the property cannot be found.
</para>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public static void <function>setProperty</function></funcdef>
  <paramdef>String <parameter>name</parameter></paramdef>
  <paramdef>String <parameter>property</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
<para>
    This method sets the property named by <varname>name</varname> with the value
    <varname>property</varname>. An existing property is overwritten.
</para>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public static void <function>setBooleanProperty</function></funcdef>
  <paramdef>String <parameter>name</parameter></paramdef>
  <paramdef>boolean <parameter>value</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
<para>
    This method sets the property named by <varname>name</varname> to
    <varname>value</varname>. The boolean value is stored internally as the
    string <quote>true</quote> or <quote>false</quote>.
</para>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public static void <function>setTemporaryProperty</function></funcdef>
  <paramdef>String <parameter>name</parameter></paramdef>
  <paramdef>String <parameter>property</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
<para>
    This sets a property that will not be stored during the current
    jEdit session only. This method is useful for storing a value
    obtained by one macro for use by another macro.
</para>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public static String <function>getJEditHome</function></funcdef>
  <void/>
 </funcprototype>
</funcsynopsis>
<para>
    Returns the path of the directory containing the jEdit executable file.
</para>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public static String <function>getSettingsDirectory</function></funcdef>
  <void/>
 </funcprototype>
</funcsynopsis>
<para>
    Returns the path of the directory in which user-specific settings
    are stored. This will be null if jEdit was started with the
    <command>-nosettings</command> command-line switch; so do not
    blindly use this method without checking for a null return value
    first.
</para>
</listitem>

</itemizedlist>


<para>The jEdit object also maintains a number of collections which
are useful in some situations. They include the following:</para>

<itemizedlist>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public static EditAction[] <function>getActions</function></funcdef>
  <void/>
 </funcprototype>
</funcsynopsis>
<para>
    Returns an array of <quote>actions</quote> or short routines maintained and used
    by the editor.
</para>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public static EditAction <function>getAction</function></funcdef>
  <paramdef>String <parameter>action</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
<para>
    Returns the action named <varname>action</varname>, or
    <constant>null</constant> if it does not exist.
</para>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public static Buffer[] <function>getBuffers</function></funcdef>
  <void/>
 </funcprototype>
</funcsynopsis>
<para>
    Returns an array of open buffers.
</para>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public static Properties <function>getProperties</function></funcdef>
  <void/>
 </funcprototype>
</funcsynopsis>
<para>
    Returns a Java <classname>Properties</classname> object (a class derived from
    <classname>Hashtable</classname>) holding all properties
    currently used by the program.  The constituent properties fall into three
    categories: application properties, <quote>site</quote> properties, and
    <quote>user</quote> properties.  Site properties take precedence over application
    properties with the same <quote>key</quote> or name, and user properties take
    precedence over both application and site properties.  User settings are
    written to a file named <filename>properties</filename> in the user settings
    directory upon program exit or whenever <function>jEdit.saveSettings()</function>
    is called.
</para>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public static int <function>getBufferCount</function></funcdef>
  <void/>
 </funcprototype>
</funcsynopsis>
<para>
    Returns the number of open buffers.
</para>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public static Buffer <function>getBuffer</function></funcdef>
  <paramdef>String <parameter>path</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
<para>
    Returns the <classname>Buffer</classname> object containing the file named
    <varname>path</varname>. or <constant>null</constant> if the buffer does not exist.
</para>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public static Mode[] <function>getModes</function></funcdef>
  <void/>
 </funcprototype>
</funcsynopsis>
<para>
    Returns an array containing all editing modes used by jEdit.
</para>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public static Mode <function>getMode</function></funcdef>
  <paramdef>String <parameter>name</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
<para>
    Returns the editing mode named by <varname>name</varname>, or
    <constant>null</constant> if such a mode does not exist.
</para>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public static EditPlugin[] <function>getPlugins</function></funcdef>
  <void/>
 </funcprototype>
</funcsynopsis>
<para>
    Returns an array containing all existing plugins.
</para>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>plugin static EditPlugin <function>getPlugin</function></funcdef>
  <paramdef>String <parameter>name</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
<para>
    Returns the plugin named by <varname>name</varname>, or
    <constant>null</constant> if such a plugin does not exist.
</para>
</listitem>

</itemizedlist>
</sect1>

<sect1 id="class-view"><title>Class View</title>

<para>
    This class represents the <quote>parent</quote> or top-level frame window
    in which the editing occurs. It contains the various visible
    components of the program, including the editing pane, menubar,
    toolbar, and any docking windows containing plugins.
</para>

<para>
    Some useful methods from this class include the following:
</para>

<itemizedlist>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public void <function>splitHorizontally</function></funcdef>
  <void/>
 </funcprototype>
</funcsynopsis>
<para>
    Splits the view horizontally.
</para>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public void <function>splitVertically</function></funcdef>
  <void/>
 </funcprototype>
</funcsynopsis>
<para>
    Splits the view vertically.
</para>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public void <function>unsplit</function></funcdef>
  <void/>
 </funcprototype>
</funcsynopsis>
<para>
    Unsplits the view.
</para>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public synchronized void <function>showWaitCursor</function></funcdef>
  <void/>
 </funcprototype>
</funcsynopsis>
<para>
    Shows a <quote>waiting</quote> cursor (typically, an hourglass).
</para>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public synchronized void <function>hideWaitCursor</function></funcdef>
  <void/>
 </funcprototype>
</funcsynopsis>
<para>
    Removes the <quote>waiting</quote> cursor. This method and
    <function>showWaitCursor()</function> are implemented using a reference
    count of requests for wait cursors, so that nested calls work
    correctly; however, you should
    be careful to use these methods in tandem.
</para>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public StatusBar <function>getStatus</function></funcdef>
  <void/>
 </funcprototype>
</funcsynopsis>
<para>
    Eeach <classname>View</classname> displays a
    <classname>StatusBar</classname> at its bottom edge. It shows the
    current cursor position, the editing mode of the current buffer and
    other information. The method <function>setMessage(String
    message)</function> can be called on the return value of
    <function>getStatus()</function> to display reminders or updates.
    The message remains until the method is called
    again. To display a temporary message in the status bar, call
    <function>setMessageAndClear(String message)</function>, which will
    erase the message automatically after ten seconds.
</para>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public DockableWindowManager <function>getDockableWindowManager</function></funcdef>
  <void/>
 </funcprototype>
</funcsynopsis>
<para>
    The object returned by this method keeps track of all dockable
    windows. See <xref linkend="class-dockablewindowmanager" />.
</para>
</listitem>

</itemizedlist>

</sect1>

<!-- open sect1 -->
<sect1 id="class-registers"><title>Class Registers</title>
<para>
  A <classname>Register</classname> is string of text indexed by a
  single character.  Typically the text is taken from selected buffer text
  and the index character is a keyboard character selected by the user.
</para>

<para>
  The application maintains a single <classname>Registers</classname> object
  consisting of an dynamically sized array of <classname>Register</classname>
  objects.  The <classname>Registers</classname> class defines a number of methods
  that give each register the properties of a virtual clipboard.
</para>

<para>
  The following methods provide a clipboard operations for register
  objects:
</para>

<itemizedlist>

  <listitem>
    <funcsynopsis>
      <funcprototype>
        <funcdef>public static void <function>copy</function></funcdef>
        <paramdef>JEditTextArea <parameter>textArea</parameter></paramdef>
        <paramdef>char <parameter>register</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
    <para>
      Saves the selected text in the designated <parameter>textArea</parameter>
      to the register indexed at <parameter>register</parameter>.  This
      will replace the existing contents of the designated register.
    </para>
  </listitem>

  <listitem>
    <funcsynopsis>
      <funcprototype>
        <funcdef>public static void <function>cut</function></funcdef>
        <paramdef>JEditTextArea <parameter>textArea</parameter></paramdef>
        <paramdef>char <parameter>register</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
  <para>
    Saves the selected text in the designated <parameter>textArea</parameter>
    to the register indexed at <parameter>register</parameter>, and removes the
    text from the text area.  This will replace the existing contents of the
    designated register.
  </para>
  </listitem>

  <listitem>
    <funcsynopsis>
      <funcprototype>
        <funcdef>public static void <function>append</function></funcdef>
        <paramdef>JEditTextArea <parameter>textArea</parameter></paramdef>
        <paramdef>char <parameter>register</parameter></paramdef>
        <paramdef>String <parameter>separator</parameter></paramdef>
        <paramdef>boolean <parameter>cut</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
  </listitem>

  <listitem>
    <funcsynopsis>
      <funcprototype>
        <funcdef>public static void <function>append</function></funcdef>
        <paramdef>JEditTextArea <parameter>textArea</parameter></paramdef>
        <paramdef>char <parameter>register</parameter></paramdef>
        <paramdef>String <parameter>separator</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
  </listitem>

  <listitem>
    <funcsynopsis>
      <funcprototype>
        <funcdef>public static void <function>append</function></funcdef>
        <paramdef>JEditTextArea <parameter>textArea</parameter></paramdef>
        <paramdef>char <parameter>register</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
  <para>
    These three methods append the selected text in the
    <parameter>textArea</parameter> to the designated register. If the
    <parameter>cut</parameter> parameter is not specified, the selected text
    remains in the text area. If the <parameter>separator</parameter>
    parameter is not specified, a newline character is used to separate the
    appended text from any existng register text.
  </para>
  </listitem>

</itemizedlist>

<para>
  The following methods provide a lower-level interface for working with
  registers:
</para>

<itemizedlist>

  <listitem>
    <funcsynopsis>
      <funcprototype>
        <funcdef>public static void <function>setRegister</function></funcdef>
        <paramdef>char <parameter>name</parameter></paramdef>
        <paramdef>Register <parameter>register</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
  </listitem>

  <listitem>
    <funcsynopsis>
      <funcprototype>
        <funcdef>public static void <function>setRegister</function></funcdef>
        <paramdef>char <parameter>name</parameter></paramdef>
        <paramdef>Register <parameter>newRegister</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
  </listitem>

  <listitem>
    <funcsynopsis>
      <funcprototype>
        <funcdef>public static void <function>clearRegister</function></funcdef>
        <paramdef>char <parameter>name</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
    <para>
      Sets the text of the designated register to <constant>null</constant>.
      If the register is one of the two registers reserved by the
      application (as discussed in the next section), the text value is
      set to an empty string.
    </para>
  </listitem>

  <listitem>
    <funcsynopsis>
      <funcprototype>
        <funcdef>public static Register <function>getRegister</function></funcdef>
        <paramdef>char <parameter>name</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
  </listitem>

  <listitem>
    <funcsynopsis>
      <funcprototype>
        <funcdef>public static Register[] <function>getRegisters</function></funcdef>
        <void/>
      </funcprototype>
    </funcsynopsis>
  </listitem>

</itemizedlist>

</sect1>


<sect1 id="class-register"><title>Interface Registers.Register</title>

<para>
  This interface requires implementation of two methods:
  <function>setValue()</function>, which takes a
  <classname>String</classname> parameter, and
  <function>toString()</function>, which return a textual representation
  of the register's contents. Two classes implement this interface. A
  <classname>ClipboardRegister</classname> is tied to the contents of the
  application's clipboard. The application assigns a
  <classname>ClipboardRegister</classname> to the register indexed under
  the character <filename>$</filename>. A
  <classname>StringRegister</classname> is created for registers assigned
  by the user. In addition, the application assigns to the
  <classname>StringRegister</classname> indexed under <filename>%</filename>
  the last text segment selected in the text area.
</para>

<para>
  A <classname>Register</classname> object does not maintain a copy of
  its index key.  Indexing is performed by the <classname>Registers</classname>
  object.
</para>


</sect1>


<!-- LaTeX spews with id's that are too long? -->
<sect1 id="class-dockablewindowmanager"><title>Class DockableWindowManager</title>

    <para>
        Windows conforming to jEdit's dockable window API can appear in
        <quote>panes</quote> located above, below or to the left or right of the
        main editing pane. They can also be displayed in <quote>floating</quote>
        frame windows. A <classname>DockableWindowManager</classname> keeps
        track of the plugins associated with a particular
        <classname>View</classname>. Each <classname>View</classname> object
        contains an instance of this class.
    </para>

    <itemizedlist>
      <listitem>
        <funcsynopsis>
          <funcprototype>
            <funcdef>public DockableWindow <function>getDockableWindow</function></funcdef>
            <paramdef>String <parameter>name</parameter></paramdef>
          </funcprototype>
        </funcsynopsis>
        <para>
          This method returns the <classname>DockableWindow</classname>
          object named by the <varname>name</varname> parameter.  The name of a
          <classname>DockableWindow</classname> is a required property of the
          plugin.  If there is no <classname>DockableWindow</classname> bearing the
          requested name, the method returns <constant>null</constant>.
        </para>
       </listitem>

       <listitem>
        <funcsynopsis>
          <funcprototype>
            <funcdef>public void <function>addDockableWindow</function></funcdef>
            <paramdef>String <parameter>name</parameter></paramdef>
          </funcprototype>
        </funcsynopsis>
        <para>
          If the <classname>DockableWindow</classname> named by the
          <varname>name</varname> parameter does not exist, a message is
          sent to the associated plugin to create it.  The
          <classname>DockableWindow</classname> is then made visible.
        </para>
       </listitem>

       <listitem>
        <funcsynopsis>
          <funcprototype>
            <funcdef>public void <function>showDockableWindow</function></funcdef>
            <paramdef>String <parameter>name</parameter></paramdef>
          </funcprototype>
        </funcsynopsis>
       </listitem>

       <listitem>
        <funcsynopsis>
          <funcprototype>
            <funcdef>public void <function>removeDockableWindow</function></funcdef>
            <paramdef>String <parameter>name</parameter></paramdef>
          </funcprototype>
        </funcsynopsis>
       </listitem>

       <listitem>
        <funcsynopsis>
          <funcprototype>
            <funcdef>public void <function>toggleDockableWindow</function></funcdef>
            <paramdef>String <parameter>name</parameter></paramdef>
          </funcprototype>
        </funcsynopsis>
       <para>
         These methods, respectively show, hide and toggle the visibility
         of the <classname>DockableWindow</classname> object named by
         the <varname>name</varname> parameter.  If the
         <classname>DockableWindowManager</classname> does not contain a
         reference to the window, these methods send an error message to the
         activity log and have no other effect.  Only
         <function>addDockableWindow()</function> can cause the creation
         of a <classname>DockableWindow</classname>.
         </para>
       </listitem>
    </itemizedlist>

</sect1>

<sect1 id="class-jedittextarea"><title>Class JEditTextArea</title>

<para>
    This class is the visible component that displays the file
    being edited. It is derived from Java's <classname>JComponent</classname> class.
</para>

<para>
    Methods in this class that deal with selecting text
    rely upon classes derived from jEdit's
    <classname>Selection</classname> class. The
    <quote>Selection API</quote> permits selection and concurrent manipulation
    of multiple, non-contiguous regions of text. After describing the
    selection classes, we will outline the selection methods
    of <classname>JEditTextArea</classname>, followed by a listing of
    other methods in this class that are useful in writing macros.
</para>

<sect2 id="class-selection"><title>Class Selection</title>
  <para>
    This is an <glossterm>abstract class</glossterm> which holds data
    on a region of selected text. As an abstract class, it cannot be used
    directly, but instead serves as a parent class for specific types
    of selection structures.  The definition of
    <classname>Selection</classname> contains two child classes used by the
    Selection API:
  </para>

  <itemizedlist>
    <listitem>
      <para>
        <classname>Selection.Range</classname> - representing an ordinary
        range of selected text
      </para>
    </listitem>
    <listitem>
      <para>
        <classname>Selection.Rect</classname> - representing a rectangular
        selection region
      </para>
    </listitem>
  </itemizedlist>

  <para>
    A new instance of either type of <classname>Selection</classname>
    can be created by specifying its starting and ending caret positions:
  </para>

  <informalexample><programlisting>    selRange = new Selection.Range(start, end);

    setRect = new Selection.Rect(start, end);</programlisting></informalexample>

  <para>
    Both classes inherit or implement the following methods of the parent
    <classname>Selection</classname> class:
  </para>

  <itemizedlist>

    <listitem>
      <funcsynopsis>
        <funcprototype>
          <funcdef>public int <function>getStart</function></funcdef>
          <void/>
        </funcprototype>
      </funcsynopsis>
    </listitem>

    <listitem>
      <funcsynopsis>
        <funcprototype>
          <funcdef>public int <function>getEnd</function></funcdef>
          <void/>
        </funcprototype>
      </funcsynopsis>
      <para>
        Retrieves the buffer position representing the start or end
        of the selection.
      </para>
    </listitem>

    <listitem>
      <funcsynopsis>
        <funcprototype>
          <funcdef>public int <function>getStartLine</function></funcdef>
          <void/>
        </funcprototype>
      </funcsynopsis>
    </listitem>

    <listitem>
      <funcsynopsis>
        <funcprototype>
          <funcdef>public int <function>getEndLine</function></funcdef>
          <void/>
        </funcprototype>
      </funcsynopsis>
      <para>
        Retrieves the zero-based index number representing the line
        on which the selection starts or ends.
      </para>
    </listitem>

    <listitem>
      <funcsynopsis>
        <funcprototype>
          <funcdef>public int <function>getStart</function></funcdef>
          <paramdef>Buffer <parameter>buffer</parameter></paramdef>
          <paramdef>int <parameter>line</parameter></paramdef>
        </funcprototype>
      </funcsynopsis>
    </listitem>

    <listitem>
      <funcsynopsis>
        <funcprototype>
          <funcdef>public int <function>getEnd</function></funcdef>
          <paramdef>Buffer <parameter>buffer</parameter></paramdef>
          <paramdef>int <parameter>line</parameter></paramdef>
        </funcprototype>
      </funcsynopsis>
      <para>
        These two methods return the position of the beginning or end of
        that portion of the selection falling on the line referenced by
        the <parameter>line</parameter> parameter.  The parameter
        <parameter>buffer</parameter> is required because a
        <classname>Selection</classname> object is a lightweight structure
        that does not contain a reference to the
        <classname>Buffer</classname> object to which it relates.
      </para>
      <para>
        These methods do not check whether the <parameter>line</parameter>
        parameter is within the range of lines actually covered by the
        selection. They would typically be used within a
        loop defined by the <function>getStartLine()</function> and
        <function>getEndLine()</function> methods to manipulate
        selection text on a line-by-line basis.  Using them without range
        checking could cause unintended behavior.
      </para>
    </listitem>

  </itemizedlist>

</sect2>

<sect2 id="class-jedittextarea-selection"><title>Selection methods in
JEditTextArea</title>
<para>
  A <classname>JEditTextArea</classname> object maintains an
  <classname>Vector</classname> of current <classname>Selection</classname>
  objects. When a selection is added, the <classname>JEditTextArea</classname>
  attempts to merge the new selection with any existing selection whose range
  contains or overlaps with the new item.  When selections are added or
  removed using by these methods, the editing display is updated to show
  the change in selection status.
</para>

<para>
  Here are the principal methods of <classname>JEditTextArea</classname>
  dealing with <classname>Selection</classname> objects:
</para>

<sect3 id="class-jedittextarea-selection-add-remove">
<title>Adding and removing selections</title>
<itemizedlist>

  <listitem>
    <funcsynopsis>
      <funcprototype>
        <funcdef>public void <function>setMultipleSelectionEnabled</function></funcdef>
        <paramdef>boolean <parameter>multi</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
    <para>
      Set multiple selection on or off according to the value of
      <parameter>multi</parameter>. This only affects the ability to
      make multiple selections in the user interface; macros and plugins
      can manipulate them regardless of the setting of this flag. In fact,
      in most cases, calling this method should not be necessary.
    </para>
  </listitem>

  <listitem>
    <funcsynopsis>
      <funcprototype>
        <funcdef>public Selection[] <function>getSelection</function></funcdef>
        <void/>
      </funcprototype>
    </funcsynopsis>
    <para>
      Returns an array containing a copy of the current selections.
    </para>
  </listitem>

  <listitem>
    <funcsynopsis>
      <funcprototype>
        <funcdef>public int <function>getSelectionCount</function></funcdef>
        <void/>
      </funcprototype>
    </funcsynopsis>
    <para>
      Returns the current number of selections.  This can be used to test
      for the existence of selections.
    </para>
  </listitem>

  <listitem>
    <funcsynopsis>
      <funcprototype>
        <funcdef>public Selection <function>getSelectionAtOffset</function></funcdef>
        <paramdef>int <parameter>offset</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
    <para>
      Returns the <classname>Selection</classname> containing the specific offset,
      or <constant>null</constant> if there is no selection at that offset.
    </para>
  </listitem>

  <listitem>
    <funcsynopsis>
      <funcprototype>
        <funcdef>public void <function>addToSelection</function></funcdef>
        <paramdef>Selection <parameter>selection</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
  </listitem>

  <listitem>
    <funcsynopsis>
      <funcprototype>
        <funcdef>public void <function>addToSelection</function></funcdef>
        <paramdef>Selection[] <parameter>selection</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
    <para>
      Adds a single <classname>Selection</classname> or an array of
      <classname>Selection</classname> objects to the existing collection
      maintined by the <classname>JEditTextArea</classname>.  Nested or
      overlapping selections will be merged where possible.
    </para>
  </listitem>

  <listitem>
    <funcsynopsis>
      <funcprototype>
        <funcdef>public void <function>extendSelection</function></funcdef>
        <paramdef>int <parameter>offset</parameter></paramdef>
        <paramdef>int <parameter>end</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
    <para>
      Extends the existing selection containing the position at
      <parameter>offset</parameter> to the position represented by
      <parameter>end</parameter>.  If there is no selection containing
      <parameter>offset</parameter> the method creates a new
      <classname>Selection.Range</classname> extending from
      <parameter>offset</parameter> to <parameter>end</parameter> and
      adds it to the current collection.
    </para>
  </listitem>

  <listitem>
    <funcsynopsis>
      <funcprototype>
        <funcdef>public void <function>removeFromSelection</function></funcdef>
        <paramdef>Selection <parameter>sel</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
  </listitem>

  <listitem>
    <funcsynopsis>
      <funcprototype>
        <funcdef>public void <function>removeFromSelection</function></funcdef>
        <paramdef>int <parameter>offset</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
    <para>
      These methods remove a selection from the current collection.  The
      second version removes any selection that contains the position at
      <parameter>offset</parameter>, and has no effect if no such
      selection exists.
    </para>
  </listitem>
</itemizedlist>
</sect3>

<sect3 id="class-jedittextarea-selection-text">
<title>Getting and setting selected text</title>
<itemizedlist>

  <listitem>
    <funcsynopsis>
      <funcprototype>
        <funcdef>public String <function>getSelectedText</function></funcdef>
        <paramdef>Selection  <parameter>s</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
  </listitem>

  <listitem>
    <funcsynopsis>
      <funcprototype>
        <funcdef>public String <function>getSelectedText</function></funcdef>
        <paramdef>String <parameter>separator</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
  </listitem>

  <listitem>
    <funcsynopsis>
      <funcprototype>
        <funcdef>public String <function>getSelectedText</function></funcdef>
        <void/>
      </funcprototype>
    </funcsynopsis>
    <para>
      These three methods return a <classname>String</classname> containing
      text corresponding to the current selections. The first version returns
      the text corresponding to a particular selection named as the parameter,
      allowing for iteration through the collection or focus on a specific
      selection (such as a selection containing the current caret position).
      The second version combines all selection text in a single
      <classname>String</classname>, separated by the
      <classname>String</classname> given as the
      <parameter>separator</parameter>. The final version operates like the
      second version, separating individual selections with newline characters.
    </para>
  </listitem>

  <listitem>
    <funcsynopsis>
      <funcprototype>
        <funcdef>public void <function>setSelectedText</function></funcdef>
        <paramdef>Selection <parameter>s</parameter></paramdef>
        <paramdef>String <parameter>selectedText</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
  </listitem>

  <listitem>
    <funcsynopsis>
      <funcprototype>
        <funcdef>public void <function>setSelectedText</function></funcdef>
        <paramdef>String <parameter>selectedText</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
    <para>
      The first version changes the text of the selection represented
      by <parameter>s</parameter> to
      <parameter>selectedText</parameter>. The second version sets the
      text of all active selections; if there are no selections, the
      text will be inserted at the current caret position.
    </para>
    <para>
      The second version of <function>setSelectedText()</function> is
      the method that will typically be used in macro scripts to insert
      text.
    </para>
  </listitem>
  <listitem>
    <funcsynopsis>
      <funcprototype>
        <funcdef>public int[] <function>getSelectedLines</function></funcdef>
        <void/>
      </funcprototype>
    </funcsynopsis>
    <para>
      Returns a sorted array of line numbers on which a selection or selections
      are present. The current line is included in the array whether or
      not it is part of a selection.
    </para>
    <para>
      This method is the most convenient way to iterate through selected lines
      in a buffer. The line numbers in the array returned by this method can
      be passed as a parameter to such methods as
      <function>getLineText()</function>, as discussed below.
    </para>
  </listitem>

</itemizedlist>
</sect3>

<sect3 id="class-jedittextarea-selection-other">
<title>Other selection methods</title>

<para>
  The following methods perform selection operations without using
  <classname>Selection</classname> objects as parameters or return
  values. These methods should only be used in macros.
</para>


<itemizedlist>
<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public void <function>selectBlock</function></funcdef>
  <void/>
 </funcprototype>
</funcsynopsis>
<para>
    Selects the code block surrounding the caret.
</para>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public void <function>selectWord</function></funcdef>
  <void/>
 </funcprototype>
</funcsynopsis>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public void <function>selectLine</function></funcdef>
  <void/>
 </funcprototype>
</funcsynopsis>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public void <function>selectParagraph</function></funcdef>
  <void/>
 </funcprototype>
</funcsynopsis>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public void <function>selectFold</function></funcdef>
  <void/>
 </funcprototype>
</funcsynopsis>
<para>
  Selects the <quote>fold</quote> (a portion of text sharing a given
  indentation level) that contains the line where the editing caret
  is positioned.
</para>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public void <function>selectFoldAt</function></funcdef>
  <paramdef>int <parameter>line</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
  <para>
    Selects the fold containing the line referenced by
    <parameter>line</parameter>.
  </para>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public void <function>selectAll</function></funcdef>
  <void/>
 </funcprototype>
</funcsynopsis>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public void <function>selectNone</function></funcdef>
  <void/>
 </funcprototype>
</funcsynopsis>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public void <function>indentSelectedLines</function></funcdef>
  <void/>
 </funcprototype>
</funcsynopsis>
</listitem>

</itemizedlist>
</sect3>


</sect2>

<sect2 id="class-jedittextarea-non-selection">
  <title>Other methods in JEditTextArea</title>

<sect3 id="class-jedittextarea-caret">
<title>Editing caret methods</title>
<para>
    These methods are used to get, set and move the position of the
    editing caret:
</para>

<itemizedlist>
<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public int <function>getCaretPosition</function></funcdef>
  <void/>
 </funcprototype>
</funcsynopsis>
<para>
    Returns a zero-based index of the caret position in the existing buffer.
</para>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public void <function>setCaretPosition</function></funcdef>
  <paramdef>int <parameter>caret</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
<para>
    Sets the caret position at <parameter>caret</parameter> and deactivates
    any selection of text.
</para>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public void <function>moveCaretPosition</function></funcdef>
  <paramdef>int <parameter>caret</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
<para>
    This moves the caret to the position represented by
    <parameter>caret</parameter> without affecting any selection of
    text.
</para>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public int <function>getCaretLine</function></funcdef>
  <void/>
 </funcprototype>
</funcsynopsis>
<para>
    Returns the line on which the caret is positioned.
</para>
</listitem>


</itemizedlist>

<para>
    Each of the following shortcut methods moves the caret.  If the
    <parameter>select</parameter> parameter is set to
    <constant>true</constant>, the intervening text will be selected
    as well.
</para>

<itemizedlist>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public void <function>goToStartOfLine</function></funcdef>
  <paramdef>boolean <parameter>select</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public void <function>goToEndOfLine</function></funcdef>
  <paramdef>boolean <parameter>select</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public void <function>goToStartOfWhiteSpace</function></funcdef>
  <paramdef>boolean <parameter>select</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public void <function>goToEndOfWhiteSpace</function></funcdef>
  <paramdef>boolean <parameter>select</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public void <function>goToFirstVisibleLine</function></funcdef>
  <paramdef>boolean <parameter>select</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public void <function>goToLastVisibleLine</function></funcdef>
  <paramdef>boolean <parameter>select</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public void <function>goToNextCharacter</function></funcdef>
  <paramdef>boolean <parameter>select</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public void <function>goToPrevCharacter</function></funcdef>
  <paramdef>boolean <parameter>select</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public void <function>goToNextWord</function></funcdef>
  <paramdef>boolean <parameter>select</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public void <function>goToPrevWord</function></funcdef>
  <paramdef>boolean <parameter>select</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public void <function>goToNextLine</function></funcdef>
  <paramdef>boolean <parameter>select</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public void <function>goToPrevLine</function></funcdef>
  <paramdef>boolean <parameter>select</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public void <function>goToNextParagraph</function></funcdef>
  <paramdef>boolean <parameter>select</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public void <function>goToPrevParagraph</function></funcdef>
  <paramdef>boolean <parameter>select</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public void <function>goToNextBracket</function></funcdef>
  <paramdef>boolean <parameter>select</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public void <function>goToPrevBracket</function></funcdef>
  <paramdef>boolean <parameter>select</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
</listitem>

</itemizedlist>


</sect3>

<!-- open sect3 -->
<sect3 id="class-jedittextarea-scrolling">
<title>Methods for scrolling the text area</title>

<itemizedlist>

<listitem>
  <funcsynopsis>
    <funcprototype>
      <funcdef>public void <function>scrollUpLine</function></funcdef>
      <void/>
    </funcprototype>
  </funcsynopsis>
</listitem>

<listitem>
  <funcsynopsis>
    <funcprototype>
      <funcdef>public void <function>scrollUpPage</function></funcdef>
      <void/>
    </funcprototype>
  </funcsynopsis>
</listitem>

<listitem>
  <funcsynopsis>
    <funcprototype>
      <funcdef>public void <function>scrollDownLine</function></funcdef>
      <void/>
    </funcprototype>
  </funcsynopsis>
</listitem>

<listitem>
  <funcsynopsis>
    <funcprototype>
      <funcdef>public void <function>scrollUpPage</function></funcdef>
      <void/>
    </funcprototype>
  </funcsynopsis>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public void <function>scrollToCaret</function></funcdef>
  <paramdef>boolean <parameter>doElectricScroll</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
<para>
    Scrolls the text area to ensure that the caret is visible. The
    <parameter>doElectricScroll</parameter> parameter detemines whether
    <quote>electric scrolling</quote> will occur. This leaves a minimum
    number of lines between the caret line and the top and bottom of the
    editing pane.
</para>
</listitem>

<listitem>
  <funcsynopsis>
    <funcprototype>
      <funcdef>public void <function>centerCaret</function></funcdef>
      <void/>
    </funcprototype>
  </funcsynopsis>
  <para>
    Scrolls the text area so that the line containing the edit caret is
    vertically centered.
  </para>
</listitem>

<listitem>
 <funcsynopsis>
  <funcprototype>
    <funcdef>public void <function>setFirstLine</function></funcdef>
     <paramdef>int <parameter>firstLine</parameter></paramdef>
   </funcprototype>
 </funcsynopsis>
</listitem>

<listitem>
  <funcsynopsis>
    <funcprototype>
      <funcdef>public int <function>getFirstLine</function></funcdef>
      <void/>
    </funcprototype>
  </funcsynopsis>
  <para>
    This pair of methods deals with the line number of the first line
    displayed at the top of the text area. Lines that are hidden by folds or
    narrowing are ignored when making this <quote>virtual</quote> line
    count, so the line number will not necessarily conform to the line
    numbers displayed in the text area's gutter. In addition, the virtual
    line index is zero-based, so <function>getFirstLine()</function> will
    always return zero for the first line of text.
  </para>
  <para>
    To convert a virtual line count to a physical count or vice versa,
    see <xref linkend="class-buffer-virtual-lines" />.
  </para>
</listitem>

<listitem>
 <funcsynopsis>
  <funcprototype>
    <funcdef>public void <function>setElectricScroll</function></funcdef>
     <paramdef>int <parameter>electricScroll</parameter></paramdef>
   </funcprototype>
 </funcsynopsis>
</listitem>

<listitem>
  <funcsynopsis>
    <funcprototype>
      <funcdef>public int <function>getElectricScroll</function></funcdef>
      <void/>
    </funcprototype>
  </funcsynopsis>
  <para>
    The <quote>electric scroll</quote> attribute is the number of lines
    above and below the editing caret that always remain visible when
    scrolling.
  </para>
</listitem>
</itemizedlist>

</sect3>

<sect3 id="class-jedittextarea-position">
<title>Methods for calculating editing positions</title>


<itemizedlist>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public int <function>getLineOfOffset</function></funcdef>
  <paramdef>int <parameter>offset</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
<para>
    Returns the line on which the given offset is found.
</para>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public int <function>getLineStartOffset</function></funcdef>
  <paramdef>int <parameter>line</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public int <function>getLineEndOffset</function></funcdef>
  <paramdef>int <parameter>line</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
<para>
    Returns the offset of the beginning or end of the given line.
</para>
</listitem>

</itemizedlist>
</sect3>

<sect3 id="class-jedittextarea-gettext">
<title>Other methods for retrieving text</title>

<para>
    These methods can retrieve buffer text without regard
    to a selection or the position of the editing caret.
</para>

<itemizedlist>
<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public String <function>getText</function></funcdef>
  <paramdef>int <parameter>start</parameter></paramdef>
  <paramdef>int <parameter>len</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
<para>
    Returns the text located between buffer offset positions.
</para>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public String <function>getLineText</function></funcdef>
  <paramdef>int <parameter>lineIndex</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
<para>
    Returns the text on the given line.
</para>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public String <function>getText</function></funcdef>
  <void/>
 </funcprototype>
</funcsynopsis>
<para>
    Returns the entire text in the text area.
</para>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public void <function>setText</function></funcdef>
  <paramdef>String <parameter>text</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
<para>
    Sets (and replaces) the entire text of the text area.
</para>
</listitem>

</itemizedlist>
</sect3>


<sect3 id="class-jedittextar…