de.sciss.app
Interface DocumentHandler

All Known Implementing Classes:

AbstractDocumentHandler

public interface DocumentHandler

The DocumentHandler interface describes an object that manages registration and unregistration of documents in a multi-document-environment.

Version:

0.13, 02-Aug-05

Author:

Hanns Holger Rutz

Method Summary

void	addDocument(java.lang.Object source, Document doc) Adds a new document to the list of open documents.
void	addDocumentListener(DocumentListener l) Registeres a listener which will be informed about document handler actions such as adding or removing a document.
Document	getActiveDocument() Determines the currently active document.
Document	getDocument(int idx) Returns one of the open documents.
int	getDocumentCount() Returns the number of open documents
boolean	isMultiDocumentApplication() Determines whether the underlying application handles more than a single open document or not.
void	removeDocument(java.lang.Object source, Document doc) Removes a document from the list of open documents.
void	removeDocumentListener(DocumentListener l) Unregisteres a listener who wishes to not be notified any more about document handler actions such as adding or removing a document.
void	setActiveDocument(java.lang.Object source, Document doc) Makes a document the active one.

Method Detail

isMultiDocumentApplication

boolean isMultiDocumentApplication()

Determines whether the underlying application handles more than a single open document or not.

Returns:

true if the application allows more than one document to be opened at a time. false for a single-document-application.

getDocumentCount

int getDocumentCount()

Returns the number of open documents

Returns:

the number of open documents

getDocument

Document getDocument(int idx)

Returns one of the open documents.

Parameters:

idx - the index of the document, ranging from 0 to getDocumentCount() - 1.

Returns:

the requested document

Throws:

java.lang.IndexOutOfBoundsException - if idx is invalid

addDocument

void addDocument(java.lang.Object source,
                 Document doc)

Adds a new document to the list of open documents. A DocumentEvent is generated and dispatched to all registered listeners. The caller is responsible for calling setActiveDocument separately, if desired.

Parameters:

source - the source of the dispatched DocumentEvent, or null to not dispatch an event.

doc - the document to add.

Throws:

java.lang.UnsupportedOperationException - if the caller tries to add a document when there is already one and isMultiDocumentApplication returns false.

java.lang.IllegalArgumentException - if the document has been added before

See Also:

isMultiDocumentApplication()

removeDocument

void removeDocument(java.lang.Object source,
                    Document doc)

Removes a document from the list of open documents. A DocumentEvent is generated and dispatched to all registered listeners. This method will first call setActiveDocument( null ) if the removed document was the active document. After removing the document, this method will call doc.dispose() to free resources occupied by the document.

Parameters:

source - the source of the dispatched DocumentEvent, or null to not dispatch an event.

doc - the document to remove.

Throws:

java.lang.IllegalArgumentException - if the document was not in the list of known documents

setActiveDocument

void setActiveDocument(java.lang.Object source,
                       Document doc)

Makes a document the active one. The active document is the one whose data representation window has the focus, are more generally speaking, is the one who is affected by editing operations. A DocumentEvent is generated and dispatched to all registered listeners.

Parameters:

source - the source of the dispatched DocumentEvent, or null to not dispatch an event.

doc - the document to make the active one, or null to indicate that no document is active.

Throws:

java.lang.IllegalArgumentException - if the document is not in the list of known documents

See Also:

getActiveDocument()

getActiveDocument

Document getActiveDocument()

Determines the currently active document. The active document is the one whose data representation window has the focus, are more generally speaking, is the one who is affected by editing operations.

Returns:

the active document or null, if there is none (this is the case when all documents have been removed)

See Also:

setActiveDocument( Object, Document )

addDocumentListener

void addDocumentListener(DocumentListener l)

Registeres a listener which will be informed about document handler actions such as adding or removing a document.

Parameters:

l - the listener to add

See Also:

removeDocumentListener( DocumentListener )

removeDocumentListener

void removeDocumentListener(DocumentListener l)

Unregisteres a listener who wishes to not be notified any more about document handler actions such as adding or removing a document.

Parameters:

l - the listener to remove

See Also:

addDocumentListener( DocumentListener )