Application Framework document base class. More...

#include <ilviews/appframe/document.h>

Inheritance diagram for IlvDvDocument:

Public Member Functions
	IlvDvDocument ()
	Constructor. More...

virtual	~IlvDvDocument ()
	Destructor. More...

virtual void	activated (IlBoolean active=IlTrue)
	Notification of the document activation. More...

void	addDoneCommand (IlvDvCommand *command, IlBoolean updateUI=IlTrue, IlBoolean modified=IlTrue)
	Adds an executed command. More...

void	addView (IlvDvDocViewInterface *, IlBoolean update=IlTrue)
	Adds the document view view to the list of owned document views. More...

virtual IlBoolean	canCloseViewContainer (IlvDvViewContainerInterface *v)
	Returns `IlTrue` if the given view container can be closed. More...

virtual IlBoolean	canRedo () const
	Returns `IlTrue` if the last undone command can be executed. More...

virtual IlBoolean	canRepeat () const
	Returns `IlTrue` if the last command to be executed can be repeated. More...

virtual IlBoolean	canUndo () const
	Returns `IlTrue` if the last executed command can be undone. More...

virtual void	clean ()
	Cleans up the document. More...

virtual void	doCommand (IlvDvCommand *command, IlBoolean updateUI=IlTrue, IlBoolean modified=IlTrue)
	Executes the command command. More...

IlvDisplay *	getDisplay () const
	Returns the display of the application. More...

IlvDvDocTemplate *	getDocTemplate () const
	Returns the document template associated with the document. More...

IlvDvDocViewInterface *	getDocView (IlUInt index) const
	Returns a document view. More...

IlvDvDocViewInterface **	getDocViews (IlUInt &count, IlBoolean create=IlTrue) const
	Returns document views. More...

IlvDvApplication *	getDvApplication () const
	Returns the application object. More...

IlUInt	getNumberOfViews () const
	Counts owned document views. More...

const IlvPathName &	getPathName () const
	Returns the path of the document. It can be empty if the document is a new empty document. More...

const IlString &	getTitle () const
	Returns the title of the document. More...

IlUInt	getViewContainersCount (IlBoolean vis=IlTrue) const
	Returns the number of containers associated with the document view. More...

virtual IlBoolean	initializeDocument (IlAny userArg=0)
	Initializes a new empty document. More...

IlBoolean	isAutoDelete () const
	Returns the auto deletion mode. More...

IlBoolean	isModified () const
	Returns the modification state of the document. More...

virtual IlBoolean	open (const IlvPathName &pathname)
	Loads data from the file that has the path pathname. It cleans the document if the associated document template specifies a Single Document Interface mode. It manages the modified state to `IlFalse`, and updates internal data, before calling the real reading method `readDocument`. Therefore, it is recommended not to override this method. It may be more sensible to override method `readDocument`. More...

virtual IlBoolean	readDocument (const IlvPathName &pathname)
	Initializes document data from a file. More...

virtual void	redo (IlBoolean updateUI=IlTrue)
	To redo the last undone command. More...

IlBoolean	removeView (IlvDvDocViewInterface *view, IlBoolean destroyIt=IlTrue, IlBoolean update=IlTrue)
	Removes a document view. More...

void	removeViews (IlBoolean destroyThem=IlFalse)
	Removes document views. More...

virtual void	repeat (IlBoolean updateUI=IlTrue)
	Repeats the last executed command. More...

IlBoolean	revert ()
	Reloads the document data from the document file. More...

IlBoolean	save ()
	Saves the document data in the current document file. More...

IlBoolean	save (IlvPathName &pathName, IlBoolean replace=IlTrue)
	Saves the document in a file. More...

IlBoolean	saveAs ()
	Saves the document in a new file. More...

virtual IlBoolean	saveDocument (const IlvPathName &pathName)
	Saves the document data in the file with the path pathname. More...

virtual IlBoolean	saveModifications ()
	Saves the document only if it has been modified. More...

virtual void	serialize (IlvDvStream &stream)
	Loads and saves the document data in the stream stream. More...

void	setAutoDelete (IlBoolean autoDelete)
	Sets the auto deletion mode of the document to the parameter autoDelete.

void	setDocTemplate (IlvDvDocTemplate *docTemplate)
	Associates the document template docTemplate with the document. More...

virtual void	setModified (IlBoolean modified, IlBoolean notify=IlTrue)
	Forces the modification state of the document. More...

virtual void	setPathName (const IlvPathName &pathName, IlBoolean addToMRU=IlTrue)
	Sets the path of the document to the parameter pathName. More...

virtual void	setTitle (const char *title, IlBoolean update=IlTrue)
	Sets the title of the document. More...

virtual void	undo (IlBoolean updateUI=IlTrue)
	To undo the last executed command. More...

void	updateViewContainerTitles ()
	Updates the view container titles. More...

Public Member Functions inherited from IlvDvInterface
IlBoolean	callMethod (const IlSymbol methodName, IlvDvValue returnedValue,...)
	Generic method for calling a method that is exported in a class interface. More...

IlvDvValue &	getFieldValue (const IlSymbol *fieldName, IlvDvValue &value) const
	Gets a field value. More...

virtual IlBoolean	isProcessingAction (const IlSymbol *methodName) const
	Returns `IlTrue` if the given action can be processed by the class. More...

virtual IlBoolean	processAction (const IlSymbol *actionName)
	Processes an action. More...

virtual IlBoolean	refreshAction (const IlSymbol actionName, IlvDvActionDescriptor desc) const
	Refresh all the menu items that reference the action given by the parameter actionName. More...

void	setFieldValue (const IlSymbol *fieldName, const IlvDvValue &value)
	Sets a field value. More...

Protected Member Functions
IlvDvDocViewInterface *	getCurrentCallerView () const
	Returns the document view that is sending a message to the document. More...

void	notifyViews (const IlSymbol name, IlvDvDocViewInterface except,...)
	Notifies the associated document views of an event. More...

Detailed Description

Application Framework document base class.

Library: ilvappframe

IlvDvDocument is the base class in the document class hierarchy. A document manages the data edited inside an application.
For example, a document in an Excel application would be an array of cells in memory.

Initializing a document
There are two ways for the user to create a document - either by activating menu item File/New.. (which executes command NewDocument), or by activating menu item File/Open.. (which executes action OpenDocument).
In both cases, the document object is automatically created by its associated document template.
Then, overridable methods are called to initialize the document.
If the document is created via the NewDocument action, its initializeDocument method is called. If the document is created via the OpenDocument action, its serialize method is called.

Notification events between document and document views
Document data is usually visualized and edited inside document views associated with the document.
More than one view can be created for the same document. They are created in the same window if an ILV template file is specified for the window, or/and by dynamically duplicating a window containing views.
Thus, a document implementation must always take into consideration the possibility of having more than one associated document view. That is why it is recommended that the document provide accessor methods that allow a safe access to its specific data, and that will notify data changes to all of its document views.

Consider the Syntaxic Editor example found in the samples directory. There are two document views of different types that edit the same parsed text. On the left side of the window, there is a tree that lists all declared classes. On the right side, there is a text editor that edits the parsed text. If the user double-clicks on a class item in the tree, the corresponding class declaration is selected in the text editor. Similarly, as the cursor is moved inside the text editor, the current declared class is selected in the parsed tree.
When the document receives the event SelectClass, it propagates the message to all other views by calling
notifyViews(IlGetSymbol("SelectClass"), getCurrentCallerView(), node);
We see here that we do not call a specific method selectClass for each document view. This lets us avoid having to write something similar to the following:

for each view in all a document's views
    if view is a subtype of tree view then
        ((TreeView*)view)->selectClass(node);
    else if view is a subtype of text view then
        ((TextView*)view)->selectClass(node);

Document implementation should not depend on any document view type. The document must notify views by sending generic events that each view will interpret in its own way. This is done by using method notifyViews. Therefore, other document view types can be added without the need for revision in the document implementation.

Document view container
When a document is created, document views are automatically created to visualize and edit the document. Depending on the options given to the associated document template, these views are created inside a window that can be either a view frame or a dockable bar. Both window types are called document view containers and inherit from the abstract class IlvDvViewContainerInterface.
The associated view containers of a document own the views that edit the document.
Some methods of IlvDvDocument provide access to the associated view containers of a document.

Constructor & Destructor Documentation

IlvDvDocument::IlvDvDocument ( )

Constructor.

Initializes a new IlvDvDocument object.

virtual IlvDvDocument::~IlvDvDocument ( )

virtual

Destructor.

Releases the IlvDvDocument object.

Member Function Documentation

virtual void IlvDvDocument::activated ( IlBoolean active = IlTrue )

virtual

Notification of the document activation.

Called when a view associated with this document is activated. This method can be overloaded if you need to perform additional work to update the document.

Parameters

active If active is IlTrue, the document is activated. Otherwise, the document is deactivated.

void IlvDvDocument::addDoneCommand	(	IlvDvCommand *	command,
		IlBoolean	updateUI = `IlTrue`,
		IlBoolean	modified = `IlTrue`
	)

Adds an executed command.

Stores the command command as the last executed command. The command is supposed to be executed before this method is called.

Parameters

command	Specifies the command.
updateUI	If updateUI is `IlTrue`, the description of the `Undo`, `Redo`, and `Repeat` actions are updated.
modified	If modified is `IlTrue`, the document is set to the modified state.

void IlvDvDocument::addView	(	IlvDvDocViewInterface *	,
		IlBoolean	update = `IlTrue`
	)

Adds the document view view to the list of owned document views.

Parameters

update If IlTrue, titles of all frames that contain views editing this document are updated.

virtual IlBoolean IlvDvDocument::canCloseViewContainer ( IlvDvViewContainerInterface * v )

virtual

Returns IlTrue if the given view container can be closed.

Parameters

v	Specifies the view container.

Returns: IlTrue if the document view container can be closed.

virtual IlBoolean IlvDvDocument::canRedo ( ) const

virtual

Returns IlTrue if the last undone command can be executed.

Returns: IlTrue if the last undone command can be executed.

virtual IlBoolean IlvDvDocument::canRepeat ( ) const

virtual

Returns IlTrue if the last command to be executed can be repeated.

Returns: IlTrue if the last command to be executed can be repeated.

virtual IlBoolean IlvDvDocument::canUndo ( ) const

virtual

Returns IlTrue if the last executed command can be undone.

For example, Paste can be undone.

Returns: IlTrue if the last executed command can be undone.

virtual void IlvDvDocument::clean ( )

virtual

Cleans up the document.

Called before the document is destroyed, or, before initializeDocument() is called if your application is a Single Document Interface application.
Free the data used by your document by using this member function.

Reimplemented in IlvDvProjectDocument, IlvDvGrapherDocument, and IlvDvManagerDocument.

virtual void IlvDvDocument::doCommand	(	IlvDvCommand *	command,
		IlBoolean	updateUI = `IlTrue`,
		IlBoolean	modified = `IlTrue`
	)

virtual

Executes the command command.

Then, the command object is stored as the last executed command.

Parameters

command	Specifies the command to execute.
updateUI	If updateUI is `IlTrue`, the description of the `Undo`, `Redo`, and `Repeat` actions are updated.
modified	If modified is `IlTrue`, the document is set to the modified state.

IlvDvDocViewInterface* IlvDvDocument::getCurrentCallerView ( ) const

protected

Returns the document view that is sending a message to the document.

Returns a non-zero value if the document is currently processing an event from one of its associated document views. In this case, the returned value is the view that has sent the message (and that is waiting for the event to be processed).

Returns: The document view that is sending a message to the document.

IlvDisplay* IlvDvDocument::getDisplay ( ) const

Returns the display of the application.

Returns: The display.

IlvDvDocTemplate* IlvDvDocument::getDocTemplate ( ) const

Returns the document template associated with the document.

Returns: The document template associated with the document.

IlvDvDocViewInterface* IlvDvDocument::getDocView ( IlUInt index ) const

Returns a document view.

Returns: The document view at position index.

IlvDvDocViewInterface** IlvDvDocument::getDocViews	(	IlUInt &	count,
		IlBoolean	create = `IlTrue`
	)		const

Returns document views.

Returns all document views owned by the document. The returned array must be deleted if the parameter create is IlTrue.

Returns: An array of all document views associated with the document.

IlvDvApplication* IlvDvDocument::getDvApplication ( ) const

Returns the application object.

For example, the application object may be necessary for updating some action descriptions.

Returns: The application.

IlUInt IlvDvDocument::getNumberOfViews ( ) const

Counts owned document views.

Returns the number of views owned by the document.

Returns: The number of document views.

const IlvPathName& IlvDvDocument::getPathName ( ) const

Returns the path of the document. It can be empty if the document is a new empty document.

Returns: The path of the document.

const IlString& IlvDvDocument::getTitle ( ) const

Returns the title of the document.

If the document is a new empty document, the title is built on 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, without its directory.

Returns: The title of the document.

IlUInt IlvDvDocument::getViewContainersCount ( IlBoolean vis = IlTrue ) const

Returns the number of containers associated with the document view.

Parameters

vis	If `IlTrue`, only the visible containers are counted.

virtual IlBoolean IlvDvDocument::initializeDocument ( IlAny userArg = 0 )

virtual

Initializes a new empty document.

Called when a document is created using the NewDocument action. This member function can be overloaded to perform all the work needed to initialize the new document.

Parameters

userArg A user argument that can be used to explicitly initialize a new document.

Reimplemented in IlvDvProjectDocument, IlvDvGrapherDocument, and IlvDvManagerDocument.

IlBoolean IlvDvDocument::isAutoDelete ( ) const

Returns the auto deletion mode.

Returns IlTrue if the document destroys itself automatically when its last associated document view is destroyed. By default, this flag is IlTrue.

Returns: IlTrue if the document destroys itself automatically.

IlBoolean IlvDvDocument::isModified ( ) const

Returns the modification state of the document.

Returns IlTrue if the document is modified. The document is modified if at least one command has been executed, and/or the modification state has been forced by calling method setModified.

Returns: IlTrue if the document is modified.

void IlvDvDocument::notifyViews	(	const IlSymbol *	name,
		IlvDvDocViewInterface *	except,
			...
	)

protected

Notifies the associated document views of an event.

Sends an event of name name with an arbitrary list of parameters to the associated document views.

Parameters

name	Specifies the name of the event.
except	Specifies a particular view that must not receive this message. It can be 0 or given by calling method `getCurrentCallerView()`.

See also: See sample Syntaxic Editor, where syntaxic documents send messages notifyViews(IlGetSymbol("SelectClass"), getCurrentCallerView(), pNode);.

virtual IlBoolean IlvDvDocument::open ( const IlvPathName & pathname )

virtual

Loads data from the file that has the path pathname. It cleans the document if the associated document template specifies a Single Document Interface mode. It manages the modified state to IlFalse, and updates internal data, before calling the real reading method readDocument. Therefore, it is recommended not to override this method. It may be more sensible to override method readDocument.

Returns: IlTrue if the document could load its data from the given file.

virtual IlBoolean IlvDvDocument::readDocument ( const IlvPathName & pathname )

virtual

Initializes document data from a file.

Called from the open method.
It creates an IlvDvStream object corresponding to the file with the path pathname. Then, it calls the method serialize, giving the created stream as its parameter.
Some document data objects (such as managers) already have specific methods allowing it to read from a file. In this case, the readDocument method must be redefined so that the serialize method is not invoked and data objects are initialized with the path directly.

Returns: IlTrue if the document data could be loaded.

virtual void IlvDvDocument::redo ( IlBoolean updateUI = IlTrue )

virtual

To redo the last undone command.

Calls the method doIt of the last undone IlvDvCommand object.

Parameters

updateUI If updateUI is IlTrue, the description of the Undo,Redo, and Repeat actions are updated.

IlBoolean IlvDvDocument::removeView	(	IlvDvDocViewInterface *	view,
		IlBoolean	destroyIt = `IlTrue`,
		IlBoolean	update = `IlTrue`
	)

Removes a document view.

Removes the document view view from the list of owned document views. If view is the last owned view and if the document is in autoDelete mode, then the document is closed.

Parameters

view	The view to remove.
destroyIt	If `IlTrue`, view is destroyed.
update	If `IlTrue`, the titles of all frames owning views that edit this document are updated.

Returns: IlTrue, if the given document view is removed from the list of associated document views.

void IlvDvDocument::removeViews ( IlBoolean destroyThem = IlFalse )

Removes document views.

Removes all document views owned by the document.

Parameters

destroyThem If IlTrue, the views are destroyed.

virtual void IlvDvDocument::repeat ( IlBoolean updateUI = IlTrue )

virtual

Repeats the last executed command.

The method creates a copy of the last executed IlvDvCommand object command. The copy is executed by calling method doIt and is stored as the last executed command.

Parameters

updateUI If updateUI is IlTrue, the description of the Undo, Redo, and Repeat actions are updated.

IlBoolean IlvDvDocument::revert ( )

Reloads the document data from the document file.

First, it makes sure that the current document data can be deleted, if the document has been modified. Then, it cleans up the data by calling method clean before finally calling method open with the document path as parameter to reload data.

Returns: IlTrue if the document data could be loaded from the document file.

IlBoolean IlvDvDocument::save ( )

Saves the document data in the current document file.

It calls method save, giving the current document file name as the parameter.

Returns: IlTrue if document data could be saved.

IlBoolean IlvDvDocument::save	(	IlvPathName &	pathName,
		IlBoolean	replace = `IlTrue`
	)

Saves the document in a file.

If pathname is empty, an open dialog box prompts for a new file name. To store the data, the method calls method saveDocument, giving the path pathName as a parameter.

Parameters

pathName	Specifies the file path.
replace	If `IlTrue`, the given path can be different from the current path stored in the document.

Returns: IlTrue if document data could be saved.

IlBoolean IlvDvDocument::saveAs ( )

Saves the document in a new file.

It calls method save, giving an empty file name as the parameter.

Returns: IlTrue if document data could be saved.

virtual IlBoolean IlvDvDocument::saveDocument ( const IlvPathName & pathName )

virtual

Saves the document data in the file with the path pathname.

It is called from the save method.
It creates an IlvDvStream object corresponding to the file with the path pathname. It can be useful to override this method if the document data already has specific methods to save itself in a file. For example, if the document data is a manager, the overridden method will call method save of the manager.

Returns: IlTrue if document data could be saved.

virtual IlBoolean IlvDvDocument::saveModifications ( )

virtual

Saves the document only if it has been modified.

If the document does not yet have a specified file name, an open file dialog box prompts for it.

Returns: IlFalse if the modifications could not be saved.

virtual void IlvDvDocument::serialize ( IlvDvStream & stream )

virtual

Loads and saves the document data in the stream stream.

If stream.isSaving() is IlTrue, the document data must be saved. Otherwise, the document data must be read from the stream.
Typically, the core of the method has the following form:

MyDocument::serialize(IlvDvStream& stream)
{
    if (stream.isSaving()) {
        // Here, write your persistent data
    } else {
        // Here, read data from stream
    }
}

There are two ways to load and save data.
First, by directly using the istream or ostream objects given by methods istream* getInStream() const and ostream* getOutStream() const of the IlvDvStream class.
Or, by using specific serialization methods provided by the IlvDvStream class. It is usually easier to use this second method.
This class provides serialization operators for basic types (IlInt, IlBoolean, and so on), and provides methods that make it easy to save a string, a bitmap, an IlvDvSerializable object, and an array of IlvDvSerializable objects.

Reimplemented from IlvDvSerializable.

Reimplemented in IlvDvProjectDocument, IlvDvGrapherDocument, IlvDvManagerDocument, and IlvDvTextDocument.

void IlvDvDocument::setDocTemplate ( IlvDvDocTemplate * docTemplate )

Associates the document template docTemplate with the document.

This method must not be called, since it is automatically done by the document template.
Thus, it is recommended to call this method only for specific uses.

virtual void IlvDvDocument::setModified	(	IlBoolean	modified,
		IlBoolean	notify = `IlTrue`
	)

virtual

Forces the modification state of the document.

The modification state is set to the parameter value modified.

Parameters

modified	Specifies the new value.
notify	If notify is `IlTrue`, all associated document views are notified of the new modification state of the document.

virtual void IlvDvDocument::setPathName	(	const IlvPathName &	pathName,
		IlBoolean	addToMRU = `IlTrue`
	)

virtual

Sets the path of the document to the parameter pathName.

This method must not be invoked explicitly: it is called by the document template when the document loads from a file or when the document saves with a new path via the SaveAs action. By default, this method updates the title if it was not explicitly set using method setTitle.

virtual void IlvDvDocument::setTitle	(	const char *	title,
		IlBoolean	update = `IlTrue`
	)

virtual

Sets the title of the document.

Parameters

title	Specifies the new title.
update	If update is `IlTrue`, all associated view containers have their title updated to the document title.

Reimplemented in IlvDvProjectDocument.

virtual void IlvDvDocument::undo ( IlBoolean updateUI = IlTrue )

virtual

To undo the last executed command.

Calls the method undo of the last executed command from the IlvDvCommand object.

Parameters

updateUI If updateUI is IlTrue, the description of the Undo, Redo, and Repeat actions are updated.

void IlvDvDocument::updateViewContainerTitles ( )

Updates the view container titles.

Updates titles of associated document views container. If the document is modified, a star symbol is added at the end of the title. If there are multiple associated containers, it adds a different number to each title to distinguish between the different containers.
The title of a document view container will have the following form:
<Document title>[[<Number of container>]] [*]

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation