api-guide.xml | searchcode

/jEdit/tags/jedit-4-1-pre5/doc/users-guide/api-guide.xml

#
XML | 2353 lines | 2081 code | 264 blank | 8 comment | 0 complexity | 1c4327a1562dcbbc47f96f141e5a7b52 MD5 | raw file
Possible License(s): BSD-3-Clause, AGPL-1.0, Apache-2.0, LGPL-2.0, LGPL-3.0, GPL-2.0, CC-BY-SA-3.0, LGPL-2.1, GPL-3.0, MPL-2.0-no-copyleft-exception, IPL-1.0

<!-- 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-guide"><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 void <function>setProperty</function></funcdef>
  <paramdef>String <parameter>name</parameter></paramdef>
  <paramdef>String <parameter>property</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
<para>
    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 boolean <function>getBooleanProperty</function></funcdef>
  <paramdef>String <parameter>name</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
<para>
    Returns a <classname>boolean</classname> 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>setBooleanProperty</function></funcdef>
  <paramdef>String <parameter>name</parameter></paramdef>
  <paramdef>boolean <parameter>value</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
<para>
    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 int <function>getIntegerProperty</function></funcdef>
  <paramdef>String <parameter>name</parameter></paramdef>
  <paramdef>int <parameter>defaultValue</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
<para>
    Returns the integer value of the property named by
    <varname>name</varname>. If the property value is not a valid
    numeric string, returns <varname>defaultValue</varname> instead.
</para>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public static void <function>setIntegerProperty</function></funcdef>
  <paramdef>String <parameter>name</parameter></paramdef>
  <paramdef>int <parameter>value</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
<para>
    Sets the property named by <varname>name</varname> to
    <varname>value</varname>.
</para>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public static Color <function>getColorProperty</function></funcdef>
  <paramdef>String <parameter>name</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
<para>
    Returns the value of the specified property as a
    <classname>java.awt.Color</classname> instance, or <constant>null</constant>
    if the color value cannot be parsed.
</para>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public static void <function>setColorProperty</function></funcdef>
  <paramdef>String <parameter>name</parameter></paramdef>
  <paramdef>Color <parameter>value</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
<para>
    Sets the property named by <varname>name</varname> to
    the textual representation of the color instance named by
    <varname>value</varname>.
</para>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public static Font <function>getFontProperty</function></funcdef>
  <paramdef>String <parameter>name</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
<para>
    Returns the value of the specified property as a
    <classname>java.awt.Font</classname> instance, or <constant>null</constant>
    if the font specification cannot be parsed.
</para>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public static void <function>setFontProperty</function></funcdef>
  <paramdef>String <parameter>name</parameter></paramdef>
  <paramdef>Font <parameter>value</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
<para>
    Sets the property named by <varname>name</varname> to
    the textual representation of the font instance stored in
    <varname>value</varname>.
</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 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, because it does not
    clutter up the user properties file on disk.
</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 <constant>null</constant> 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 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 Buffer[] <function>getBuffers</function></funcdef>
  <void/>
 </funcprototype>
</funcsynopsis>
<para>
    Returns an array of open buffers.
</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 loaded 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, menu bar,
    toolbar, and any docked windows.
</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>
    Each <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>

<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
      maintained 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.
    </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>Buffer.getLineText()</function> (see
      <xref linkend="class-buffer-editing"/>).
    </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-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>


</sect2>

<!-- open sect3 -->
<sect2 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>scrollTo</function></funcdef>
  <paramdef>int <parameter>location</parameter></paramdef>
  <paramdef>boolean <parameter>doElectricScroll</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public void <function>scrollToCaret</function></funcdef>
  <paramdef>boolean <parameter>doElectricScroll</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
<para>
    The first version scrolls the text area to ensure that the caret is
    visible; the second scrolls to ensure that an arbitrary offset
    (from the start of the buffer) is visible. The
    <parameter>doElectricScroll</parameter> parameter determines whether
    <quote>electric scrolling</quote> will occur. This leaves a minimum
    number of lines between the target 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-jedittextarea-virtual-lines" />.
  </para>
</listitem>

</itemizedlist>

</sect2>

<sect2 id="class-jedittextarea-delete">
<title>Methods for deleting text</title>

<itemizedlist>

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

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

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

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

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

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

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

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

</itemizedlist>
</sect2>

<sect2 id="class-jedittextarea-modify">
<title>Methods for modifying text</title>

<itemizedlist>

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

<listitem>
  <funcsynopsis>
    <funcprototype>
      <funcdef>public void <function>toUpperCase</function></funcdef>
      <void/>
    </funcprototype>
  </funcsynopsis>
  <para>
    These two methods operate on all selected text, including multiple
    selections.
  </para>
</listitem>

<listitem>
  <funcsynopsis>
    <funcprototype>
      <funcdef>public void <function>joinLines</function></funcdef>
      <void/>
    </funcprototype>
  </funcsynopsis>
  <para>
    Joins the current line with the following line.
  </para>
</listitem>

<listitem>
  <funcsynopsis>
    <funcprototype>
      <funcdef>public void <function>setOverwriteEnabled</function></funcdef>
      <paramdef>boolean <parameter>overwrite</parameter></paramdef>
    </funcprototype>
  </funcsynopsis>
</listitem>

<listitem>
  <funcsynopsis>
    <funcprototype>
      <funcdef>public boolean <function>isOverwriteEnabled</function></funcdef>
      <void/>
    </funcprototype>
  </funcsynopsis>
  <para>
    Sets and gets whether added text will overwrite text at the editing
    caret or whether it will be inserted immediately to the right of the
    caret.
  </para>
</listitem>

<listitem>
  <funcsynopsis>
    <funcprototype>
      <funcdef>public void <function>userInput</function></funcdef>
      <paramdef>char <parameter>ch</parameter></paramdef>
    </funcprototype>
  </funcsynopsis>
  <para>
     Inserts the character at the caret position as if it were typed at
     the keyboard (keyboard input is actually passed to this method).
     Unlike <function>setSelectedText()</function>, or
     <function>insert()</function> in the
     <classname>Buffer</classname> class, this method triggers
     any active text formatting features such as auto indent,
     abbreviation expansion and word wrap.
  </para>
</listitem>

</itemizedlist>

</sect2>

<sect2 id="class-jedittextarea-commment">
<title>Methods for creating comments</title>

<itemizedlist>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public void <function>lineComment</function></funcdef>
  <void/>
 </funcprototype>
</funcsynopsis>
<para>
    This inserts the line comment string at the beginning of each selected line.
</para>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public void <function>rangeComment</function></funcdef>
  <void/>
 </funcprototype>
</funcsynopsis>
<para>
    This surrounds each selected text chunk with
    the comment start and end strings.
</para>
</listitem>

</itemizedlist>
</sect2>

<sect2 id="class-jedittextarea-virtual-lines">
<title>Virtual and physical line indices</title>

<para>
When jEdit's folding or narrowing features are used to hide
  portions of a buffer, the <quote>virtual</quote> line count visible
  in the text area is generally not equal to the <quote>physical</quote>

line count of the buffer represented by the gutter's display.  The
  following pair of methods translate one enumeration to the other.
</para>


<itemizedlist>

<listitem>
<funcsynopsis>
<funcprototype>
<funcdef>public int <function>virtualToPhysical</function></funcdef>

<paramdef>int <parameter>lineNo</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</listitem>

<listitem>
<funcsynopsis>
<funcprototype>

<funcdef>public int <function>physicalToVirtual</function></funcdef>
<paramdef>int <parameter>lineNo</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</listitem>

</itemizedlist>

</sect2>

</sect1>

<sect1 id="class-buffer"><title>Class Buffer</title>

<para>
    A <classname>Buffer</classname> represents the contents of an open text
    file as it is maintained in the computer's memory (as opposed to
    how it may be stored on a disk).
</para>

<sect2 id="class-buffer-attrs"><title>File attribute methods</title>

<itemizedlist>

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

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

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public File <function>getFile</function></funcdef>
  <void/>
 </funcprototype>
</funcsynopsis>
<para>
 This method may return <constant>null</constant> if the file is stored on
 a remote file system (for example, if the <application>FTP</application>
 or <application>Archive</application> plugins are in use). This method
 should be avoided unless you really need to use the
 <classname>java.io.File</classname> APIs and you are sure the buffer in
 question is a local file.
</para>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public boolean <function>isNewFile</function></funcdef>
  <void/>
 </funcprototype>
</funcsynopsis>
<para>
    Returns whether a buffer lacks a corresponding version on disk.
</para>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public boolean <function>isDirty</function></funcdef>
  <void/>
 </funcprototype>
</funcsynopsis>
<para>
    Returns whether there have been unsaved changes to the buffer.
</para>
</listitem>

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

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

</itemizedlist>

</sect2>

<sect2 id="class-buffer-attr"><title>Editing attribute methods</title>

<itemizedlist>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public Mode <function>getMode</function></funcdef>
  <void/>
 </funcprototype>
</funcsynopsis>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public void <function>setMode</function></funcdef>
  <paramdef>Mode <parameter>mode</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
<para>
    Gets and sets the editing mode for the buffer.
</para>
</listitem>

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

  <listitem>
    <funcsynopsis>
      <funcprototype>
        <funcdef>public int <function>getTabSize</function></funcdef>
        <void/>
      </funcprototype>
    </funcsynopsis>
    <para>
      These methods return the size of an initial indentation at the beginning
      of a line and the distance between tab stops, each measured in
      character columns. If these properties are not individually set for
      a specific buffer, they are inherited from the properties of the buffer's
      associated editing mode.
    </para>
  </listitem>
</itemizedlist>

<para>
  The <classname>Buffer</classname> object maintains a table of
  properties that describe a broad range of attributes. The value of each
  property is stored using a
  <classname>String</classname> that names the particular property.
  Most of these properties are documented in <xref
  linkend="buffer-local" />.
</para>

<itemizedlist>

  <listitem>
    <funcsynopsis>
      <funcprototype>
        <funcdef>public Object <function>getProperty</function></funcdef>
        <paramdef>String <parameter>name</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
    <para>
      Using this method is generally discouraged, because it returns an
      <classname>Object</classname> which must be cast to another type
      in order to be useful, and this can cause problems if the object
      is of a different type than what your plugin or macro expects.
    </para>
    <para>
      jEdit 4.0 added a number of <quote>wrapper</quote> methods,
      documented below; you are strongly encouraged to use them
      instead.
    </para>
  </listitem>

  <listitem>
    <funcsynopsis>
      <funcprototype>
        <funcdef>public void <function>setProperty</function></funcdef>
        <paramdef>String <parameter>name</parameter></paramdef>
        <paramdef>Object <parameter>value</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
    <para>
     Sets the value of a property named by <varname>name</varname> to
     <varname>value</varname>.
    </para>
  </listitem>

</itemizedlist>

<para>
  These methods provide shortcuts for getting and setting
  string, integer and <classname>boolean</classname>
  properties.
</para>

<itemizedlist>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public static String <function>getStringProperty</function></funcdef>
  <paramdef>String <parameter>name</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
<para>
    Returns the value of the property named by
    <varname>name</varname> as a string.
</para>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public static void <function>setStringProperty</function></funcdef>
  <paramdef>String <parameter>name</parameter></paramdef>
  <paramdef>String <parameter>value</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
<para>
    Sets the property named by <varname>name</varname> to
    <varname>value</varname>.
</para>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public static boolean <function>getBooleanProperty</function></funcdef>
  <paramdef>String <parameter>name</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
<para>
    Returns a <classname>boolean</classname> 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>setBooleanProperty</function></funcdef>
  <paramdef>String <parameter>name</parameter></paramdef>
  <paramdef>boolean <parameter>value</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
<para>
    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 int <function>getIntegerProperty</function></funcdef>
  <paramdef>String <parameter>name</parameter></paramdef>
  <paramdef>int <parameter>defaultValue</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
<para>
    Returns the integer value of the property named by
    <varname>name</varname>. If the property value is not a valid
    numeric string, returns <varname>defaultValue</varname> instead.
</para>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public static void <function>setIntegerProperty</function></funcdef>
  <paramdef>String <parameter>name</parameter></paramdef>
  <paramdef>int <parameter>value</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
<para>
    Sets the property named by <varname>name</varname> to
    <varname>value</varname>.
</para>
</listitem>
</itemizedlist>

</sect2>



<sect2 id="class-buffer-io"><title>Input/output methods</title>

<itemizedlist>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public void <function>reload</function></funcdef>
  <paramdef>View <parameter>view</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
<para>
  Reloads the buffer from disk into <parameter>view</parameter>, asking
  for confirmation if the buffer has unsaved changes.
</para>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public boolean <function>save</function></funcdef>
  <paramdef>View <parameter>view</parameter></paramdef>
  <paramdef>String <parameter>path</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public boolean <function>save</function></funcdef>
  <paramdef>View <parameter>view</parameter></paramdef>
  <paramdef>String <parameter>path</parameter></paramdef>
  <paramdef>boolean <parameter>rename</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
<para>
    The <parameter>rename</parameter> parameter causes a buffer's name to
    change if set to <parameter>true</parameter>; if
    <parameter>false</parameter>, a copy is saved to
    <parameter>path</parameter>.
</para>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public boolean <function>saveAs</function></funcdef>
  <paramdef>View <parameter>view</parameter></paramdef>
  <paramdef>boolean <parameter>rename</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
<para>
    Prompts the user for a new name for saving the file.
</para>
</listitem>

</itemizedlist>

</sect2>

<sect2 id="class-buffer-editing"><title>General editing methods</title>

<itemizedlist>

    <listitem>
      <funcsynopsis>
        <funcprototype>
          <funcdef>public String <function>getText</function></funcdef><!--
          --><paramdef>int <parameter>offset</parameter></paramdef>
          <paramdef>int <parameter>length</parameter></paramdef>
        </funcprototype>
      </funcsynopsis>
    </listitem>

    <listitem>
      <funcsynopsis>
        <funcprototype>
          <funcdef>public void <function>getText</function></funcdef><!--
          --><paramdef>int <parameter>offset</parameter></paramdef>
          <paramdef>int <parameter>length</parameter></paramdef>
          <paramdef>Segment <parameter>text</parameter></paramdef>
        </funcprototype>
      </funcsynopsis>
     <para>
       These methods extract a portion of buffer text having length
       <varname>length</varname> beginning at offset position
       <varname>offset</varname>.  The first method returns a newly
       created <classname>String</classname> containing the requested
       excerpt.  The second version initializes an existing
       <classname>Segment</classname> object with the location of the
       requested excerpt.  The <classname>Segment</classname> object
       represents array locations within the <classname>Buffer</classname>
       object's data and should be used on a read-only basis. Calling
       <function>toString()</function> on the <classname>Segment</classname>
       will create a new object suitable for manipulation.
     </para>
     <para>
       Using a <classname>Segment</classname> is generally more
       efficient than using a <classname>String</classname> because it
       results in less memory allocation and array copying. However,
       <classname>Segments</classname> are slightly harder to set up and
       use.
     </para>
    </listitem>

    <listitem>
    <funcsynopsis>
    <funcprototype>
    <funcdef>public String <function>getLineText</function></funcdef>
    <paramdef>int <parameter>lineIndex</parameter></paramdef>
    </funcprototype>
    </funcsynopsis>
    </listitem>

    <listitem>
    <funcsynopsis>
    <funcprototype>
    <funcdef>public void <function>getLineText</function></funcdef>
    <paramdef>int <parameter>lineIndex</parameter></paramdef>
          <paramdef>Segment <parameter>text</parameter></paramdef>
    </funcprototype>
    </funcsynopsis>
    <para>
      Returns the text of the given line. Just as with
      <function>getText()</function>, there are two forms of this
      method; the first returns a <classname>String</classname>, the
      second copies into a <classname>Segment</classname>.
    </para>
    </listitem>

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

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public void <function>endCompoundEdit</function></funcdef>
  <void/>
 </funcprototype>
</funcsynopsis>
<para>
    Marks the beginning and end of a series of editing operations that will
    be dealt with by a single <guimenuitem>Undo</guimenuitem> command.
</para>
</listitem>

    <listitem>
      <funcsynopsis>
        <funcprototype>
          <funcdef>public void <function>insert</function></funcdef><!--
          --><paramdef>int <parameter>offset</parameter></paramdef>
          <paramdef>String <parameter>text</parameter></paramdef>
        </funcprototype>
      </funcsynopsis>
     <para>
       This method inserts the string <varname>text</varname> at offset
       <varname>offset</varname> in the buffer.
     </para>
    </listitem>

    <listitem>
      <funcsynopsis>
        <funcprototype>
          <funcdef>public void <function>remove</function></funcdef><!--
          --><paramdef>int <parameter>offset</parameter></paramdef>
          <paramdef>int <parameter>length</parameter></paramdef>
        </funcprototype>
      </funcsynopsis>
     <para>
       This method removes <varname>length</varname> characters of
       text starting from <varname>offset</varname>.
     </para>
    </listitem>

    <listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public void <function>removeTrailingWhiteSpace</function></funcdef>
  <paramdef>int[] <parameter>lines</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
<para>
    Removes trailing whitespace in the lines referenced by the index numbers
    in <parameter>lines</parameter> array.
</para>
</listitem>

<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>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public int <function>getLineLength</function></funcdef>
  <paramdef>int <parameter>line</parameter></paramdef>
 </funcprototype>
</funcsynopsis>
<para>
    Returns the length of the line number <varname>line</varname> (using a
    zero-based count).
</para>
</listitem>

<listitem>
<funcsynopsis>
 <funcprototype>
  <funcdef>public int <function>getLineCount</function></funcdef>
  <void/>
 </funcprototype>
</funcsynopsis>
<para>
    Returns the number of lines in the buffer being edited.
</para>
</listitem>

<listitem>
<funcsynopsis>
<funcprototype>
<funcdef>public int <function>getLength</function></funcdef><void/>
</funcprototype>
</funcsynopsis>
<para>
 Returns the number of characters in the buffer.
</para>
</listitem>

</itemizedlist>
</sect2>

<sect2 id="class-buffer-markers"><title>Marker methods</title>
<para>
  Buffers may have one or more <glossterm>markers</glossterm> which serve
  as textual bookmarks.  A <classname>Marker</classname> has three key attributes: the
  <classname>Buffer</classname> to which it relates, the line number to which
  the marker refers, and an optional shortcut character.  The shortcut
  identifies the the key that can be pressed with the
  <guimenu>Markers</guimenu>&gt;<guimenuitem>Go To Marker</guimenuitem>
  command to move the editing caret to the marker line location.
</para>
<para>
  The position and shortcut character of a <classname>Marker</classname>
  object can be retrieved with the methods <function>getPosition()</function>
  and <function>getShortcut()</function>.
</para>
<para>
  The <classname>Buffer</classname> class includes the following methods to
  set and retrieve markers:
</para>

<itemizedlist>

  <listitem>
    <funcsynopsis>
      <funcprototype>
        <funcdef>public void <function>addMarker</function></funcdef>
        <paramdef>char <parameter>shortcut</parameter></paramdef>
        <paramdef>int <parameter>pos</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
    <para>
      Adds a marker for the line indicated by <parameter>pos</parameter>
      using <parameter>shortcut</parameter>.  Set
      <parameter>shortcut</parameter> to <constant>'\0'</constant> to
      indicate the absence of a shortcut.
    </para>
  </listitem>

  <listitem>
    <funcsynopsis>
      <funcprototype>
        <funcdef>public Vector <function>getMarkers</function></funcdef>
        <void/>
      </funcprototype>
    </funcsynopsis>
    <para>
      Returns a <classname>Vector</classname> containing the buffer's
      current markers.
    </para>
  </listitem>

  <listitem>
    <funcsynopsis>
      <funcprototype>
        <funcdef>public Marker <function>getMarkerAtLine</function></funcdef>
        <paramdef>int <parameter>line</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
    <para>
      Returns the first marker at the specified line, or
      <constant>null</constant> if no marker is present at the line.
    </para>
  </listitem>

  <listitem>
    <funcsynopsis>
      <funcprototype>
        <funcdef>public Marker <function>getMarker</function></funcdef>
        <paramdef>char <parameter>shortcut</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
    <para>
      Returns the marker with the specified shortcut, or
      <constant>null</constant> if no such marker exists.
    </para>
  </listitem>

  <listitem>
    <funcsynopsis>
      <funcprototype>
        <funcdef>public void <function>removeMarker</function></funcdef>
        <paramdef>int <parameter>line</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
    <para>
      Removes all markers at the specified line.
    </para>
  </listitem>

  <listitem>
    <funcsynopsis>
      <funcprototype>
        <funcdef>public void <function>removeAllMarkers</function></funcdef>
        <void/>
      </funcprototype>
    </funcsynopsis>
    <para>
      Removes all markers in the buffer.
    </para>
  </listitem>

</itemizedlist>

</sect2>

</sect1>

<sect1 id="class-macros"><title>Class Macros</title>

<para>
  This class contains a few methods useful for displaying output messages
  or obtaining input from a macro. These methods are documented in
  detail in <xref linkend="helpful-methods" />.
  Plugins should use the methods in the
  <classname>GUIUtilities</classname> class instead; see
  <xref linkend="class-guiutilities" />.
</para>

<itemizedlist>

<listitem>
 <funcsynopsis>
  <funcprototype>
   <funcdef>public static void <function>message</function></funcdef>
    <paramdef>Component <parameter>comp</parameter></paramdef>
    <paramdef>String <parameter>message</parameter></paramdef>
  </funcprototype>
 </funcsynopsis>
</listitem>

<listitem>
 <funcsynopsis>
  <funcprototype>
   <funcdef>public static void <function>error</function></funcdef>
	<paramdef>View <parameter>view</parameter></paramdef>
    <paramdef>String <parameter>message</parameter></paramdef>
  </funcprototype>
 </funcsynopsis>
</listitem>

<listitem>
 <funcsynopsis>
  <funcprototype>
   <funcdef>public static String <function>input</function></funcdef>
   <paramdef>View <parameter>view</parameter></paramdef>
   <paramdef>String <parameter>prompt</parameter></paramdef>
  </funcprototype>
 </funcsynopsis>
</listitem>

<listitem>
 <funcsynopsis>
  <funcprototype>
   <funcdef>public static String <function>input</function></funcdef>
   <paramdef>View <parameter>view</parameter></paramdef>
   <paramdef>String <parameter>prompt</parameter></paramdef>