rwlogo
Rogue Wave Views 5.6

Rogue Wave Views
Application Framework Package API Reference Guide

Product Documentation:

Rogue Wave Views
Documentation Home

List of all members | Public Member Functions | Protected Member Functions
IlvDvDocument Class Reference

Application Framework document base class. More...

#include <ilviews/appframe/document.h>

Inheritance diagram for IlvDvDocument:
IlvDvSerializable IlvDvInterface IlvDvManagerDocument IlvDvProjectDocument IlvDvTextDocument IlvDvGrapherDocument

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 bSetModified=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 *view)
 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...
 
IlvDisplaygetDisplay () const
 Returns the display of the application. More...
 
IlvDvDocTemplategetDocTemplate () const
 Returns the document template associated with the document. More...
 
IlvDvDocViewInterfacegetDocView (IlUInt index) const
 Returns a document view. More...
 
IlvDvDocViewInterface ** getDocViews (IlUInt &count, IlBoolean create=IlTrue) const
 Returns document views. More...
 
IlvDvApplicationgetDvApplication () 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 IlStringgetTitle () const
 Returns the title of the document. More...
 
IlUInt getViewContainersCount (IlBoolean onlyVisibles=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 with the path pathname. 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 to the parameter title. 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...
 
IlvDvValuegetFieldValue (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

IlvDvDocViewInterfacegetCurrentCallerView () 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
activeIf active is IlTrue, the document is activated. Otherwise, the document is deactivated.
void IlvDvDocument::addDoneCommand ( IlvDvCommand command,
IlBoolean  updateUI = IlTrue,
IlBoolean  bSetModified = 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
updateUIIf updateUI is IlTrue, the description of the Undo, Redo, and Repeat actions are updated.
modifiedIf 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
updateIf IlTrue, titles of all frames that contain views editing this document are updated.
virtual IlBoolean IlvDvDocument::canCloseViewContainer ( IlvDvViewContainerInterface view)
virtual

Returns IlTrue if the given view container can be closed.

Returns
IlTrue if the document view container view 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
updateUIIf updateUI is IlTrue, the description of the Undo, Redo, and Repeat actions are updated.
modifiedIf 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  onlyVisibles = IlTrue) const

Returns the number of containers associated with the document view.

Parameters
onlyVisiblesIf 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
userArgA 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
exceptSpecifies 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
updateUIIf 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
destroyItIf IlTrue, view is destroyed.
updateIf 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
destroyItIf IlTrue, view is destroyed.
updateIf IlTrue, the titles of all frames that contain views editing this document are updated.
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
updateUIIf 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 with the path pathname.

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
replaceIf replace is 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
notifyIf 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 to the parameter title.

Parameters
updateIf 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
updateUIIf 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>="">]] [*]


© Copyright 2012, Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave is a registered trademark of Rogue Wave Software, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.