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