CApplicationobject, which is the highest object in the application framework hierarchy. This object is the first to be instantiated, the first to receive the thread of control, and the last to be destroyed. It is also the last object to receive events when no other objects can handle them. The
CApplicationobject maintains a list of
CDocumentobjects and creates the global desktop and global environment.
CApplicationis an abstract class and cannot be instantiated; you must derive an instance from it instead.
CApplicationwithin a running application. The application is normally created inside of
main, as shown in the following example:
void main(int argc, char* argv)Refer to the
testApp.Go(argc, argv, MENU_BAR_RID, 0, "BaseName",
"Application Name", "Task Window Title");
for more information on each of the parameters passed in. Once the application is created and the
Gomethod is called in the application, the
Gofunction never returns to the user. Thus, you should set up everything before calling
Typically XVT-Power++ applications close themselves when commanded by the user. The following code shows how to force the closing of an application:
Assures that only one |
Note: XVT-Power++ supplies this public data member so that other classes can determine application creation.
Protected Data Members
The list of documents maintained by the application
The global default environment
The event handler for the application
The application's print record
A document that can call the protected methods and add or remove itself from the application object's data member,
Constructor, Destructor, and Initializer Methods
The application should be created inside of
main. This constructor just sets up some global objects and some initial data structures-as should any derived class constructors. The constructor should take care of only these tasks. No other object from the XVT-Power++ application framework should be created until the application receives a
CApplication(const CApplication& theApplication);
CApplicationobject per application.
virtual void Go(int argc, char *argv,
short theMenuBarId, short theAboutBoxId,
char *theBaseName, char *theApplicationName,
main. It is called inside
mainon the application object that is created there. The parameters
argvare the standard C parameters that are passed to the
theMenuBarIdis the resource ID number of the task menubar in XVT Portability Toolkit's URL. Similarly,
theAboutBoxIdis the resource ID number of the application's default About box.
theBaseNameis the application's file name. That is, it is the base file name, without extension, that the XVT Portability Toolkit uses when looking for .hlp files, .frl files, and .uid files.
theApplicationNamespecifies the name that is prepended to the titles of document windows when the title of the document is set. Finally,
theTaskTitleis the title of the task window for platforms where the task window has a physical representation.
Gois called, control is not returned to
main, so no code should follow
Go. In fact, there should be very little code before
Gois called. Very little should be done in
mainother than creating the application and invoking
virtual void StartUp(void);
StartUp, the first thing you must do is call the inherited
StartUpmethod. After that, specify what you want your application to do upon startup: create windows, open documents, connect to a database, and so on.
virtual void ShutDown(void);
ShutDownmethod and specify the actions you want it to take upon application shutdown. However, the
CGlobalUserobject must be deleted before calling the inherited
ShutDownwill return an error message (see "Override" below).
Normally, you do not have to perform any actions related to XVT-Power++ objects. For example, if windows are up, they are closed and deleted automatically through XVT-Power++. The objects inside these windows are also deleted automatically. What you must do is close any files, disconnect from a database, and perform any other application-dependent tasks.
The user is responsible for deleting the
CGlobalUserobject. While the destructor for the application cleans up any global objects created by XVT-Power++, it is the responsibility of the derived destructor to delete any objects created by the derived application, as shown here:
. . .
BOOLEAN IsMultiByte() const;
virtual void DoCommand(long theCommand,
theDatacan be used to pass any user-defined structure to the
virtual void DoMenuCommand(MENU_TAG theMenuItem,
BOOLEAN isShiftKey, BOOLEAN isControlKey);
DoMenuCommandfirst goes to the window from which the selection was made. If the window cannot handle the command, it sends it to its document. The event chains upwards to the application.
theMenuItemis the menu item number of the command, starting at one. Disabled commands and dividing lines count in the numbering.
isControlKeyspecify whether the mouse is used with the Shift key or Control key.
DoMenuCommandhas the following predefined actions it takes upon a predefined menu, the File menu. The methods called by these predefined functions are described in the next section, called "File Menu Item Events."
DoClosein turn queries every document for quitting and returns
TRUEif all documents agree to close. If
TRUE, the application terminates. See
DoAboutBoxmethod when the user selects "About Box" from the menu. See
DoPageSetupmethod when the user selects Page Setup from the menu. See
virtual void ChangeFont(const CFont &theFont);
ChangeFontsends a font object,
theFont, that indicates the current state of the Font/Style menu.
ChangeFontis an event that chains upwards from a window. This event goes directly to the application if no windows are up. This method sets the font for the global application environment. You should not call it directly; instead, call
SetEnvironment()to change the application's font.
virtual void SetUpMenus(CMenuBar* theMenuBar);
virtual void UpdateMenus(CMenuBar* theMenuBar);
theMenuBar-checking menu items, unchecking them, and so forth. This method is called when a window is selected and when a document's "NeedsSaving" state is changed. When a window object updates its menus, the update event can pass up to its parent and chain upward, stopping at any point, until it reaches the
virtual void DoAboutBox(void);
virtual BOOLEAN DoClose(void);
DoClosemessage to all of the documents of the application. The documents can query the user before closing and return
TRUEif the close operation succeeds. If all documents close, this method returns
TRUE; otherwise, it returns
FALSEto indicate that some documents are still open. This method is called internally when the user selects "Quit" from the File menu or closes the task window.
virtual BOOLEAN DoOpen(void);
virtual BOOLEAN DoNew(void);
Openwhich gives access to existing data. You must provide the appropriate action(s) in your derived class by overriding this method.
virtual BOOLEAN DoPageSetUp(void);
DoPageSetUpcalls the XVT Portability Toolkit
xvt_dm_post_page_setupfunction, which sets up the standard page setup dialog. This method returns a
FALSE, depending on whether the page set-up dialog box succeeded. The page set-up information is contained in the global class library. Its print record is the information that is set by the page set-up dialog box.
virtual BOOLEAN DoPrint(void);
virtual BOOLEAN DoSave(void);
DoSavemethod on any documents that need saving. This method returns a
TRUEif all save operations are successful.
virtual BOOLEAN DoSaveAs(void);
DoSaveAsmethod on any documents that need saving. If all save operations are successful,
virtual void DoKey(const CKey&);
DoKey()is provided with a
CKeyobject that describes the keyboard event, including information regarding the actual key pressed as well as whether other keys pressed simultaneously (e.g., Shift, Ctl, Alt).
virtual CDocument* FindDocument(int theId) const;
RWOrdered, the document ID list maintained by the application.
virtual void CloseAll(void);
DoClose, this method disregards whether documents need saving or not.
virtual int GetNumDocuments(void);
virtual RWOrdered* GetDocuments(void) const;
virtual const RWOrdered* GetSubObjects(void) const;
CSubview. It returns a list of any subobjects associated with a given object. For example, the application would return a list of all its documents, a document would return a list of all its windows, a window would return a list of all its enclosed views, and a subview would return a list of all its enclosed views.
virtual const CEnvironment* GetEnvironment(void) const;
virtual void DoSetEnvironment(
const CEnvironment& theNewEnvironment,
BOOLEAN isUpdate = FALSE);
theNewEnvironment. In addition it sends an "update environment" message to all documents that depend on the global environment.
virtual void SetEnvironment(
const CEnvironment& theNewEnvironment);
theNewEnvironmentthat is passed to it. By default, all objects of the application share this environment. However, you can use the
CView::SetEnvironmentmethod to give a view an environment of its own. If you do this, the view uses its own environment instead of the shared, application environment.
virtual PRINT_RCD* GetPrintRecord(void) const;
CApplicationclass by means of this method.
virtual void DoTimer(long theTimerId);
E_TIMER) event. You set a timer using the XVT Portability Toolkit's
xvt_timer_createfunction, which takes a window and a time interval (in milliseconds) and returns an ID number for the timer. This is the ID number that is passed to
DoTimer. When the timer generates a timer event,
CSwitchBoardpasses it to the XVT Portability Toolkit-designated window via
DoTimer. The window passes it on to its selected view, if it has one. The timer event may propagate upwards from a view to the window to the document and all the way to the application object, stopping at any point.
virtual void DoUser(long theUserId, void* theData);
E_USER) event. As noted in the XVT Portability Toolkit Guide, user events allow you to pass custom events to windows and dialogs.
theUserIdis the ID number that designates a particular kind of user event. The void pointer
theDatacan be used to pass any user-defined structure to
DoUser, just as you would for a
DoCommand. As with timer events,
CSwitchBoardpasses a user event to a designated window. The window passes it on to its selected view, if it has one. The timer event may propagate upwards from a view to the window to the document and all the way to the application object, stopping at any point.
static BOOLEAN IsInstantiated(void);
BOOLEAN IApplication(CGlobalUser *theGlobalUser);
CGlobalUserobject provides a central place to store global objects for user-derived application objects in a concise, uniform way.
IApplicationallows you to set up the global user for the user-derived application object.
TRUEif it has succeeded. See
virtual void AddDocument(CDocument *theDocument);
virtual void RemoveDocument(CDocument *theDocument);
static void SetInstantiated(BOOLEAN isInstantiated);