Overview

# Introduction

## What do the Dates Mean?

The supplied dates indicate when the API change was made, on the CVS trunk. From this you can generally tell whether the change should be present in a given build or not; for trunk builds, simply whether it was made before or after the change; for builds on a stabilization branch, whether the branch was made before or after the given date. In some cases corresponding API changes have been made both in the trunk and in an in-progress stabilization branch, if they were needed for a bug fix; this ought to be marked in this list.

- The `release41` branch was made on Apr 03 '05 for use in the NetBeans 4.1 release. Specification versions: 6.0 begins after this point.
- The `release40` branch was made on Nov 01 '04 for use in the NetBeans 4.0 release. Specification versions: 5.0 begins after this point.

# Index of APIs

- Text API

# Incompatible changes by date

Fuller descriptions of all changes can be found below (follow links).

Not all deprecations are listed here, assuming that the deprecated APIs continue to essentially work. For a full deprecation list, please consult the Javadoc.

- (Jan 14 '05) `CloneableEditorSupport.notifyModified` is called only on first modification
- (Apr 2 '03) PositionRef.getEditorSupport() removed
- (Apr 2 '03) Line.getDataObject() removed
- (Apr 2 '03) Line constructor changed

# All changes by date

- (Oct 31 '05) Added CloneableEditorSupport.messageHtmlName method
- (Aug 9 '05) Added ActiveEditorDrop interface
- (Jul 22 '05) Added CloneableEditorSupport.wrapEditorComponent
- (Jul 18 '05) Annotation type extended with `severity`, `custom_sidebar_color`, `browsable` and `priority` attributes
- (Mar 21 '05) Added a new constant `Line.SHOW_TOFRONT`
- (Jan 14 '05) `CloneableEditorSupport.notifyModified` is called only on first modification
- (Dec 6 '04) CloneableEditor.openAt made protected
- (Aug 24 '04) Enhance SPI interface for CloneableEditorSupport.Pane providers
- (Jun 8 '04) Line.getOriginalLineNumber
- (Apr 30 '04) Support for AnnotationProvider interface
- (Apr 20 '04) Allow custom toolbar for NbDocument impls, editor panes separation in editor support classes
- (Feb 2 '04) Allow CloneableEditorSupport subclasses to specify persistence ID for the associated editor TopComponent.
- (Jun 26 '03) New `getInputStream()` method in CloneableEditorSupport
- (Apr 18 '03) CloneableEditorSupport takes Lookup for its Lines in constructor
- (Apr 2 '03) PositionRef.getEditorSupport() removed
- (Apr 2 '03) Line.getDataObject() removed
- (Apr 2 '03) Line constructor changed
- (Apr 2 '03) CloneableEditorSupport can provide display name for its Lines
- (Oct 31 '01) Added to javadoc an `IndexOutOfBoundsException` can be thrown from `NbDocument.findLineOffset` method
- (Oct 12 '01) Notifications about annotation attaching/detaching added
- (Sep 25 '01) Get content of Annotatable
- (Sep 25 '01) Annotatable.isDeleted and Annotatable.getAnnotationCount are final
- (Jul 9 '01) `Line` methods deprecated in favor of annotations
- (Jul 9 '01) New annotations API published
- (Dec 1 '00) Customization of editor support after creation
- (Jul 21 '00) Can control undo/redo on editor supports
- (Jul 17 '00) Can control title format for editor supports
- (Jun 23 '00) `IndentEngine` a service type
- (May 29 '00) Refactoring of editor and open supports
- (Mar 27 '00) Setting colors for lines deprecated
- (Feb 24 '00) `PrintSettings.getPageFormat` requires a printer job

# Changes by version

These API specification versions may be used to indicate that a module requires a certain API feature in order to function. For example, if you see here a feature you need which is labelled `1.20`, your manifest should contain in its main attributes the line:

    OpenIDE-Module-Module-Dependencies: org.openide.text > 1.20

- (6.8) Added CloneableEditorSupport.messageHtmlName method
- (6.6) Added ActiveEditorDrop interface
- (6.4) Added CloneableEditorSupport.wrapEditorComponent
- (6.3) Annotation type extended with `severity`, `custom_sidebar_color`, `browsable` and `priority` attributes
- (5.8) Added a new constant `Line.SHOW_TOFRONT`
- (5.4) `CloneableEditorSupport.notifyModified` is called only on first modification
- (5.2) CloneableEditor.openAt made protected
- (4.45) Enhance SPI interface for CloneableEditorSupport.Pane providers
- (4.38) Line.getOriginalLineNumber
- (4.31) Allow custom toolbar for NbDocument impls, editor panes separation in editor support classes
- (4.30) Support for AnnotationProvider interface
- (4.24) Allow CloneableEditorSupport subclasses to specify persistence ID for the associated editor TopComponent.
- (4.7) New `getInputStream()` method in CloneableEditorSupport
- (4.5) CloneableEditorSupport takes Lookup for its Lines in constructor
- (4.3) PositionRef.getEditorSupport() removed
- (4.3) Line.getDataObject() removed
- (4.3) Line constructor changed
- (4.3) CloneableEditorSupport can provide display name for its Lines
- (1.38) Notifications about annotation attaching/detaching added
- (1.35) Get content of Annotatable
- (1.35) Annotatable.isDeleted and Annotatable.getAnnotationCount are final
- (1.20) `Line` methods deprecated in favor of annotations
- (1.20) New annotations API published

# Changes by affected class

## `org.openide.text.ActiveEditorDrop`

- (Aug 9 '05) Added ActiveEditorDrop interface

## `org.openide.text.Annotatable`

- (Sep 25 '01) Get content of Annotatable
- (Sep 25 '01) Annotatable.isDeleted and Annotatable.getAnnotationCount are final
- (Jul 9 '01) New annotations API published

## `org.openide.text.Annotation`

- (Oct 12 '01) Notifications about annotation attaching/detaching added
- (Jul 9 '01) New annotations API published

## `org.openide.text.AnnotationProvider`

- (Apr 30 '04) Support for AnnotationProvider interface

## `org.openide.text.CloneableEditor`

- (Oct 31 '05) Added CloneableEditorSupport.messageHtmlName method
- (Jul 22 '05) Added CloneableEditorSupport.wrapEditorComponent
- (Apr 20 '04) Allow custom toolbar for NbDocument impls, editor panes separation in editor support classes
- (May 29 '00) Refactoring of editor and open supports

## `org.openide.text.CloneableEditorSupport`

- (Oct 31 '05) Added CloneableEditorSupport.messageHtmlName method
- (Jul 22 '05) Added CloneableEditorSupport.wrapEditorComponent
- (Jan 14 '05) `CloneableEditorSupport.notifyModified` is called only on first modification
- (Dec 6 '04) CloneableEditor.openAt made protected
- (Apr 20 '04) Allow custom toolbar for NbDocument impls, editor panes separation in editor support classes
- (Feb 2 '04) Allow CloneableEditorSupport subclasses to specify persistence ID for the associated editor TopComponent.
- (Jun 26 '03) New `getInputStream()` method in CloneableEditorSupport
- (Apr 18 '03) CloneableEditorSupport takes Lookup for its Lines in constructor
- (Apr 2 '03) CloneableEditorSupport can provide display name for its Lines
- (Dec 1 '00) Customization of editor support after creation
- (Jul 21 '00) Can control undo/redo on editor supports
- (Jul 17 '00) Can control title format for editor supports
- (May 29 '00) Refactoring of editor and open supports

## `org.openide.windows.CloneableOpenSupport`

- (May 29 '00) Refactoring of editor and open supports

## `org.openide.text.DataEditorSupport`

- (Oct 31 '05) Added CloneableEditorSupport.messageHtmlName method
- (Apr 2 '03) PositionRef.getEditorSupport() removed
- (Apr 2 '03) Line.getDataObject() removed

## `org.openide.text.DocumentLine`

- (Apr 2 '03) Line constructor changed
- (Jul 9 '01) `Line` methods deprecated in favor of annotations

## `org.openide.text.EditorSupport`

- (Apr 20 '04) Allow custom toolbar for NbDocument impls, editor panes separation in editor support classes
- (May 29 '00) Refactoring of editor and open supports

## `org.openide.text.IndentEngine`

- (Jun 23 '00) `IndentEngine` a service type

## `org.openide.text.Line`

- (Mar 21 '05) Added a new constant `Line.SHOW_TOFRONT`
- (Jun 8 '04) Line.getOriginalLineNumber
- (Apr 2 '03) Line.getDataObject() removed
- (Apr 2 '03) Line constructor changed
- (Jul 9 '01) `Line` methods deprecated in favor of annotations

## `org.openide.text.NbDocument`

- (Apr 20 '04) Allow custom toolbar for NbDocument impls, editor panes separation in editor support classes
- (Oct 31 '01) Added to javadoc an `IndexOutOfBoundsException` can be thrown from `NbDocument.findLineOffset` method
- (Jul 9 '01) New annotations API published
- (Mar 27 '00) Setting colors for lines deprecated

## `org.openide.loaders.OpenSupport`

- (May 29 '00) Refactoring of editor and open supports

## `org.openide.text.PositionRef`

- (Apr 2 '03) PositionRef.getEditorSupport() removed

## `org.openide.text.PrintSettings`

- (Feb 24 '00) `PrintSettings.getPageFormat` requires a printer job

# Details of all changes by API and date

## Text API

### Added CloneableEditorSupport.messageHtmlName method

Oct 31 '05; API spec. version: 6.8; affected top-level classes: `CloneableEditorSupport` `CloneableEditor` `org.openide.text.DataEditorSupport`; made by: dsimonek; issues: #66777

A `messageHtmlName` method has been added to CloneableEditorSupport to allow for display names with html tags. CloneableEditor uses this new method to set its html display name correctly. Also `DataEditorSupport` now overrides `messageHtmlName` to connect with `Node.getHtmlDisplayName`.

### Added ActiveEditorDrop interface

Aug 9 '05; API spec. version: 6.6; affected top-level classes: `ActiveEditorDrop`; made by: mroskanin; issues: #61367

An `ActiveEditorDrop` interface has been added due to drag and drop callback support described at issue #61367

### Added CloneableEditorSupport.wrapEditorComponent

Jul 22 '05; API spec. version: 6.4; affected top-level classes: `CloneableEditorSupport` `CloneableEditor`; made by: abadea; issues: #60922

A `wrapEditorComponent` method has been added to CloneableEditorSupport allowing to wrap the editor component in another component.

### Annotation type extended with `severity`, `custom_sidebar_color`, `browsable` and `priority` attributes

Jul 18 '05; API spec. version: 6.3; issues: #55639
Annotation type was extended with `severity`, `custom_sidebar_color`, `browsable` and `priority` attributes.

### Added a new constant `Line.SHOW_TOFRONT`

Mar 21 '05; API spec. version: 5.8; affected top-level classes: `Line`; issues: #47825
The new constant is used in the `EditorSupportLineSet` and brings editor's parent `Window` to be fronted above all other top-level windows.

### `CloneableEditorSupport.notifyModified` is called only on first modification

Jan 14 '05; API spec. version: 5.4; affected top-level classes: `CloneableEditorSupport`; made by: jtulach; issues: #52493

It has been found that `CloneableEditorSupport.notifyModified` is called more often than it should. It used to be called after every keystroke, which is bad, as its return value could not be honored - it is not possible to prevent modification when the document is already modified. Now the method is called only on first modification of the document and if it returns false, the modification is not allowed.
This may be incompatible for clients that relied on the often calls. Such clients need to be fixed.

### CloneableEditor.openAt made protected

Dec 6 '04; API spec. version: 5.2; affected top-level classes: `CloneableEditorSupport`; made by: pnejedly; issues: #51441

Deprecated `EditorSupport` has had a method `openAt`, which has no easy replacement in `CloneableEditorSupport`. The method is implemented in `CloneableEditorSupport`, but is package private. This change makes it protected.

### Enhance SPI interface for CloneableEditorSupport.Pane providers

Aug 24 '04; API spec. version: 4.45; made by: mleint; issues: #46127
Additional method to `CloneableEditorSupport.Pane` interface, `Pane.ensureVisible()`. The implementing classes should ensure that the pane's component is open and visible after calling this method. Is used in `CloneableEditorSupport.openAt()`.

### Line.getOriginalLineNumber

Jun 8 '04; API spec. version: 4.38; affected top-level classes: `Line`; made by: jtulach; issues: #43484
A method that for a given line computes its original line number. Is useful when user edits text and places a breakpoint to find out what was the original line that the breakpoint should be placed to.

### Support for AnnotationProvider interface

Apr 30 '04; API spec. version: 4.30; affected top-level classes: `AnnotationProvider`; made by: pnejedly; issues: #41345

- Added interface org.openide.text.AnnotationProvider
- Call all instances of the interface found in the global lookup when going to visualize given Annotatable.

### Allow custom toolbar for NbDocument impls, editor panes separation in editor support classes

Apr 20 '04; API spec. version: 4.31; affected top-level classes: `NbDocument` `CloneableEditorSupport` `CloneableEditor` `org.openide.text.EditorSupport`; made by: mkleint; issues: #41085
In order to implement MultiViews, these changes were necessary to the org.openide.text package.

- Added new subinterface to NbDocument -> NbDocument.CustomToolbar which lets the implementors to define a custom toolbar. It allows to present the toolbar in different environments (eg. multiviews)
- CloneableEditorSupport defined a new interface CloneableEditorSupport.Pane and has a new protected method createPane()
- The deprecated EditorSupport has a new protected method createPane()
- CloneableEditor implements CloneableEditorSupport.Pane, thus updateTitle was changed from protected to public and 2 additional methods from Pane interfacewere added

### Allow CloneableEditorSupport subclasses to specify persistence ID for the associated editor TopComponent.

Feb 2 '04; API spec. version: 4.24; affected top-level classes: `CloneableEditorSupport`; made by: pnejedly; issues: #37892
Adding protected `CloneableEditorSupport.documentID` to allow subclasses to compute preferred ID String used for TopComponent persistence.

### New `getInputStream()` method in CloneableEditorSupport

Jun 26 '03; API spec. version: 4.7; affected top-level classes: `CloneableEditorSupport`; made by: pjiricka; issues: #34692
New method that returns an InputStream which reads the current data from the editor, taking into account the encoding of the file. The returned InputStream contains the same data as if the file was written out to the disk. Useful when interacting with a tool that expects an InputStream, and the current (possibly modified) content of the editor is desired.

### CloneableEditorSupport takes Lookup for its Lines in constructor

Apr 18 '03; API spec. version: 4.5; affected top-level classes: `CloneableEditorSupport`; made by: jtulach; issues: #32937
Allows subclasses of the support DataEditorSupport, etc. pass additional information to each of its Lines. Such information can consist of location like DataObject or FileObject.

### PositionRef.getEditorSupport() removed

Apr 2 '03; API spec. version: 4.3; affected top-level classes: `PositionRef` `org.openide.text.DataEditorSupport`; made by: jtulach; issues: #32143
For a long time deprecated `PositionRef.getEditorSupport()` method has been removed to enabled separation of EditorSupport to openide-loaders.jar

### Line.getDataObject() removed

Apr 2 '03; API spec. version: 4.3; affected top-level classes: `Line` `org.openide.text.DataEditorSupport`; made by: jtulach; issues: #32143
Due to separation of openide-loaders.jar the `Line.getDataObject()` method had to be removed and replaced by `Line.getLookup` which provides more general way for providing line context. The direct replacement for the old method is `DataObject DataEditorSupport.findDataObject(Line)`.

### Line constructor changed

Apr 2 '03; API spec. version: 4.3; affected top-level classes: `Line` `DocumentLine`; made by: jtulach; issues: #32143
Due to separation of openide-loaders.jar the `Line` and `DocumentLine` constructors taking DataObject had to be modified to take Lookup or plain Object instead.

### CloneableEditorSupport can provide display name for its Lines

Apr 2 '03; API spec. version: 4.3; affected top-level classes: `CloneableEditorSupport`; made by: jtulach; issues: #32143
Added method `String messageLine (Line)` that can be overriden to provide meaningful display name for lines produced by this support.

### Added to javadoc an `IndexOutOfBoundsException` can be thrown from `NbDocument.findLineOffset` method

Oct 31 '01; affected top-level classes: `NbDocument`; issues: #17144
Added declaration to javadoc of the method `NbDocument.findLineOffset()` can throw an unchecked `IndexOutOfBoundsException`. The method could throw the exception also before (and also other kinds of them see the issue), but it was not declared in javadoc. This change makes it compliant to use with standard Swing text package and also with `Line.Set.getCurrent()` method.

### Notifications about annotation attaching/detaching added

Oct 12 '01; API spec. version: 1.38; affected top-level classes: `Annotation`
Added protected methods `Annotation.notifyAttached()` and `Annotation.notifyDetached()`.

### Get content of Annotatable

Sep 25 '01; API spec. version: 1.35; affected top-level classes: `Annotatable`
Added public abstract method `Annotatable.getText()`. Listeners can be attached to Annotatable.PROP_TEXT property.

### Annotatable.isDeleted and Annotatable.getAnnotationCount are final

Sep 25 '01; API spec. version: 1.35; affected top-level classes: `Annotatable`
The Annotatable.isDeleted and Annotatable.getAnnotationCount are final now.
Compatibility: This is not considered as incompatible change, because the API with these methods was not published yet.

### `Line` methods deprecated in favor of annotations

Jul 9 '01; API spec. version: 1.20; affected top-level classes: `Line` `DocumentLine`
Because of publication of Annotation API, all previously used methods like `setBreakpoint`, `isBreakpoint`, `markError`, `unmarkError`, `markCurrentLine`, `unmarkCurrentLine`, and `canBeMarkedCurrent` are deprecated. Use `Annotation.attach()` and `detach()` instead. `Line` now extends `Annotatable` abstract class.

### New annotations API published

Jul 9 '01; API spec. version: 1.20; affected top-level classes: `Annotation` `Annotatable` `NbDocument`
Annotation API was published.
Compatibility: Because of publication of Annotation API, all previously used `NbDocument` methods like `markError`, `markCurrent`, `markNormal` are deprecated. Use `addAnnotation` and `removeAnnotation` instead.

### Customization of editor support after creation

Dec 1 '00; affected top-level classes: `CloneableEditorSupport`; made by:
Added method `initializeCloneableEditor` to allow easier customization of the editor after creation and also after deserialization.

### Can control undo/redo on editor supports

Jul 21 '00; affected top-level classes: `CloneableEditorSupport`
`getUndoRedo()` method was made protected final instead of final.

### Can control title format for editor supports

Jul 17 '00; affected top-level classes: `CloneableEditorSupport`
`updateTitles()` method was made protected final instead of private.

### `IndentEngine` a service type

Jun 23 '00; affected top-level classes: `IndentEngine`
Now a `ServiceType`. A few new methods relating to lookup.
Compatibility: Until Sep 27 '00, was incompatible (`register` had been deleted as it is no longer useful); the method was then restored but made deprecated.

### Refactoring of editor and open supports

May 29 '00; affected top-level classes: `org.openide.text.EditorSupport` `CloneableEditorSupport` `CloneableEditor` `org.openide.loaders.OpenSupport` `org.openide.windows.CloneableOpenSupport`
Major refactoring of `EditorSupport` and `OpenSupport`, so that subclasses can have much finer control over pieces of its functionality.
Compatibility: First broken, Sep 29 '00 restored backwards compatibility.

### Setting colors for lines deprecated

Mar 27 '00; affected top-level classes: `NbDocument`
`NbDocument.COLORS` and `NbDocument.Colors` deprecated.
Compatibility: First removed, later re-added but deprecated in trunk and `boston`. These classes were long disused (and should only have ever been used by the editor module anyway, which did not need them).

### `PrintSettings.getPageFormat` requires a printer job

Feb 24 '00; affected top-level classes: `PrintSettings`
`getPageFormat` method now requires a `PrinterJob` argument.
Compatibility: First removed, later re-added but deprecated in trunk and `boston`. User-stored settings of this class should be backwards compatible, however code directly calling `getPageFormat` will produce a deprecation warning. Probably no one should be directly referring to this class or its BeanInfo outside the package; public only because it is a system option that must be public to appear.

Built on December 7 2006. | Portions Copyright 1997-2005 Sun Microsystems, Inc. All rights reserved.