org.openide.cookies
Interface EditorCookie

All Superinterfaces:

LineCookie, Node.Cookie

All Known Subinterfaces:

SourceCookie.Editor

All Known Implementing Classes:

EditorSupport

public interface EditorCookie

extends LineCookie

Cookie defining standard operations with a text document and an editor that can display it. The cookie extends LineCookie because all implementations of editors should support access by lines.

The cookie provides interfaces for opening the file, closing the editor, background loading, saving of the document, and notification of modification.

Warning: it is not guaranteed that the document returned from this cookie will persist for the full lifetime of the cookie. That is, if the editor window is closed and then reopened, it is possible for the document to change. EditorCookie provides no mechanism for listening to changes in the document. Rather, you can attach a change listener to an appropriate support implementing this cookie, as in CloneableEditorSupport.addChangeListener(javax.swing.event.ChangeListener) in order to be notified of document changes. You should do this if you are listening to changes in the document itself, as otherwise you would get no notifications from a reopened document.

Method Summary

boolean	close() Closes all opened editors (if the user agrees) and flushes content of the document to file.
StyledDocument	getDocument() Get the document (but do not block).
JEditorPane[]	getOpenedPanes() Get a list of all editor panes opened on this object.
boolean	isModified() Test whether the document is modified.
void	open() Instructs an editor to be opened.
StyledDocument	openDocument() Get the document (and wait).
Task	prepareDocument() Should load the document into memory.
void	saveDocument() Save the document.

Methods inherited from interface org.openide.cookies.LineCookie

getLineSet

Method Detail

open

public void open()

Instructs an editor to be opened. The operation can return immediately and the editor may be opened later. There can be more than one editor open, so one of them should be arbitrarily chosen and selected (typically given focus).

close

public boolean close()

Closes all opened editors (if the user agrees) and flushes content of the document to file.

Returns:

false if the operation has been cancelled

prepareDocument

public Task prepareDocument()

Should load the document into memory. This is done in a different thread. A task for the thread is returned so other components can test whether the loading is finished or not.

Note that this does not involve opening the actual Editor window. For that, use open().

Returns:

task for control over the loading process

openDocument

public StyledDocument openDocument()
                            throws IOException

Get the document (and wait). See the org.openide.text for details on how this document should behave.

If the document is not yet loaded the method blocks until it is.

Note that this does not involve opening the actual Editor window. For that, use open().

Returns:

the styled document for this cookie

Throws:

IOException - if the document could not be loaded

getDocument

public StyledDocument getDocument()

Get the document (but do not block).

Note that this does not involve opening the actual Editor window. For that, use open().

Returns:

the document, or null if it has not yet been loaded

saveDocument

public void saveDocument()
                  throws IOException

Save the document. This is done in the current thread.

Throws:

IOException - on I/O error

isModified

public boolean isModified()

Test whether the document is modified.

Returns:

true if the document is in memory and is modified; false otherwise

getOpenedPanes

public JEditorPane[] getOpenedPanes()

Get a list of all editor panes opened on this object. The first item in the array should represent the component that is currently selected or that was most recently selected. (Typically, multiple panes will only be open as a result of cloning the editor component.)

The resulting panes are useful for a range of tasks; most commonly, getting the current cursor position or text selection, including the Caret object.

This method may also be used to test whether an object is already open in an editor, without actually opening it.

Returns:

an array of panes, or null if no pane is open from this file. In no case is an empty array returned.