/jEdit/tags/jedit-4-3-pre5/doc/news42/news.xml

<?xml version="1.0" encoding="UTF-8" ?>

<!-- :folding=sidekick: -->

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
		"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<book>
	<bookinfo>
		<author>
			<firstname>Slava</firstname><surname>Pestov</surname>
		</author>
		<copyright><year>2003</year>
		<year>2004</year><holder>Slava Pestov</holder></copyright>
		<legalnotice><title>Legal Notice</title>
			<para>
				Permission is granted to copy, distribute and/or modify this document
				under the terms of the GNU Free Documentation License, Version 1.1 or
				any later version published by the Free Software Foundation; with no
				<quote>Invariant Sections</quote>, <quote>Front-Cover Texts</quote> or
				<quote>Back-Cover Texts</quote>, each as defined in the license. A copy of
				the license is included in the file <filename>COPYING.DOC.txt</filename>
				included with the jEdit distribution.
			</para>
		</legalnotice>
		<title>What's New in jEdit 4.2</title>
	</bookinfo>

	<chapter id="user-changes"><title>User-Visible Changes</title>
	
	<sect1 id="incompatible"><title>Removed Features</title>
	
	<para>
	 Soft wrapping to the text area width (by setting the wrap width to zero) is no longer supported.
	</para>

	<para>
	 The <guimenu>View</guimenu>&gt;<guisubmenu>Scrolling</guisubmenu>&gt;<guimenuitem>Synchronized Scrolling</guimenuitem> command has been removed.
	</para>

	<para>
	 The <application>jEditLauncher</application> component for Windows shell integration is no longer included.
	</para>

	</sect1>

	<sect1 id="plugin-manager"><title>Plugin Manager</title>
	
	<para>
	 A new plugin API has been added that allows plugins to be loaded and unloaded while jEdit is running. The plugin manager's user interface has also been overhauled to be more intuitive and powerful.
	</para>

	<para>
	 While the new API is mostly backwards compatible, some plugins will no longer work. The best way to upgrade from 4.1 to 4.2 is to completely remove any existing plugins, and re-install a new set from scratch.
	</para>
	
	<para>
	 Plugin options have been moved from the <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem> dialog box to a new <guimenu>Plugins</guimenu>&gt;<guimenuitem>Plugin Options</guimenuitem> dialog box.
	</para>

	<para>
	 If you are a plugin developer, see <xref linkend="api-changes"/>.
	</para>

	</sect1>

	<sect1 id="interface"><title>User Interface</title>
	
	<para>
	 jEdit now saves the configuration of open views between sessions; this includes including their position, size and any splits. This information is stored in the <filename>perspective.xml</filename> file in the settings directory.
	</para>

	<para>
	 Dockable windows can now be moved between panes without having to open the <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem> dialog box. Just right-click on the dockable window's button, or for floating windows, click the small triangle in the top left corner of the window. In both cases this displays a menu where you can pick a new docking location for the window.
	</para>

	<para>
	 A new <guimenu>Utilities</guimenu>&gt;<guimenuitem>Repeat Last Action</guimenuitem> command (shortcut: <keycombo><keycap>Control</keycap><keycap>Space</keycap></keycombo>) repeats the most recently invoked command.
	</para>

	<para>
	 The status bar can now optionally display a simple clock. This can be enabled in the <guilabel>Status Bar</guilabel> pane of the <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem> dialog box
	</para>

	</sect1>
	
	<sect1 id="editing"><title>Text Editing</title>
	
	<para>
	 Drag and drop of text is now supported in the text area; it can be disabled in the <guimenuitem>Mouse</guimenuitem> pane of the <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem> dialog box.
	</para>

	<para>
	 The <guimenu>Edit</guimenu>&gt;<guimenuitem>Complete Word</guimenuitem> command (shortcut:  <keycombo><keycap>Control</keycap><keycap>B</keycap></keycombo>) now looks in all visible buffers for completions. Also, the longest common prefix of the completions is inserted if there are multiple completions.
	</para>

	<para>
	 The new <guimenu>Edit</guimenu>&gt;<guimenuitem>More Clipboard</guimenuitem>&gt;<guimenuitem>Paste Deleted</guimenuitem> command (shortcut: <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>
	 <keycombo><keycap>Control</keycap><keycap>Y</keycap></keycombo>) lists the 20 most recently deleted strings of text. This list of deleted strings is also persistent.
	</para>
	
	<para>
	 Register contents are now saved between editing sessions.
	</para>

	<para>
	 The limit of 8 text areas editing a single buffer has been removed.
	</para>

	<para>
	 Fold start lines are now colored according to their nesting level in the text area. The colors can be customized in the <guilabel>Syntax Highlighting</guilabel> pane of the <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem> dialog box. <keycap>Alt</keycap>-clicking on a fold in the gutter (or clicking with the middle mouse button) now narrows to that fold.
	</para>

	<para>
	 When soft wrap is on, the text area now scrolls by screen lines, instead of scrolling by physical lines.
	</para>

	</sect1>

	<sect1 id="rect"><title>Rectangular Editing</title>

	<para>
	 <guimenu>Edit</guimenu>&gt;<guimenuitem>More Clipboard</guimenuitem>&gt;<guimenuitem>Vertical Paste</guimenuitem> command (shortcut: <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>
	 <keycombo><keycap>Control</keycap><keycap>P</keycap></keycombo>) behaves in a more intelligent manner. Entering characters while a rectangular selection is active inserts into each row of the selection, thus a zero-width rectangular selection can now act like a <quote>tall caret</quote>.
	</para>
	
	<para>
	 The new <guimenu>Edit</guimenu>&gt;<guimenuitem>More Selection</guimenuitem>&gt;<guimenuitem>Rectangular Selection</guimenuitem> command (shortcut: <keycombo><keycap>Alt</keycap><keycap>\</keycap></keycombo>) permits rectangular selections to be created using the keyboard. A static bar indicator is shown when rectangular selection mode is active.
	</para>
	
	<para>
	 Clicking beyond the end of a line in rectangular selection mode (or <keycap>Control</keycap>-clicking otherwise) inserts the appropriate amount of whitespace and moves the caret to the clicked location.
	</para>

	<para>
	 The rectangular selection now acts like a <quote>tall caret</quote>. Inserting text or pressing <keycap>Backspace</keycap> or <keycap>Delete</keycap> while a rectangular selection is active performs that operation on each selected line.
	</para>

	</sect1>

	<sect1 id="syntax"><title>Syntax Highlighting</title>
	 <para>
	  Many new syntax highlighting modes were added, and many existing ones were enhanced. jEdit now supports syntax highlighting for 133 languages.
	 </para>
	 <para>
	  The following new token types were added:
	 </para>
	 <itemizedlist>
	 <listitem><para>COMMENT3</para></listitem>
	 <listitem><para>COMMENT4</para></listitem>
	 <listitem><para>LITERAL3</para></listitem>
	 <listitem><para>LITERAL4</para></listitem>
	 <listitem><para>KEYWORD4</para></listitem>
	 </itemizedlist>
	 <para>
	  Any capture groups defined in the <literal>SPAN_REGEXP</literal>
	  element's <literal>BEGIN</literal> child are now substituted into the <literal>END</literal> child for matching purposes. This allows here-docs in languages such as Perl to be highlighted correctly.
	 </para>
	 <para>
	  A new <literal>NO_ESCAPE</literal> attribute has been added to the <literal>SPAN</literal> and <literal>SPAN_REGEXP</literal> elements.
	 </para>
	 <para>
	  A new <literal>IMPORT</literal> rule causes the current ruleset to inherit the rules from the given ruleset.
	 </para>
	 <para>
	  A background color defined for a ruleset's default token type now takes effect on tokens that appear inside this ruleset for which no explicit background color is defined.
	 </para>
	</sect1>

	<sect1 id="search"><title>Search and Replace</title>
	
	<para>
	 Added <guimenuitem>Ignore Case</guimenuitem> (shortcut: <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo> <keycombo><keycap>Control</keycap><keycap>I</keycap></keycombo>) and <guimenuitem>Regular Expressions</guimenuitem> (shortcut: <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo> <keycombo><keycap>Control</keycap><keycap>X</keycap></keycombo>) commands for toggling search bar settings from the keyboard.
	</para>

	<para>
	 The <guimenuitem>Incremental Search Bar</guimenuitem> and <guimenuitem>HyperSearch Bar</guimenuitem> commands in the <guimenu>Search</guimenu> menu no longer insert the currently selected text into the search bar. If you prefer this behavior, use <guimenuitem>Incremental Search for Word</guimenuitem> and <guimenuitem>HyperSearch for Word</guimenuitem> instead.
	</para>

	<para>
	 Clicking on a line in the <guimenuitem>HyperSearch Results</guimenuitem> window now selects all ocurrences of the search string in that line, not just the first occurrence.
	</para>

	</sect1>

	<sect1 id="files"><title>File Management</title>
	
	<para>
	 The handling of files that are changed on disk by another program is now more flexible. There are three possible behaviors that can be specified in the <guibutton>General</guibutton> pane of the <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem> dialog box:
	</para>

	<itemizedlist>
	 <listitem><para><guilabel>Do nothing</guilabel> - jEdit will not check if files are modified on disk by another program.</para></listitem>
	 <listitem><para><guilabel>Prompt</guilabel> - a dialog box will be shown listing all changed files, offering to reload them.</para></listitem>
	 <listitem><para><guilabel>Automatically reload</guilabel> - a dialog box will be shown listing all changed files, and they are all automatically reloaded.</para></listitem>
	</itemizedlist>

	<para>
	 When opening a symbolic link on Unix, the opened buffer has the path name of the link itself, not the file pointed by the link. However, it is still not possible to open the same buffer twice by opening two links to the same file.
	</para>

	</sect1>

	<sect1 id="encodings"><title>Handling of Multiple Encodings</title>
	
	<para>
	 A full list of encodings supported by your Java implementation is now shown in the file system browser's <guimenu>Commands</guimenu>&gt;<guimenuitem>Encoding</guimenuitem> menu and other places. Previously only a small list of common encodings was shown.
	</para>

	<para>
	 Files saved in the <literal>UTF-8Y</literal> encoding are now supported. This encoding is identical to <literal>UTF-8</literal> except there
	 is a three-byte signature (<literal>0xEFBBBF</literal>) at the beginning of the file.
	</para>

	<para>
	 UTF8-Y-encoded files are auto-detected as being such.
	</para>

	<para>
	 The encoding used by XML files is also auto-detected if the file provides an XML declaration like the following:
	</para>

	<programlisting><![CDATA[<?xml version="1.0" encoding="UTF-8"?>]]></programlisting>
	</sect1>

	<sect1 id="vfs.browser"><title>File System Browser</title>
	
	<para>
	 The file system browser now shows file details such as size, type, modification time and access permissions. Virtual file systems provided by plugins can add their own columns to the view.
	</para>

	<para>
	 The favorites list can now contain files, and a new <guimenu>Utilities</guimenu>&gt;<guisubmenu>Favorites</guisubmenu> menu allows accessing favorites without having to open the file system browser first.
	</para>

	<para>
	 File name completion in file dialog boxes has been greatly improved. It is now possible to navigate around the file system quite comfortably without using the mouse.
	</para>

	</sect1>

	<sect1 id="bundled-macros"><title>Bundled Macros</title>
	
	<para>
	 There are a number of new bundled macros, and most of the existing ones have undergone enhancements and bug fixes. jEdit 4.1 bundled 28 macros in 4 categories; jEdit 4.2 bundles 58 macros in 7 categories.
	</para>

	<para>
	  Of course you can create new macros of your own, either by recording actions or writing them from scratch.
	</para>

	</sect1>

	</chapter>
	
	<chapter id="api-changes"><title>API Changes</title>
	
	<sect1 id="beanshell"><title>BeanShell</title>

	<para>
		BeanShell has been updated from version 1.2b7 to 2.0b1. The
		new release of BeanShell brings support for scripted
		classes, static imports, mixins, better
		error reporting, improved performance, and various fixes.
	</para>

	<para>
		A number of jEdit-specific changes are also present in this
		BeanShell version; they will eventually be merged back into
		the main BeanShell source tree.
	</para>

	<para>
		A new preset BeanShell variable, <varname>wm</varname> is set to the
		<function>view.getDockableWindowManager()</function>.
	</para>


	<para>
		Previously plugins that wanted to provide BeanShell scripting
		commands had to source a BeanShell script on startup. This was
		slow. Now, BeanShell supports a <quote>command path</quote>.
		When an unresolved method name is entered, the command path is
		consulted for the method definition. Entries are added to the
		command path using the following method of the
		<ulink
		url="../api/org/gjt/sp/jedit/NameSpace.html">NameSpace</ulink>
		class:
	</para>

	<para>
		<funcsynopsis>
		<funcprototype>
		<funcdef>void <function>addCommandPath</function></funcdef>
		<paramdef>String <parameter>path</parameter></paramdef>
		<paramdef>Class <parameter>clas</parameter></paramdef>
		</funcprototype>
		</funcsynopsis>
	</para>

	<para>
		For example, if your plugin provides commands in the
		<filename>commands</filename> directory of the JAR file, you
		could call something like this:
	</para>

	<programlisting>BeanShell.getNameSpace().addCommandPath("/commands/",
    MyPlugin.class);</programlisting>

	</sect1>
	
	<sect1 id="plugin-api"><title>Dynamic Plugin Loading</title>

	<para>
		In jEdit 4.1 and earlier, plugins are always fully loaded at program
		startup, and unloaded at program shutdown. While the plugin loader and
		API was very simple as a result, this scheme had two main
		disadvantages:
	</para>

	<itemizedlist>
		<listitem><para>Having a large number of plugins generally slowed down
		jEdit startup, since many plugins performed a lot of lengthy
		initialization.
		Even if all plugins made their <function>start()</function>
		methods as quick as possible, there would still be the overhead of
		scanning the JAR files, loading the plugin classes, and so on.</para>
		</listitem>
		<listitem><para>There was no way to reload plugins in a running jEdit
		instance. This made plugin development and use of the plugin manager
		a bit cumbersome.</para>
		</listitem>
	</itemizedlist>

	<para>
		Through a stroke of insight, one notices that the only
		functions called from most plugins' <function>start()</function>
		methods fall into two categories:
	</para>

	<itemizedlist>
		<listitem><para>Registration of virtual file systems, fold handlers,
		macro handlers, Console shells, SideKick parsers, ...</para>
		</listitem>
		<listitem><para>Arbitriary initialization that only needs to be
		done when the plugin is first invoked by the user, and not at
		program startup.</para></listitem>
	</itemizedlist>
	
	<para>
		jEdit 4.2 moves the former task out of the <function>start()</function>
		method and into a file within the JAR that can be parsed quickly. This
		allows the plugin core class to only be loaded, and its
		<function>start()</function> method called, only when
		the plugin is first invoked. Note that the <function>start()</function>
		method is always called from the event dispatch thread (or from
		the main thread if the GUI has not yet been loaded). Therefore you
		do not need to worry about thread-safety issues.
	</para>
	
	<para>
		Also, plugins can now be loaded and unloaded at runtime.
	</para>
	
	</sect1>

	<sect1 id="class-editplugin"><title>EditPlugin Class Changes</title>
	
	<para>
		Documentation for the properties mentioned below, and their possible values,
		can be found in the
		documentation for the <ulink
		url="../api/org/gjt/sp/jedit/EditPlugin.html">EditPlugin</ulink> class.
	</para>

	<para>
		jEdit distinguishes between jEdit 4.1 and 4.2-style plugins by checking
		for the presence of a single property,
		<property>plugin.<replaceable>class
		name</replaceable>.activate</property>. If this property is present, the
		plugin is loaded using the new API.
	</para>

	<para>
		Since the plugin's menu might need to be displayed before its core class
		is fully loaded, there is a new way of specifying the plugin menu using
		properties; the <function>createMenuItems()</function> method of the
		<ulink
		url="../api/org/gjt/sp/jedit/EditPlugin.html">EditPlugin</ulink>
		class has been deprecated.
	</para>

	<para>
		For example, the jEdit 4.1 version of the QuickNotepad plugin had the
		following <function>createMenuItems()</function> method:
	</para>

	<programlisting>public void createMenuItems(Vector menuItems)
{
    menuItems.addElement(GUIUtilities.loadMenu("quicknotepad.menu"));
}</programlisting>

	<para>
		Additionally, the following two properties were defined in
		<filename>QuickNotepad.props</filename>:
	</para>

	<programlisting>quicknotepad.menu.label=QuickNotepad
quicknotepad.menu=quicknotepad - quicknotepad.choose-file \
    quicknotepad.save-file quicknotepad.copy-to-buffer</programlisting>

	<para>
		The jEdit 4.2 version of this plugin no longer has a
		<function>createMenuItems()</function> method, and instead defines the
		following property:
	</para>

	<programlisting>plugin.QuickNotepadPlugin.menu=quicknotepad \
    - \
    quicknotepad.choose-file \
    quicknotepad.save-file \
    quicknotepad.copy-to-buffer</programlisting>

	<para>
		Note that specifying a <property>.label</property> property for the menu
		is no longer necessary, as the label becomes the name of the plugin.
	</para>

	<para>
		If the content of your plugin's menu is determined at runtime, you must
		use the new dynamic menu API by defining a property like so:
	</para>

	<programlisting>plugin.MyPlugin.menu.code=new MyPluginMenuProvider();</programlisting>

	<para>
		The value of the property is a BeanShell snippet that should evaluate to a
		<ulink
		url="../api/org/gjt/sp/jedit/menu/DynamicMenuProvider.html">DynamicMenuProvider</ulink>
		instance.
	</para>

	<para>
		Similarly, option panes should are now specified using properties, and
		the <function>createOptionPanes()</function> method of the
		<ulink
		url="../api/org/gjt/sp/jedit/EditPlugin.html">EditPlugin</ulink>
		class has been deprecated.
	</para>

	<para>
		In QuickNotepad's case, the <function>createOptionPanes()</function>
		method has been removed:
	</para>

	<programlisting>public void createOptionPanes(OptionsDialog od)
    {
        od.addOptionPane(new QuickNotepadOptionPane());
    }</programlisting>

	<para>
		The new properties look like this:
	</para>

	<programlisting>plugin.QuickNotepadPlugin.option-pane=quicknotepad
options.quicknotepad.code=new QuickNotepadOptionPane();</programlisting>

	</sect1>

	<sect1 id="actions"><title>Actions</title>
	
	<para>
		The syntax of the <filename>actions.xml</filename> file has not changed.
	</para>

	<para>
		A few methods of the <ulink
		url="../api/org/gjt/sp/jedit/EditAction.html">EditAction</ulink>
		class were made
		final, since these three values must be known even if the action
		instance in question has not been loaded:
	</para>
	
	<itemizedlist>
		<listitem><para><function>getLabel()</function></para></listitem>
		<listitem><para><function>isToggle()</function></para></listitem>
		<listitem><para><function>getMouseOverText()</function></para></listitem>
	</itemizedlist>
	
	<para>
		This change does not affect plugins that define actions using an
		<filename>actions.xml</filename> file. However, if your plugin creates
		action instances dynamically, you will need to make calls like the
		following instead of overriding these methods:
	</para>

	<programlisting>jEdit.setTemporaryProperty("<replaceable>action name</replaceable>.label",
    "<replaceable>Hello World</replaceable>");
jEdit.setTemporaryProperty("<replaceable>action name</replaceable>.toggle",
    "<replaceable>true or false</replaceable>");
jEdit.setTemporaryProperty("<replaceable>action name</replaceable>.mouse-over",
    "<replaceable>some string</replaceable>");</programlisting>

	<para>
		Make sure to use <function>jEdit.setTemporaryProperty()</function> and
		not <function>jEdit.setProperty()</function> since the latter will save
		the values to the user properties file, which is probably not what you
		want.
	</para>

	<para>
		The <function>jEdit.getActions()</function> method has been
		deprecated, since it must load all plugin <filename>actions.xml</filename>
		files in order to return an array of <ulink
		url="../api/org/gjt/sp/jedit/EditAction.html">EditAction</ulink>
		instances. Use <function>jEdit.getActionNames()</function> instead,
		which returns an array of strings.
	</para>

	<para>
		A new abstract method was added to the <ulink
		url="../api/org/gjt/sp/jedit/gui/InputHandler.html">InputHandler</ulink>
		class:
	</para>
	
	<para>
		<funcsynopsis>
		<funcprototype>
		<funcdef>void <function>addKeyBinding</function></funcdef>
		<paramdef>String <parameter>keyBinding</parameter></paramdef>
		<paramdef>String <parameter>action</parameter></paramdef>
		</funcprototype>
		</funcsynopsis>
	</para>

	<para>
		The <function>removeKeyBinding()</function> method of the <ulink
		url="../api/org/gjt/sp/jedit/gui/DefaultInputHandler.html">DefaultInputHandler</ulink>
		class has finally been implemented. Previously it always threw
		an <classname>InternalError</classname> when invoked.
	</para>

	</sect1>

	<sect1 id="dockables"><title>Dockable Windows</title>
	
	<para>
		The syntax of the <filename>dockables.xml</filename> file has not changed.
	</para>

	<para>
		Instead of overriding the deprecated
		<function>JComponent.requestDefaultFocus()</function> method,
		dockable windows can now implement the new <ulink
		url="../api/org/gjt/sp/jedit/gui/DefaultFocusComponent.html">DefaultFocusComponent</ulink>
		interface and its
		<function>focusOnDefaultComponent()</function> method.
	</para>

	</sect1>

	<sect1 id="services"><title>Services</title>
	
	<para>
		A new <filename>services.xml</filename> file can be provided in the
		plugin JAR file. The preferred way of adding virtual file systems, fold
		handlers and many other types of extensions is through this file. Its
		syntax is described in the documentation for the <ulink
		url="../api/org/gjt/sp/jedit/ServiceManager.html">ServiceManager</ulink>
		class.
	</para>

	</sect1>

	<sect1 id="vfs"><title>Virtual File Systems</title>
	
	<para>
		Instead of calling <function>VFSManager.registerVFS()</function> in your
		plugin's <function>start()</function> method, add entries in the
		<filename>services.xml</filename> file that look like so:
	</para>

	<programlisting><![CDATA[<SERVICE CLASS="org.gjt.sp.jedit.io.VFS" NAME="ftp">
    new ftp.FtpVFS(false);
</SERVICE>]]></programlisting>

	<para>
		A new  <ulink
		url="../api/org/gjt/sp/jedit/io/VFS.DirectoryEntryCompare.html">VFS.DirectoryEntryCompare</ulink>
		class was added,
		for sorting lists of VFS directory entries.
	</para>

	<para>
		Fields named <varname>canRead</varname> and <varname>canWrite</varname>
		were added to the <ulink
		url="../api/org/gjt/sp/jedit/io/VFS.DirectoryEntry.html">VFS.DirectoryEntry</ulink>
		class.
	</para>

	<para>
		There is a new extended attribute API to go with the details view in the
		file system browser. Pass an array of extended attribute names to the
		<ulink
		url="../api/org/gjt/sp/jedit/io/VFS.html">VFS</ulink> constructor, then
		provide an implementation
		of the <function>getExtendedAttribute()</function> method in your
		subclass of <ulink
		url="../api/org/gjt/sp/jedit/io/VFS.DirectoryEntry.html">VFS.DirectoryEntry</ulink>.
	</para>

	<para>
		The following two methods in the <ulink
		url="../api/org/gjt/sp/jedit/io/VFSManager.html">VFSManager</ulink>
		class have been deprecated since they can no longer be implemented for
		file systems using the deferred loading API
	</para>

	<itemizedlist>
		<listitem><para><function>getVFSByName()</function> - use
		<function>getVFSForProtocol()</function>
		instead.</para></listitem>
		<listitem><para><function>getFilesystems()</function> - use
		<function>getVFSs()</function>, which returns a string array,
		instead.</para></listitem>
	</itemizedlist>

	</sect1>

	<sect1 id="extensions"><title>Text Area Extensions</title>

	<para>
		The API for text area extensions is still the same, however you
		must make sure your plugin correctly adds itself to existing
		text areas when it is loaded after jEdit startup, and that it
		removes itself from open views if it is unloaded before jEdit
		exits.
	</para>

	<para>
		A new method was added to the <ulink
		url="../api/org/gjt/sp/jedit/textarea/TextAreaExtension.html">TextAreaExtension</ulink>
		class:
	</para>

	<para>
		<funcsynopsis>
		<funcprototype>
		<funcdef>void <function>paintScreenLineRange</function></funcdef>
		<paramdef>Graphics2D <parameter>gfx</parameter></paramdef>
		<paramdef>int <parameter>firstLine</parameter></paramdef>
		<paramdef>int <parameter>lastLine</parameter></paramdef>
		<paramdef>int[] <parameter>physicalLines</parameter></paramdef>
		<paramdef>int[] <parameter>start</parameter></paramdef>
		<paramdef>int[] <parameter>end</parameter></paramdef>
		<paramdef>int <parameter>y</parameter></paramdef>
		<paramdef>int <parameter>lineHeight</parameter></paramdef>
		</funcprototype>
		</funcsynopsis>
	</para>

	<para>
		See the class documentation for information on each parameter.
	</para>

	<para>
		You can override this method to paint a range of
		lines at once, instead of having to respond to each individual
		<function>paintValidLine()</function> and
		<function>paintInvalidLine</function> call.
	</para>

	<para>
		While for many text area extensions using this method will result
		in no speedup, some like the error highlight in the ErrorList
		plugin become more efficient. The error highlight searches an
		array each time it has to paint a line. Previously the array
		was searched for each line painted in screen. Using this method,
		it is possible to search the array only once when painting a
		range of lines.
	</para>

	</sect1>

	<sect1 id="syntax-api"><title>Syntax Highlighting</title>
	
	<para>
		The <classname>org.gjt.sp.jedit.syntax</classname> package can now
		be used in other programs.
		All you need to provide is error handling and logic for locating
		the XML mode files. See the
		<ulink url="../api/org/gjt/sp/jedit/syntax/package-summary.html">package
		documentation</ulink> for details.
	</para>

	</sect1>

	<sect1 id="textarea-api"><title>Text Area and Folding</title>

	<para>The
		<ulink
		url="../api/org/gjt/sp/jedit/textarea/JEditTextArea.html">JEditTextArea</ulink>
		class has a new <function>addToLeftOfScrollBar()</function> method that
		adds a component to the left of the scroll bar. Previously plugins like
		JDiff had to resort to undocumented hacks to do this.
	</para>

	<para>
		The code that displays lines of text on screen has been overhauled for
		improved performance and correctness. As a result, two methods in
		<ulink
		url="../api/org/gjt/sp/jedit/textarea/JEditTextArea.html">JEditTextArea</ulink>
		that have been deprecated since jEdit 4.0 were removed:
	</para>

	<itemizedlist>
		<listitem><para><function>xToOffset()</function></para>
		</listitem>
		<listitem><para><function>offsetToX()</function></para>
		</listitem>
	</itemizedlist>

	<para>
		As in jEdit 4.0 and 4.1, the <function>xyToOffset()</function> and
		<function>offseToXY()</function> methods replace these two.
	</para>

	<para>
		Also, the way folds are handled has changed. The
		<classname>FoldVisibilityManager</classname> class has been removed,
		and a number of methods in the <ulink
		url="../api/org/gjt/sp/jedit/textarea/JEditTextArea.html">JEditTextArea</ulink>
		class have been removed also:
	</para>

	<itemizedlist>
		<listitem><para><function>virtualToPhysical()</function></para>
		</listitem>
		<listitem><para><function>physicalToVirtual()</function></para>
		</listitem>
		<listitem><para><function>getVirtualLineCount()</function></para>
		</listitem>
	</itemizedlist>

	<para>
		The replacement for the <classname>FoldVisibilityManager</classname>
		class is a class named <ulink
		url="../api/org/gjt/sp/jedit/io/DisplayManager.html">DisplayManager</ulink>,
		with a similar but not identical API.
	</para>

	<para>
		Previously, a <quote>virtual line number</quote> was a line number such
		that each physical line (delimited by <literal>\n</literal>) counted
		as 1 if it was visible, and 0 if it was not. They did not take into
		account lines that were split on screen as a result of soft wrap, and
		this made the soft wrap scrolling code rather complicated.
	</para>

	<para>
		In jEdit 4.2, virtual line numbers are no longer used internally; now,
		similar <quote>scroll line numbers</quote> are used. Scroll line numbers
		take both hidden lines and soft wrap into account. The
		<function>getFirstLine()</function> and
		<function>setFirstLine()</function> methods of the
		<ulink
		url="../api/org/gjt/sp/jedit/textarea/JEditTextArea.html">JEditTextArea</ulink>
		class now work with
		scroll line numbers.
	</para>

	<para>
		An internal API for converting between scroll line numbers and physical
		line numbers exists, but it is rather complicated and it will not be
		made public. Instead, if you want the text area to scroll to a given
		physical line number, use the new
		<function>setFirstPhysicalLine()</function> method in the
		<ulink
		url="../api/org/gjt/sp/jedit/textarea/JEditTextArea.html">JEditTextArea</ulink>
		class.
	</para>

	<para>
		Instead of calling <function>FoldHandler.registerFoldHandler()</function>
		in your
		plugin's <function>start()</function> method, add entries in the
		<filename>services.xml</filename> file that look like so:
	</para>

	<programlisting><![CDATA[<SERVICE CLASS="org.gjt.sp.jedit.buffer.FoldHandler" NAME="sidekick">
    new sidekick.SideKickFoldHandler()
</SERVICE>]]></programlisting>

	</sect1>

	<sect1 id="misc-api-changes"><title>Miscellaneous API Changes</title>
	
	<para>
		A new <function>View.goToBuffer()</function> method has been added.
		If the specified buffer is already
		visible in one of the view's edit panes, it sends focus to that edit
		pane. Otherwise, it calls <function>setBuffer()</function>
		on the current edit pane.
	</para>

	<para>
		The constructor of the <ulink
		url="../api/org/gjt/sp/jedit/io/EBMessage.html">EBMessage</ulink> class
		now takes
		an <classname>Object</classname>, as opposed to an
		<ulink
		url="../api/org/gjt/sp/jedit/io/EBComponent.html">EBComponent</ulink>.
		Plugins that provide custom message
		types will need to be recompiled.
	</para>
	
	<para>
		The following deprecated method was removed from the
		<ulink
		url="../api/org/gjt/sp/jedit/io/GUIUtilities.html">GUIUtilities</ulink>
		class:
	</para>
	
	<para>
		<funcsynopsis>
		<funcprototype>
		<funcdef>void <function>loadMenu</function></funcdef>
		<paramdef>View <parameter>view</parameter></paramdef>
		<paramdef>String <parameter>name</parameter></paramdef>
		</funcprototype>
		</funcsynopsis>
	</para>

	</sect1>

	</chapter>
	
</book>