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 | Friends
IlvDvApplication Class Reference

Application Framework application class. More...

#include <ilviews/appframe/app.h>

Inheritance diagram for IlvDvApplication:
IlvApplication IlvDvInterface IlvValueInterface

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.
 
IlvDvDocTemplatefindDocTemplate (const char *name) const
 Retrieves the document template with the name name. More...
 
IlvDvDocumentfindDocument (const char *filename) const
 Finds a document with the given file name. More...
 
IlvDvDocumentgetActiveDocument () const
 Returns the active document. More...
 
IlvDvDocViewInterfacegetActiveView () const
 Returns the active document view. More...
 
IlvDvViewContainerInterfacegetActiveViewContainer () const
 Returns the active document view container. More...
 
IlvDvApplicationStartergetApplicationStarter () const
 Returns the application object contained by the application starter. More...
 
const IlStringgetAppOptionsFilename () const
 Returns the name of the file containing the specific application options. More...
 
IlvDvDockableMainWindowgetDockableMainWindow () const
 Returns the main window of the application. More...
 
IlvDvDocTemplategetDocTemplate (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...
 
IlvDvMainWindowInterfacegetMainWindow () 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...
 
IlvDvNodeValuegetOptionNode (const IlSymbol *type, const IlSymbol *name) const
 Returns a value from the option nodes. More...
 
IlvDvNodeValuegetOptionNode (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 IlStringgetUserOptionsFilename () const
 Returns the name of the file containing the user profile options. More...
 
virtual void initialize ()
 Initializes the application. More...
 
IlvGadgetItemloadGraphicInBar (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 IlvDvDocumentnewDocument ()
 Creates a new document. More...
 
virtual IlvDvDocumentnewDocument (const char *templateName, IlAny data=0)
 Creates a new document from a document template name. More...
 
virtual IlvDvDocumentnewDocument (IlvDvDocTemplate *tpl, IlAny data=0)
 Creates a new document for a document template. More...
 
virtual IlvDvDocumentopenDocument ()
 Prompts for a document file name and opens the document whose template matches the specified file name. More...
 
virtual IlvDvDocumentopenDocumentFile (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...
 
IlvPopupMenureadPopup (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.
 
IlvGadgetItemsetGraphicInBar (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...
 
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...
 
void setFieldValue (const IlSymbol *fieldName, const IlvDvValue &value)
 Sets a field value. More...
 

Protected Member Functions

virtual IlvDvDocTemplatecreateDocTemplate (const IlSymbol *app)
 Creates a document template object. More...
 
virtual IlvDvMainWindowInterfacecreateMainWindow ()
 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:


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.

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
nameSpecifies the application name. The given name is discarded when reading the application option file.
displayNameName of the display.
argcNumber of items in argv.
argvArray 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
templateNameThe name identifying the template to use.
dataThe 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
tplThe document template.
dataThe 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
filenameSpecifies the file name.
addToROLIf IlTrue, the document file name is added to the recently used file list.
createWindowIf 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
createIf IlTrue, a new document is created when the application is launched without program arguments.
docTemplateNameUsed 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).

© Copyright 2016, 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.