org.openide.cookies

Interface EditorCookie

All Superinterfaces:

LineCookie, Node.Cookie

All Known Subinterfaces:

EditorCookie.Observable

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. The EditorCookie.Observable allows listening to changes of the state of the document. 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.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	EditorCookie.Observable The interface extends EditorCookie and allows observing changes in state of the text document.

Method Summary

Modifier and Type	Method and Description
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

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

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

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

StyledDocument openDocument()
                     throws IOException

Get the document (and wait). See the Editor API 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().

Method will throw UserQuestionException exception if file size is too big. This exception could be caught and its method UserQuestionException.confirmed() can be used for confirmation. You need to call openDocument()} one more time after confirmation.

Returns:

the styled document for this cookie

Throws:

IOException - if the document could not be loaded

getDocument

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

void saveDocument()
           throws IOException

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

Throws:

IOException - on I/O error

isModified

boolean isModified()

Test whether the document is modified.

Returns:

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

getOpenedPanes

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.