ilog.views.appframe.docview
Interface IlvDocument

All Superinterfaces:

ActionHandler, ActionListener, EventListener, IlvPropertyManager, MessageListener

All Known Subinterfaces:

IlvFileDocument, IlvStreamDocument

All Known Implementing Classes:

IlvAbstractDocument, IlvAbstractFileDocument, IlvDataContainerDocument, IlvDataDocument, IlvDOMDocument, IlvProjectDocument, IlvTextDocument, IlvWorkspaceDocument

public interface IlvDocument
extends ActionHandler, MessageListener, IlvPropertyManager

A document manages the data to be edited inside an application. It is associated with document views that let the application user visualize and edit this data.
For example, an application that lets the user edit text files will create Text documents that embed a text buffer and a text editor - the document view - to edit the text buffer. In a Model View Controller architecture, the document is the Model and the document view, the View.

Creation of documents
Documents are created by the class IlvApplication. They must not be instantiated explicitly as the application and the associated document template complete the initialization of the document by setting document properties.
The application provides three ways for creating documents:

• Create an empty document. This is done with the methods:
  • IlvApplication.newDocument()
  • IlvApplication.newDocumentOnLastTemplate()
  • IlvApplication.newDocument(IlvDocumentTemplate, boolean, Object) with the userData parameter set to null.
  The method initializeDocument(java.lang.Object) to initialize the empty document, with null as the parameter.
• Create a document to associate with data. This is done with the methods:
  • IlvApplication.newDocument(Object, boolean)
  • IlvApplication.newDocument(IlvDocumentTemplate, boolean, Object) with a non-null userData parameter.
  The method initializeDocument(java.lang.Object) is then called with a user data object with which the document is initialized.
• Create a document from a file. This is done with the methods:
  • IlvApplication.openDocument()
  • IlvApplication.openDocument(IlvFileDocumentTemplate)
  • IlvApplication.openDocumentFile(String, boolean, boolean)
  The document must then be an IlvFileDocument object and its method IlvFileDocument.readDocument(URL, IlvFileFilter) is invoked to initialize the document according to the specified file.

Once the document has been successfully initialized, it is given a title (see setTitle(java.lang.String)) and is set as unmodified (see setModified(boolean)). New document views are associated with the document by invoking its method addView(ilog.views.appframe.docview.IlvDocumentView). Those views are then accessible with the methods getView(int) and getViewCount().

Processing action events
The IlvDocument class implements the ActionHandler interface for processing action events fired by the application.
When a document view becomes active in the application, its associated document is activated. The active view is registered as a new action handler to the application, as well as the document with a lower priority. Action updates or events that are not processed by the active view can be processed by the document. When the document is deactivated, it is removed from the list of action handlers of the application.

An implementation of the IlvDocument interface can handle action events in the implementation of the methods:

• ActionListener.actionPerformed(java.awt.event.ActionEvent)
• ActionHandler.updateAction(javax.swing.Action)
• ActionHandler.isProcessingAction(java.lang.String)

Instead, it is recommended that the IlvDocument implementation extends the IlvAbstractDocument or IlvAbstractFileDocument classes and uses the methods IlvAbstractDocument.addActionHandler(ilog.views.appframe.event.ActionHandler) or IlvAbstractDocument.registerMappings(ilog.views.appframe.event.IlvMessageMapper) for registering new action handlers. This way, it is possible to use predefined ActionHandler implementation classes that make the processing of action events and updates easier.

Field Summary

static String	APPLICATION_PROPERTY Bound property name for the application of the document.
static String	ATTACHED_DOCUMENTS_PROPERTY Bound property name for storing the array of attached documents.
static String	DOCUMENT_OWNER_PROPERTY Bound property name for the document this document is attached to.
static String	DOCUMENT_TEMPLATE_PROPERTY Bound property name for the document template associated with the document.
static String	EDITABLE_PROPERTY Name of the bound property that specifies whether the document can be edited.
static String	MODIFIED_PROPERTY Bound property name for the modification state of a document.
static String	SAVEABLE_PROPERTY Name of the bound property that specifies whether the document can be saved.
static String	TITLE_PROPERTY Bound property name for the title of the document.

Method Summary

void	activated(boolean active) Invoked after a document view associated with this document is activated.
void	addView(IlvDocumentView view) Adds the specified IlvDocumentView object to the list of views of the document.
void	clean() Cleans up the document.
void	documentClosed() Invoked after the document has been closed.
void	documentClosing() Invoked before the document closes.
IlvApplication	getApplication() Returns the application of the document.
IlvDocumentTemplate	getDocumentTemplate() Returns the document template that has created the document.
String	getTitle() Returns the title of the document.
IlvDocumentView	getView(int index) Returns the view of the document at the specified position in the list of document views.
int	getViewCount() Returns the number of views associated with this document.
boolean	initializeDocument(Object userData) Initializes a new document.
boolean	isModified() Returns the modification state of the document.
boolean	removeView(IlvDocumentView view) Removes the specified view from the list of views of the document.
void	removeViews() Removes all the document views owned by the document.
void	setModified(boolean modified) Marks this document as modified.
void	setTitle(String title) Gives the document a new title.

Methods inherited from interface ilog.views.appframe.event.ActionHandler

isProcessingAction, updateAction

Methods inherited from interface java.awt.event.ActionListener

actionPerformed

Methods inherited from interface ilog.views.appframe.event.MessageListener

receiveMessage

Methods inherited from interface ilog.views.appframe.util.IlvPropertyManager

addPropertyChangeListener, getProperty, removePropertyChangeListener, setProperty

Field Detail

TITLE_PROPERTY

static final String TITLE_PROPERTY

Bound property name for the title of the document.

See Also:

Constant Field Values

MODIFIED_PROPERTY

static final String MODIFIED_PROPERTY

Bound property name for the modification state of a document.

See Also:

Constant Field Values

DOCUMENT_TEMPLATE_PROPERTY

static final String DOCUMENT_TEMPLATE_PROPERTY

Bound property name for the document template associated with the document.

See Also:

Constant Field Values

APPLICATION_PROPERTY

static final String APPLICATION_PROPERTY

Bound property name for the application of the document.

See Also:

Constant Field Values

EDITABLE_PROPERTY

static final String EDITABLE_PROPERTY

Name of the bound property that specifies whether the document can be edited.

See Also:

Constant Field Values

SAVEABLE_PROPERTY

static final String SAVEABLE_PROPERTY

Name of the bound property that specifies whether the document can be saved. If the value of the property is equal to Boolean.FALSE, the document cannot be saved; otherwise, if the property is not set or is equal to Boolean.TRUE, the document is automatically saved when the saving actions IlvApplication.SAVE_DOCUMENT_CMD or IlvApplication.SAVE_ALL_DOCUMENTS_CMD are processed.

See Also:

Constant Field Values

ATTACHED_DOCUMENTS_PROPERTY

static final String ATTACHED_DOCUMENTS_PROPERTY

Bound property name for storing the array of attached documents. This property is for internal use only.

See Also:

IlvApplication.attachDocument(ilog.views.appframe.docview.IlvDocument, ilog.views.appframe.docview.IlvDocument), IlvApplication.detachDocument(ilog.views.appframe.docview.IlvDocument, ilog.views.appframe.docview.IlvDocument), DOCUMENT_OWNER_PROPERTY, Constant Field Values

DOCUMENT_OWNER_PROPERTY

static final String DOCUMENT_OWNER_PROPERTY

Bound property name for the document this document is attached to.

See Also:

IlvApplication.attachDocument(ilog.views.appframe.docview.IlvDocument, ilog.views.appframe.docview.IlvDocument), IlvApplication.detachDocument(ilog.views.appframe.docview.IlvDocument, ilog.views.appframe.docview.IlvDocument), ATTACHED_DOCUMENTS_PROPERTY, Constant Field Values

Method Detail

initializeDocument

boolean initializeDocument(Object userData)

Initializes a new document. This method should be overloaded to perform additional initialization work.

Parameters:

userData - The user data to initialize the document with - can be null.

Returns:

true. An overridden method returns true if the document has been successfully initialized; false otherwise.

See Also:

IlvApplication.newDocument(java.lang.Object, boolean), IlvApplication.newDocument(), IlvApplication.newDocument(IlvDocumentTemplate, boolean, Object)

documentClosing

void documentClosing()

Invoked before the document closes.

See Also:

documentClosed()

documentClosed

void documentClosed()

Invoked after the document has been closed.

See Also:

documentClosing()

clean

void clean()

Cleans up the document.

Called before the document closes, or, before the document is initialized with new data if the document template of the document is not MDI (see IlvDocumentTemplate.isMDI()).

activated

void activated(boolean active)

Invoked after a document view associated with this document is activated.

Parameters:

active - If true, the document is activated. Otherwise, the document is deactivated.

getViewCount

int getViewCount()

Returns the number of views associated with this document.

removeView

boolean removeView(IlvDocumentView view)

Removes the specified view from the list of views of the document.

Returns:

true if the specified view was removed from the list of views of the document; false if the view was not added to the document.

See Also:

addView(ilog.views.appframe.docview.IlvDocumentView)

removeViews

void removeViews()

Removes all the document views owned by the document.

addView

void addView(IlvDocumentView view)

Adds the specified IlvDocumentView object to the list of views of the document.

Parameters:

view - The view to add to the list of views of the document.

See Also:

getViewCount(), removeView(ilog.views.appframe.docview.IlvDocumentView), removeViews()

getView

IlvDocumentView getView(int index)

Returns the view of the document at the specified position in the list of document views.

Parameters:

index - The storage index of the view to return.

Returns:

The document view at the specified index.

See Also:

getView(int)

isModified

boolean isModified()

Returns the modification state of the document.

Returns:

true if the document is modified; false otherwise.

See Also:

setModified(boolean)

setModified

void setModified(boolean modified)

Marks this document as modified. The isModified() method will then return the specified value. It is strongly recommended that the implementation of this method changes the MODIFIED_PROPERTY value accordingly.

Parameters:

modified - The new modification state of the document. If true, the document is marked as modified. If false, the document is marked as unmodified.

See Also:

isModified()

getTitle

String getTitle()

Returns the title of the document. The value of the TITLE_PROPERTY must be returned. If the document is a new empty document, the title is built from the default document name given by its associated document template. Otherwise, if the document has been loaded from a file, the title is by default the name of the file.

Returns:

The title of the document.

See Also:

setTitle(java.lang.String)

setTitle

void setTitle(String title)

Gives the document a new title.

Parameters:

title - The new title of the document.

See Also:

getTitle()

getDocumentTemplate

IlvDocumentTemplate getDocumentTemplate()

Returns the document template that has created the document. The implementation of this method should return the value of the DOCUMENT_TEMPLATE_PROPERTY that is automatically set by the template of the document.

getApplication

IlvApplication getApplication()

Returns the application of the document. The implementation of this method should return the value of the APPLICATION_PROPERTY that is automatically set by the document template of the document.

See Also:

APPLICATION_PROPERTY