IlvDvApplication Class Reference

Application Framework application class. More...

#include <ilviews/appframe/app.h>

Inheritance diagram for IlvDvApplication:

Public Member Functions
	IlvDvApplication (const char *name, const char *displayName, int argc=0, char **argv=0)
	Constructs an IlvDvApplication object. More...
	IlvDvApplication (IlvDisplay *display, const char *name, IlBoolean owner=IlFalse)
	Constructs an IlvDvApplication object. More...
void	addActionProcessor (IlvDvActionProcessor *actProcess)
	Sets the object actProcess that will process the event for the action with the name actionName.
virtual void	addDocTemplate (IlvDvDocTemplate *tpl)
	Adds the tpl document template to the application.
IlvDvDocTemplate *	findDocTemplate (const char *name) const
	Retrieves the document template with the name name. More...
IlvDvDocument *	findDocument (const char *filename) const
	Finds a document with the given file name. More...
IlvDvDocument *	getActiveDocument () const
	Returns the active document. More...
IlvDvDocViewInterface *	getActiveView () const
	Returns the active document view. More...
IlvDvViewContainerInterface *	getActiveViewContainer () const
	Returns the active document view container. More...
IlvDvApplicationStarter *	getApplicationStarter () const
	Returns the application object contained by the application starter. More...
const IlString &	getAppOptionsFilename () const
	Returns the name of the file containing the specific application options. More...
IlvDvDockableMainWindow *	getDockableMainWindow () const
	Returns the main window of the application. More...
IlvDvDocTemplate *	getDocTemplate (IlUInt index) const
	Returns the document template to the position index. More...
IlUInt	getDocTemplatesCount () const
	Returns the number of document templates owned by the application. More...
virtual const char *	getFullPathName (const char *pathname) const
	Returns the full name of the path pathname. More...
IlvDvMainWindowInterface *	getMainWindow () const
	Returns the main window of the application. More...
IlvDvMenuOptionsReader *	getMenuOptionsReader () const
	Returns the reader of the application menu options. More...
virtual IlUInt	getOpenedDocumentCount () const
	Returns the number of open documents. More...
IlvDvNodeValue *	getOptionNode (const IlSymbol *type, const IlSymbol *name) const
	Returns a value from the option nodes. More...
IlvDvNodeValue *	getOptionNode (const char *type, const char *name) const
	Returns a value node from the option nodes. More...
const char *	getRecentOpenedFile (IlUInt nFile) const
	Returns the file name of the nFile most recently used file. More...
IlUInt	getRecentOpenedFilesCount () const
	Returns the number of stored recently used files. More...
const IlString &	getUserOptionsFilename () const
	Returns the name of the file containing the user profile options. More...
virtual void	initialize ()
	Initializes the application. More...
IlvGadgetItem *	loadGraphicInBar (IlvToolBar *bar, const char *itemLabel, const char *pathname, const char *graphicName, IlBoolean defaultCallbacks=IlTrue)
	Inserts a graphic into a gadget item located in the given toolbar. More...
virtual IlvDvDocument *	newDocument ()
	Creates a new document. More...
virtual IlvDvDocument *	newDocument (const char *templateName, IlAny data=0)
	Creates a new document from a document template name. More...
virtual IlvDvDocument *	newDocument (IlvDvDocTemplate *tpl, IlAny data=0)
	Creates a new document for a document template. More...
virtual IlvDvDocument *	openDocument ()
	Prompts for a document file name and opens the document whose template matches the specified file name. More...
virtual IlvDvDocument *	openDocumentFile (const char *filename, IlBoolean createWindow=IlTrue, IlBoolean addToROL=IlTrue)
	Opens a document with the specified file name. More...
void	openRecentOpenedFile (IlUInt nFile)
	Opens or activates the last nFile most recently used file. More...
virtual IlBoolean	processAction (const IlSymbol *actionName)
	Processes an action. More...
IlBoolean	readOptions (const char *filename)
	Reads the options file named filename. More...
IlvPopupMenu *	readPopup (const IlSymbol *popupName)
	Reads a popup menu resource. More...
virtual IlBoolean	refreshAction (const IlSymbol *actionName, IlvDvActionDescriptor *actionDesc) const
	Refresh all the menu items that reference the action given by the parameter actionName. More...
virtual IlBoolean	refreshAction (const IlSymbol *actionName)
	Refreshes the presentation of an action. More...
virtual IlBoolean	refreshAction (const char *actionName)
	Refreshes the presentation of an action. More...
virtual void	refreshActions ()
	Refreshes the presentation of all the actions represented in the application toolbars. More...
virtual IlBoolean	saveAsCurrentDocument ()
	Saves the active document under another file name. More...
virtual IlBoolean	saveCurrentDocument ()
	Saves the active document. More...
virtual IlBoolean	saveDocument (const char *filename)
	Saves an open document specified by a given file name. More...
virtual void	setActionValid (const char *actionName, IlBoolean valid=IlTrue)
	Sets the validity of the action with the name actionName to the parameter valid. More...
virtual void	setActionValid (const IlSymbol *actionName, IlBoolean valid=IlTrue)
	Sets the validity of the action with the name actionName to the parameter valid. More...
void	setApplicationStarter (IlvDvApplicationStarter *st)
	Sets the application object contained by the application starter st. More...
void	setAppOptionsFilename (const char *filename)
	Sets the name of the file containing the specific application options.
IlvGadgetItem *	setGraphicInBar (IlvToolBar *bar, const char *itemLabel, IlvGraphic *graphic, IlBoolean defaultCallbacks=IlTrue)
	Sets a graphic to a gadget item located in the given toolbar. More...
void	setMenuOptionsReader (IlvDvMenuOptionsReader *reader)
	Sets the menu options reader reader to the application. The previous one is deleted.
void	setUserOptionsFilename (const char *filename)
	Sets the name of the file containing the user profile options.
void	startWithNewDocument (IlBoolean create=IlTrue, const char *docTemplateName=0)
	Specifies whether a new document is created when the application is launched and no program arguments are provided. 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...
void	setFieldValue (const IlSymbol *fieldName, const IlvDvValue &value)
	Sets a field value. More...

Protected Member Functions
virtual IlvDvDocTemplate *	createDocTemplate (const IlSymbol *app)
	Creates a document template object. More...
virtual IlvDvMainWindowInterface *	createMainWindow ()
	Creates a main window for the application. More...
virtual void	readAppOptions ()
	Reads the options specific to the application. More...
virtual void	readUserOptions ()
	Reads the user profile options.

Friends
class	IlvDvApplicationStarter

Detailed Description

Application Framework application class.

Library: ilvappframe

IlvDvApplication is a subclass of IlvApplication. It constructs an application oriented on the Document/View architecture that provides many services standard to Windows applications. Examples of these are MDI (Multiple Document Interface), dockable bars, recently used file lists, reorganization of menus and toolbars, and so on.

Options
The IlvDvApplication class does not need to be inherited. It initializes itself by reading option files that were generated by the Application Framework Editor. These option files contain information such as the description of the main menus and toolbars, a list of all document types (IlvDvDocTemplate objects) that the application can open, the description of the document views that will edit the documents, and so on.
An Application Framework application reads three option files.
First, it reads the specific Application Framework option file, where a set of main actions is described. Examples of these options are OpenDocument or Copy actions, the default main menu and the default main toolbar, and information relative to the scripting.
Then, it reads the specific application option file by calling method readAppOptions. By default, the application option file is the file generated by the Application Framework Editor. It therefore contains all that was edited in the editor, such as redefined main menus and toolbars, all document types that the application can open, and so on. In a third part, it reads the options of all the dynamic modules that are associated with the application. Finally, it calls the readUserOptionsmethod. This method reads a user profile option file, which was automatically saved by the application the last time it exited. This file contains all the options that were modified by the user in the last session. Many categories of options can be dynamically modified by the user:

• Options that are editable in the customization dialog, such as toolbar reorganization, description of actions, and so on.
• Size and position of the main window.
• Size and position of all dialogs, and the tab index of the last notebook page activated for property sheet dialogs.
• Dockable bar positions.
• Dynamic modules that can be loaded or unloaded in the modules dialog.

If you redefine methods readDocViewOptions, readAppOptions, or readUserOptions, the application can load other option files. In this case, it is important to note that if a loaded option was defined in a previously loaded file, the new read values discard the old ones. This is what happens, for example, when the application option file redefines the main menu that was previously read in the Application Framework option file.

IlvDvApplication in the Document/View architecture

The Application Framework application is the main component in the Document/View architecture. It is aware of all objects related to its architecture. In fact, it creates most of them.
It is implicated in the management of documents and in the GUI of the application.

It creates and stores all the document templates that are built according to the read options. An IlvDvDocTemplate object is created for each document type specified in the options. Then, the document template object initializes itself by reading the associated options. For a very specific use, method IlvDvDocTemplate* createDocTemplate(const IlSymbol* name) can be redefined to create a document template object of a subclass of IlvDvDocTemplate.

The application interacts at several levels in the GUI.

• It creates the main window of the application, which is by default an IlvDvDockableMainWindow object that manages the dockable bars and the MDI.
• The application tracks the activation of items in all toolbars. When a menu item is activated, the application retrieves its associated action description. It does this to get the name of the action event to fire. Then, an action event is sent to the following targets, with the following priority:
  • the active document view
  • the document associated with the active document view (the active document)
  • the document view container associated with the active document view (to close or hide the container, for example)
  • all document views created in dockable bars, along with their associated document
  • the GUI manager object (the main window), to execute command Cascad for example)
  • the application object
  To process an action event, one of these targets has to specify an action entry Action(actionName, method) in its interface table. The call chain is broken as soon as a target processes the action event.

Constructor & Destructor Documentation

IlvDvApplication::IlvDvApplication	(	const char *	name,
		const char *	displayName,
		int	argc = 0,
		char **	argv = 0
	)

Constructs an IlvDvApplication object.

This constructor creates an instance of IlvDvApplication whose name is provided by the name parameter and whose display (IlvDisplay class) is created using the parameters displayName, argc, and argv.

Parameters

name	Specifies the application name. The given name is discarded when reading the application option file.
displayName	Name of the display.
argc	Number of items in argv.
argv	Array of strings, as in IlvDisplay constructor.

See Also

IlvDisplay::IlvDisplay()

IlvDvApplication::IlvDvApplication	(	IlvDisplay *	display,
		const char *	name,
		IlBoolean	owner = IlFalse
	)

Constructs an IlvDvApplication object.

This constructor initializes a new IlvDvApplication instance, using a valid IlvDisplay object, provided in the display parameter. The application initializes its name using a copy of the string name. If owner is IlTrue, the display is deleted by the application destructor.

Member Function Documentation

virtual IlvDvDocTemplate* IlvDvApplication::createDocTemplate ( const IlSymbol *  app )

protectedvirtual

Creates a document template object.

By default it creates an IlvDvDocTemplate object, but it can be overridden to create an instance of a class that directly inherits from IlvDvDocTemplate.

Returns

An IlvDvDocTemplate object.

virtual IlvDvMainWindowInterface* IlvDvApplication::createMainWindow ( )

protectedvirtual

Creates a main window for the application.

By default it creates an IlvDvDockableMainWindow object, but it can be overridden to create an instance of a class that directly inherits from IlvDvMainWindowInterface.

Returns

The new main window of the application.

IlvDvDocTemplate* IlvDvApplication::findDocTemplate

(

const char *

name

)

const

Retrieves the document template with the name name.

Returns

The document template with the name name, or 0 if no such document exists.

IlvDvDocument* IlvDvApplication::findDocument

(

const char *

filename

)

const

Finds a document with the given file name.

Finds an open document whose path matches the file name filename.

Returns

The found document. It returns 0 if no document was found.

IlvDvDocument* IlvDvApplication::getActiveDocument

(

)

const

Returns the active document.

Returns

The active document.

IlvDvDocViewInterface* IlvDvApplication::getActiveView

(

)

const

Returns the active document view.

Returns

The active document view.

IlvDvViewContainerInterface* IlvDvApplication::getActiveViewContainer

(

)

const

Returns the active document view container.

Returns

The active document view container.

IlvDvApplicationStarter* IlvDvApplication::getApplicationStarter

(

)

const

Returns the application object contained by the application starter.

Returns

The application object contained by the application starter.

const IlString& IlvDvApplication::getAppOptionsFilename

(

)

const

Returns the name of the file containing the specific application options.

Returns

The name of the file containing the specific application options.

IlvDvDockableMainWindow* IlvDvApplication::getDockableMainWindow

(

)

const

Returns the main window of the application.

It returns an IlvDvDockableMainWindow object built by calling the method createMainWindow().
It returns 0 if the main window created by the method createMainWindow is not a subclass of IlvDvMainWindowInterface. Otherwise, it returns the dockable main window.

Returns

The main window of the application

IlvDvDocTemplate* IlvDvApplication::getDocTemplate

(

IlUInt

index

)

const

Returns the document template to the position index.

Returns

The document template to the position index.

IlUInt IlvDvApplication::getDocTemplatesCount

(

)

const

Returns the number of document templates owned by the application.

Returns

The number of document templates owned by the application.

virtual const char* IlvDvApplication::getFullPathName ( const char *  pathname ) const

virtual

Returns the full name of the path pathname.

If the path corresponds to a resource key, the same path is returned. If not, the application finds in all its display paths a full path that will match.

Returns

The found path. It returns 0 if no path was found.

IlvDvMainWindowInterface* IlvDvApplication::getMainWindow

(

)

const

Returns the main window of the application.

It returns an IlvDvMainWindowInterface object built by calling the method createMainWindow(). By default, this methods builds an IlvDvDockableMainWindow window.

Returns

The main window of the application.

IlvDvMenuOptionsReader* IlvDvApplication::getMenuOptionsReader

(

)

const

Returns the reader of the application menu options.

Returns

The menu options reader.

virtual IlUInt IlvDvApplication::getOpenedDocumentCount ( ) const

virtual

Returns the number of open documents.

Returns

The number of open documents.

IlvDvNodeValue* IlvDvApplication::getOptionNode	(	const IlSymbol *	type,
		const IlSymbol *	name
	)		const

Returns a value from the option nodes.

Returns the option node specified by the given type name type and by the given name name.

Returns

The option node that matches the given type and name.

IlvDvNodeValue* IlvDvApplication::getOptionNode	(	const char *	type,
		const char *	name
	)		const

Returns a value node from the option nodes.

Returns the option node specified by the given type type and by the name name.

Returns

The option node that matches the given type and name.

const char* IlvDvApplication::getRecentOpenedFile

(

IlUInt

nFile

)

const

Returns the file name of the nFile most recently used file.

Returns

The file name of a recently used file.

IlUInt IlvDvApplication::getRecentOpenedFilesCount

(

)

const

Returns the number of stored recently used files.

Returns

The number of stored recently used file.

const IlString& IlvDvApplication::getUserOptionsFilename

(

)

const

Returns the name of the file containing the user profile options.

Returns

The name of the file containing the user profile options.

virtual void IlvDvApplication::initialize ( )

virtual

Initializes the application.

It reads the options and creates all the document templates from these options.

IlvGadgetItem* IlvDvApplication::loadGraphicInBar	(	IlvToolBar *	bar,
		const char *	itemLabel,
		const char *	pathname,
		const char *	graphicName,
		IlBoolean	defaultCallbacks = IlTrue
	)

Inserts a graphic into a gadget item located in the given toolbar.

Loads the graphic with the name graphicName from the .ilv file whose path is given by the parameter pathname.
If no graphic is found, it returns 0.
Otherwise, the graphic is inserted into the gadget item within the toolbar bar, and whose label is itemLabel.
If defaultCallbacks is IlTrue, default callbacks are added to the loaded graphic, so that active documents or views are notified of events that occurred on this graphic. To be notified of graphic events, a document or a view must use graphic notification macros like ComboSelected. These macros must be inserted inside the interface declaration of the document or the view, between macros IlvDvBeginInterface and IlvDvEndInterface.

Returns

The gadget item in which the graphic had been added, if the operation succeeded. Otherwise, it returns 0.

virtual IlvDvDocument* IlvDvApplication::newDocument ( )

virtual

Creates a new document.

If at least two document templates have been previously registered, a dialog box is displayed, allowing you to select the document template that will create the document. Then, the selected document template creates a new empty document and a window containing its document view(s).

Returns

The new document, if the method succeeded.

virtual IlvDvDocument* IlvDvApplication::newDocument ( const char *  templateName, IlAny  data = 0  )

virtual

Creates a new document from a document template name.

First, it finds a document template that matches the given template name. Then, it delegates the document creation to the found document template by calling its newDocument method.

Parameters

templateName	The name identifying the template to use.
data	The data that will be given as the parameter of the initializeDocument method of the document.

Returns

The new document, if the method succeeded.

virtual IlvDvDocument* IlvDvApplication::newDocument ( IlvDvDocTemplate *  tpl, IlAny  data = 0  )

virtual

Creates a new document for a document template.

By default, the method delegates the document creation to the given document template by calling its newDocument method.

Parameters

tpl	The document template.
data	The data that will be given as the parameter of the initializeDocument method of the document.

Returns

The new document, if the method succeeded.

virtual IlvDvDocument* IlvDvApplication::openDocument ( )

virtual

Prompts for a document file name and opens the document whose template matches the specified file name.

Returns

The new document, if the method succeeded.

virtual IlvDvDocument* IlvDvApplication::openDocumentFile ( const char *  filename, IlBoolean  createWindow = IlTrue, IlBoolean  addToROL = IlTrue  )

virtual

Opens a document with the specified file name.

First, it finds a document template that matches the file name. Then, the found document template creates a new document that reads its data from the file name filename. Finally, the document template creates a window whose type depends on template specifications. This window will contain document views that edit the document.

Parameters

filename	Specifies the file name.
addToROL	If IlTrue, the document file name is added to the recently used file list.
createWindow	If IlTrue, a window will be created and associated with the document.

Returns

The new document, if the method succeeded.

void IlvDvApplication::openRecentOpenedFile

(

IlUInt

nFile

)

Opens or activates the last nFile most recently used file.

If the file name of the nFile most recently used file corresponds to a document that is currently open, this document is activated. Otherwise, the document is opened.

virtual IlBoolean IlvDvApplication::processAction ( const IlSymbol *  actionName )

virtual

Processes an action.

Tries to process the action given by the parameter actionName. If a macro Action(actionName, actionMethod) is inserted in the interface table of the class with a specified external name equal to the actionName parameter, the processAction method will automatically call the actionMethod method.

Returns

IlTrue if the action is processed.

Reimplemented from IlvDvInterface.

virtual void IlvDvApplication::readAppOptions ( )

protectedvirtual

Reads the options specific to the application.

These options are generated by the Application Framework Editor.

IlBoolean IlvDvApplication::readOptions

(

const char *

filename

)

Reads the options file named filename.

Returns

IlTrue if the given file name is valid and if the written options are valid.

IlvPopupMenu* IlvDvApplication::readPopup

(

const IlSymbol *

popupName

)

Reads a popup menu resource.

Creates a popup menu according to the popup menu description of name popupName, edited in the Application editor. The new created popup menu is filled with menu items that are built using action descriptions. No callback need to be set to menu items. Processing menu items activation or refreshing their state is done as usual, by specifying Action or RefreshAction entries in interfaces of document view or document classes.

Returns

The new created popup menu, if the operation succeeded. Otherwise it returns 0.

virtual IlBoolean IlvDvApplication::refreshAction ( const IlSymbol *  actionName, IlvDvActionDescriptor *  desc  ) const

virtual

Refresh all the menu items that reference the action given by the parameter actionName.

If a macro RefreshAction(actionName, refreshMethod) is inserted in the interface table of the class with a specified external name equal to the actionName parameter, the refreshAction method will automatically call the refreshMethod method, with desc as the parameter.
All modifications brought to the desc parameter are directly dispatched to all the menu items that reference the action.

Returns

IlTrue if the given action is refreshed.

Reimplemented from IlvDvInterface.

virtual IlBoolean IlvDvApplication::refreshAction ( const IlSymbol *  actionName )

virtual

Refreshes the presentation of an action.

Refreshes all the menu items of the application toolbars that reference action actionName. The descriptor of the action is sent to all targets that process actions. An object that processes actions can also process the action state, by specifying an entry RefreshAction in its interface table.

Returns

IlTrue if an action target processed the action presentation.

virtual IlBoolean IlvDvApplication::refreshAction ( const char *  actionName )

virtual

Refreshes the presentation of an action.

Refreshes all the menu items of the application toolbars that reference action actionName. The descriptor of the action is sent to all targets that process actions. An object that processes actions can also process the action state, by specifying an entry RefreshAction in its interface table.

Returns

IlTrue if an action target processed the action presentation.

virtual void IlvDvApplication::refreshActions ( )

virtual

Refreshes the presentation of all the actions represented in the application toolbars.

Refreshes all the menu items of the application toolbars that reference action actionName. The descriptor of the action is sent to all targets that process actions. An object that processes actions can also process the action state, by specifying an entry RefreshAction in its interface table.

Returns

IlTrue if an action target processed the action presentation.

virtual IlBoolean IlvDvApplication::saveAsCurrentDocument ( )

virtual

Saves the active document under another file name.

Prompts the user for a new file name for the active document, and then it saves the document.

Returns

IlTrue, if saving succeeded.

virtual IlBoolean IlvDvApplication::saveCurrentDocument ( )

virtual

Saves the active document.

Returns

IlTrue, if saving succeeded.

virtual IlBoolean IlvDvApplication::saveDocument ( const char *  filename )

virtual

Saves an open document specified by a given file name.

Finds the open document with the file name filename, and then it asks the document to save.

Returns

IlTrue, if saving succeeded.

virtual void IlvDvApplication::setActionValid ( const char *  actionName, IlBoolean  valid = IlTrue  )

virtual

Sets the validity of the action with the name actionName to the parameter valid.

If the action is invalid, all menu items linked to this action will be grayed. Otherwise, they are set to sensitive.

virtual void IlvDvApplication::setActionValid ( const IlSymbol *  actionName, IlBoolean  valid = IlTrue  )

virtual

Sets the validity of the action with the name actionName to the parameter valid.

If the action is invalid, all menu items linked to this action will be grayed. Otherwise, they are set to sensitive.

void IlvDvApplication::setApplicationStarter

(

IlvDvApplicationStarter *

st

)

Sets the application object contained by the application starter st.

The previous application starter is deleted.

IlvGadgetItem* IlvDvApplication::setGraphicInBar	(	IlvToolBar *	bar,
		const char *	itemLabel,
		IlvGraphic *	graphic,
		IlBoolean	defaultCallbacks = IlTrue
	)

Sets a graphic to a gadget item located in the given toolbar.

Inserts graphic graphic into the gadget item within toolbar bar and whose label is itemLabel. If defaultCallbacks is IlTrue, default callbacks are added to the loaded graphic, so that active documents or views are notified of events that occurred on this graphic. To be notified of graphic events, a document or a view must use graphic notification macros like ComboSelected. These macros must be inserted inside the interface declaration of the document or the view, between macros IlvDvBeginInterface and IlvDvEndInterface.

Returns

The gadget item in which the graphic had been added, if the operation succeeded. Otherwise, it returns 0.

void IlvDvApplication::startWithNewDocument	(	IlBoolean	create = IlTrue,
		const char *	docTemplateName = 0
	)

Specifies whether a new document is created when the application is launched and no program arguments are provided.

By default, the application does not create a new document when it is launched.

Parameters

create	If IlTrue, a new document is created when the application is launched without program arguments.
docTemplateName	Used only if create is IlTrue. It specifies the name of the document template used to create the new document. If it is empty or if it does not specify a valid document name, the new document is created with the document template returned by getDocTemplate((IlUInt)0).