Rogue Wave Views 5.6
Rogue Wave Views
Application Framework Package API Reference Guide
Rogue Wave Views
Documentation Home
Rogue Wave Views 5.6 |
Rogue Wave Views |
Rogue Wave Views Documentation Home |
Application Framework application class. More...
#include <ilviews/appframe/app.h>
Public Member Functions | |
| IlvDvApplication (IlvDisplay *display, const char *name, IlBoolean owner=IlFalse) | |
Constructs an IlvDvApplication object. | |
| IlvDvApplication (const char *name, const char *displayName, int argc=0, char **argv=0) | |
Constructs an IlvDvApplication object. | |
| 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. | |
| IlvDvDocument * | findDocument (const char *filename) const |
| Finds a document with the given file name. | |
| IlvDvDocument * | getActiveDocument () const |
| Returns the active document. | |
| IlvDvDocViewInterface * | getActiveView () const |
| Returns the active document view. | |
| IlvDvViewContainerInterface * | getActiveViewContainer () const |
| Returns the active document view container. | |
| IlvDvApplicationStarter * | getApplicationStarter () const |
| Returns the application object contained by the application starter. | |
| const IlString & | getAppOptionsFilename () const |
| Returns the name of the file containing the specific application options. | |
| IlvDvDockableMainWindow * | getDockableMainWindow () const |
| Returns the main window of the application. | |
| IlvDvDocTemplate * | getDocTemplate (IlUInt index) const |
| Returns the document template to the position index. | |
| IlUInt | getDocTemplatesCount () const |
| Returns the number of document templates owned by the application. | |
| virtual const char * | getFullPathName (const char *pathname) const |
| Returns the full name of the path pathname. | |
| IlvDvMainWindowInterface * | getMainWindow () const |
| Returns the main window of the application. | |
| IlvDvMenuOptionsReader * | getMenuOptionsReader () const |
| Returns the reader of the application menu options. | |
| virtual IlUInt | getOpenedDocumentCount () const |
| Returns the number of open documents. | |
| IlvDvNodeValue * | getOptionNode (const char *type, const char *name) const |
| Returns a value node from the option nodes. | |
| IlvDvNodeValue * | getOptionNode (const IlSymbol *type, const IlSymbol *name) const |
| Returns a value from the option nodes. | |
| const char * | getRecentOpenedFile (IlUInt nFile) const |
| Returns the file name of the nFile most recently used file. | |
| IlUInt | getRecentOpenedFilesCount () const |
| Returns the number of stored recently used files. | |
| const IlString & | getUserOptionsFilename () const |
| Returns the name of the file containing the user profile options. | |
| virtual void | initialize () |
| Initializes the application. | |
| 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. | |
| virtual IlvDvDocument * | newDocument (IlvDvDocTemplate *tpl, IlAny data=0) |
| Creates a new document for the document template tpl. | |
| virtual IlvDvDocument * | newDocument (const char *templateName, IlAny data=0) |
| Creates a new document for the document template of name templateName. | |
| virtual IlvDvDocument * | newDocument () |
| Creates a new document. | |
| virtual IlvDvDocument * | openDocument () |
| Prompts for a document file name and opens the document whose template matches the specified file name. | |
| virtual IlvDvDocument * | openDocumentFile (const char *filename, IlBoolean createWindow=IlTrue, IlBoolean addToROL=IlTrue) |
| Opens a document with the specified file name. | |
| void | openRecentOpenedFile (IlUInt nFile) |
| Opens or activates the last nFile most recently used file. | |
| virtual IlBoolean | processAction (const IlSymbol *actionName) |
| Processes an action. | |
| IlBoolean | readOptions (const char *filename) |
| Reads the options file named filename. | |
| IlvPopupMenu * | readPopup (const IlSymbol *popupName) |
| Reads a popup menu resource. | |
| virtual IlBoolean | refreshAction (const char *actionName) |
| Refreshes the presentation of an action. | |
| virtual IlBoolean | refreshAction (const IlSymbol *actionName) |
| Refreshes the presentation of an action. | |
| virtual IlBoolean | refreshAction (const IlSymbol *actionName, IlvDvActionDescriptor *actionDesc) const |
| Refresh all the menu items that reference the action given by the parameter actionName. | |
| virtual void | refreshActions () |
| Refreshes the presentation of all the actions represented in the application toolbars. | |
| virtual IlBoolean | saveAsCurrentDocument () |
| Saves the active document under another file name. | |
| virtual IlBoolean | saveCurrentDocument () |
| Saves the active document. | |
| virtual IlBoolean | saveDocument (const char *filename) |
| Saves an open document specified by a given file name. | |
| virtual void | setActionValid (const IlSymbol *actionName, IlBoolean valid=IlTrue) |
| Sets the validity of the action with the name actionName to the parameter valid. | |
| virtual void | setActionValid (const char *actionName, IlBoolean valid=IlTrue) |
| Sets the validity of the action with the name actionName to the parameter valid. | |
| void | setApplicationStarter (IlvDvApplicationStarter *starter) |
| Sets the application object contained by the application starter starter. The previous application starter is deleted. | |
| 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. | |
| 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. | |
Protected Member Functions | |
| virtual IlvDvDocTemplate * | createDocTemplate (const IlSymbol *app) |
| Creates a document template object. | |
| virtual IlvDvMainWindowInterface * | createMainWindow () |
| Creates a main window for the application. | |
| virtual void | readAppOptions () |
| Reads the options specific to the application. | |
| virtual void | readUserOptions () |
| Reads the user profile options. | |
Friends | |
| class | IlvDvApplicationStarter |
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.
IlvDvDockableMainWindow object that manages the dockable bars and the MDI. Cascad for example) Action(actionName, method) in its interface table. The call chain is broken as soon as a target processes the action event. | 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.
| name | Specifies the application name. The given name is discarded when reading the application option file. |
| 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.
| virtual IlvDvDocTemplate* IlvDvApplication::createDocTemplate | ( | const IlSymbol * | app | ) | [protected, virtual] |
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.
IlvDvDocTemplate object. | virtual IlvDvMainWindowInterface* IlvDvApplication::createMainWindow | ( | ) | [protected, virtual] |
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.
| IlvDvDocTemplate* IlvDvApplication::findDocTemplate | ( | const char * | name | ) | const |
Retrieves the document template with the name name.
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.
0 if no document was found. | IlvDvDocument* IlvDvApplication::getActiveDocument | ( | ) | const |
Returns the active document.
| IlvDvDocViewInterface* IlvDvApplication::getActiveView | ( | ) | const |
Returns the active document view.
| IlvDvViewContainerInterface* IlvDvApplication::getActiveViewContainer | ( | ) | const |
Returns the active document view container.
| IlvDvApplicationStarter* IlvDvApplication::getApplicationStarter | ( | ) | const |
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.
| 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.
| IlvDvDocTemplate* IlvDvApplication::getDocTemplate | ( | IlUInt | index | ) | const |
Returns the document template to the position index.
| IlUInt IlvDvApplication::getDocTemplatesCount | ( | ) | const |
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.
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.
| IlvDvMenuOptionsReader* IlvDvApplication::getMenuOptionsReader | ( | ) | const |
Returns the reader of the application menu options.
| virtual IlUInt IlvDvApplication::getOpenedDocumentCount | ( | ) | const [virtual] |
Returns the number of open documents.
| 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.
| 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.
| const char* IlvDvApplication::getRecentOpenedFile | ( | IlUInt | nFile | ) | const |
Returns the file name of the nFile most recently used file.
| IlUInt IlvDvApplication::getRecentOpenedFilesCount | ( | ) | const |
Returns the number of stored recently used files.
| const IlString& IlvDvApplication::getUserOptionsFilename | ( | ) | const |
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.
0. | virtual IlvDvDocument* IlvDvApplication::newDocument | ( | IlvDvDocTemplate * | tpl, | |
| IlAny | data = 0 | |||
| ) | [virtual] |
Creates a new document for the document template tpl.
By default, the method delegates the document creation to the given document template by calling its newDocument method.
| data | The data that will be given as the parameter of the initializeDocument method of the document. |
| virtual IlvDvDocument* IlvDvApplication::newDocument | ( | const char * | templateName, | |
| IlAny | data = 0 | |||
| ) | [virtual] |
Creates a new document for the document template of name templateName.
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.
| data | The data that will be given as the parameter of the initializeDocument method of the document. |
| 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).
| virtual IlvDvDocument* IlvDvApplication::openDocument | ( | ) | [virtual] |
Prompts for a document file name and opens the document whose template matches the specified file name.
| 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.
| 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. |
| 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.
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.
IlTrue if the action is processed. Reimplemented from IlvDvInterface.
| virtual void IlvDvApplication::readAppOptions | ( | ) | [protected, virtual] |
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.
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.
| 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.
IlTrue if an action target processed the action presentation. 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.
IlTrue if an action target processed the action presentation. | 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.
IlTrue if the given action is refreshed. Reimplemented from IlvDvInterface.
| 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.
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.
IlTrue, if saving succeeded. | virtual IlBoolean IlvDvApplication::saveCurrentDocument | ( | ) | [virtual] |
Saves the active document.
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.
IlTrue, if saving succeeded. | 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.
| 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.
| 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.
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.
| 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). |
© 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.