IDocument Interface
- public interface IDocument
extends ICookieSupport
, IDriverSupport
, IElement
, IPropertySupport
The IDocument allows extensions within the IDE to communicate with documents
that make up the application source. A document is an abstract view of a resource
(typically a file). It is a fairly simple interface. There are essentially, two
three primary consumers of the IDocument. First and foremost is the DocumentSvc
which is responsible for displaying the documents views. In addition, the document views
will perform some operations on the document. Finally, other extensions within the IDE
may use the Document to obtain drivers, view IElement
and
store information about the document.
-
All Known Implementing Classes
-
DefaultDocument
, JavaDocument
, ControlDocument
, ControlContainerDocument
, DefaultSourceDocument
-
All Superinterfaces
-
ICookieSupport
, IDriverSupport
, IElement
, IPropertySupport
-
All Known Subinterfaces
-
IRelatedDocument
, ISourceDocument
, IVersionedDocument
public static final String |
-
KEY_HiddenEdit
- This key represents a marker cookie that indicates an hidden edit is being made to the document.
|
public static final String |
-
KEY_UndoManager
- This key represents a cookie on the document that holds the UndoManager.
|
public static final String |
-
PROP_DocumentDeleted
- This property represents an event indicating that the file has been deleted.
|
public static final String |
-
PROP_DocumentDirty
- This property indicates the "dirty" state of the document.
|
public static final String |
-
PROP_DocumentEditable
- This property indicates whether or not the current document is editable.
|
public static final String |
-
PROP_DocumentReadOnly
- This property indicates whether or not the current file is "read-only".
|
public static final String |
-
PROP_DocumentURI
- This property indicates the URI of the persistent store for this document.
|
public static final String |
-
PROP_ElementModified
- This property represents an event indicating that an element in the document model
has been modified.
|
KEY_HiddenEdit
public static final String
KEY_HiddenEdit
- This key represents a marker cookie that indicates an hidden edit is being made to the document.
A hidden edit is one that is done implicitly, and while it may dirty the document, the change
will be automatically saved. The presence of this can be used by dirty listeners to allow them
to distinguish this from a simple user edit that may require some state change. For example,
the document service checks for this to avoid displaying a document if it is made dirty and is
not yet displayed. Since it is an implicit change, there is no need to show it to the user.
An example of an implict change is the rename of the java class when a java document's URI
changes. The value of the cookie is simply checked against null and has no meaning itself.
KEY_UndoManager
public static final String
KEY_UndoManager
- This key represents a cookie on the document that holds the UndoManager. This object is an
instance of the Swing UndoManager and will be used by the shell to enable the undo and
redo commands for edits on this document.
PROP_DocumentDeleted
public static final String
PROP_DocumentDeleted
- This property represents an event indicating that the file has been deleted. When this
property becomes true, any references to the document should be removed.
PROP_DocumentDirty
public static final String
PROP_DocumentDirty
- This property indicates the "dirty" state of the document. A dirty document has changes
that have not been written to the persistent store.
PROP_DocumentEditable
public static final String
PROP_DocumentEditable
- This property indicates whether or not the current document is editable.
PROP_DocumentReadOnly
public static final String
PROP_DocumentReadOnly
- This property indicates whether or not the current file is "read-only".
PROP_DocumentURI
public static final String
PROP_DocumentURI
- This property indicates the URI of the persistent store for this document. If the document
is moved or renamed, this property may change. When the document is deleted, the URI should
be set to null. Any extensions that cache documents using the URI as a key should listen
on this event and update their data structures appropriately.
PROP_ElementModified
public static final String
PROP_ElementModified
- This property represents an event indicating that an element in the document model
has been modified.
addElementChangeListener(IElementChangeListener) Method
public void addElementChangeListener(IElementChangeListener
ecl)
Add an element change listener to the document. Whenever any document elements in the
document's tree change, the listener will receive a notification.
It is highly recommended that the same listener not be added twice. A common idiom to
prevent this is to remove the listener (which will do nothing if it's not already added)
before adding it.
Parameters
-
ecl
- Element change listener object to add
Related Topics
IElementChangeListener
getHandlerId() Method
public String
getHandlerId()
Returns the String representing the document handler for this document. The
getDocInfo
method of the DocumentSvc
may be used in order to obtain the IDocumentInfo
interface using this String.
Returns
- String representing the document handler for this document.
getIFile() Method
public IFile
getIFile()
This method returns the IFile for the document.
Returns
- IFile object that represents this document on disk
getInputStream() Method
public InputStream
getInputStream()
Returns an InputStream for the contents of this document. This will return an input stream that
allows the document contents to be read as a byte stream. Non-binary documents should return null.
Returns
- An input stream for the document contents, or null if the document is not binary.
getReader() Method
public Reader
getReader()
Returns a Reader for the contents of this document. IDocument implementers should implement
this method and allow the FileSvc to write the doc's content to disk rather than writing the
file directly. This will allow the FileSvc to properly coordinate change events and alert the
user to file save issues, like file locked and other IO errors. Binary documents should return null.
Returns
- A Reader object for the contents of the document or null if this is a binary document.
getRootElement() Method
public IDocumentElement
getRootElement()
Returns the root of the element model that this document contains. The element model
is an abstract representation of the contents of this document, exposed using the
IElement
interface. IDocumentElement
is a
derived class that exposes a tree model as well as the ability to retrieve the owning
document from any element.
Returns
-
IDocumentElement
representing the root of the document model tree for
this document.
getRootElement(IElementChangeListener) Method
public IDocumentElement
getRootElement(IElementChangeListener
ecl)
Same as above, but will register the given element change listener in an atomic fashion.
If this method returns null, then the element change listener is guaranteed to receive a NEWROOT
element change event when the root element is set to a valid value.
Returns
-
IDocumentElement
representing the root of the document model tree for
this document.
getURI() Method
public URI
getURI()
A shortcut method to return the current value of the Document URI
property.
Returns
- URI of the persistent store location for this document.
getViewInfo() Method
public IDocumentViewInfo
[] getViewInfo()
Returns an array of the IDocumentViewInfo
objects that are valid for this document.
These will be used by the DocumentSvc to display the document panel for this document.
Returns
- Array of
IDocumentViewInfo
objects for this document.
isBinary() Method
public boolean isBinary()
Returns true if this document is a binary-format, false if it contains text.
Returns
- boolean value indicating whether the document is binary
isEditable() Method
public boolean isEditable()
Indicates whether this document is editable. This is a way to determine if certain
operations on the document should be enabled or disabled. Generally a document is not editable
if the underlying file is READ_ONLY although this is not necessarily the case. There may be other
states that render a document unEditable (auto-generated, etc....)
Returns
- true if the document is allowing changes to the model, false otherwise
isModified() Method
public boolean isModified()
A shortcut method to return the current value of the Document Dirty
property.
Returns
true
if the document contains changes that have not been written to the persistent
store; false
if the documents contents match the state of the persistent store.
isReadOnly() Method
public boolean isReadOnly()
A shortcut method to return the current value of the Document Read-only
property.
Returns
true
if the document is read-only; false
if the document can be saved.
makeEditable() Method
public boolean makeEditable()
Attempts to put the document in an editable state. This may involve making the
file writable either in the file system or through source control. If the
document is already editable, this call has no effect.
Warning: some types of documents will change their contents when made editable.
Be sure to check that any ranges or elements are still valid before using them after making
the document editable.
Returns
- true if the document was successfully set to editable, false otherwise
onOpen() Method
public boolean onOpen()
Method called by the document service when this document is initially opened. This is
called automatically by the document service. It may return false to indicate that this
document should not be opened.
Returns
- boolean indicating whether the document should be opened
onRemove() Method
public void onRemove()
Method called by the document service when this document is removed from the document cache.
After this, another document may be created to handle this URI. Any services that this document
has registered itself with as a handler for a particular URI should be notified that it is no
longer the document for its URI.
onSave() Method
public boolean onSave()
Method called by the document service when this document is saved. This is called automatically
by the document service. It may return false to indicate that this document should not be saved.
Returns
- boolean indicating whether the document should be saved
reload() Method
public boolean reload()
Discard any in memory changes to this document and reload it's contents from the
persistent store. This operation may return false indicating that the attempt to
read the data from the persistent store failed. In this case, the in-memory contents of the
document should be the same as before the call to reload
Returns
true
if the reload succeeded; false
if the attempt to reload from the store failed.
removeElementChangeListener(IElementChangeListener) Method
public void removeElementChangeListener(IElementChangeListener
ecl)
Remove the specified element change listener from the list of listeners. If the listener
is not found in the list, this method does nothing.
Parameters
-
ecl
- Element change listener object to remove
waitForRootElement() Method
public IDocumentElement
waitForRootElement()
This waits for a root element to be available, then returns it. It should be used
only with care as it will block the thread it is executed on. Instead, use IDocument.getRootElement(IElementChangeListener)
with a listener.
Returns
-
IDocumentElement
representing the root of the document model tree for
this document.