CApplication

Heritage

Description

Usage

Public Data Members

Protected Data Members

Friends

Public Methods

Constructor, Destructor, and Initializer Methods

Immutable Accessor

Command Events

Menu Events

File Menu Item Events

Keyboard Events

Document Management Methods

Getting Subobjects

Environment Methods

Printing Methods

Event Handler Methods

Protected Methods

Heritage

Subclasses: None

Description

Usage

void main(int argc, char* argv[])
{
CHardHatApp testApp;
testApp.Go(argc, argv, MENU_BAR_RID, 0, "BaseName",
				 "Application Name", "Task Window Title");
}

Typically XVT-Power++ applications close themselves when commanded by the user. The following code shows how to force the closing of an application:

if(G->GetApplication()->DoClose())
	xvt_app_destroy();

Note: XVT-Power++ supplies this public data member so that other classes can determine application creation.

Protected Data Members

Friends

Public Methods

CApplication(void);

A constructor. It sets up the application object and acts as a safeguard, ensuring that only one application object is instantiated per application.

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 StartUp event.

CApplication(const CApplication& theApplication);

A constructor. It guarantees that no application object is instantiated twice because there can be only one instance of a CApplication object per application.

virtual ~CApplication(void);

The formal C++ destructor, which is never called. For information on handling the application cleanup that would normally be done in the destructor, see the ShutDown method.

virtual void Go(int argc, char *argv[],
	short theMenuBarId, short theAboutBoxId, 
	char *theBaseName, char *theApplicationName, 
	char *theTaskTitle);

A method that takes control of the application from main. It is called inside main on the application object that is created there. The parameters argc and argv are the standard C parameters that are passed to the main function. theMenuBarId is the resource ID number of the task menubar in XVT Portability Toolkit's URL. Similarly, theAboutBoxId is the resource ID number of the application's default About box. theBaseName is 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. theApplicationName specifies the name that is prepended to the titles of document windows when the title of the document is set. Finally, theTaskTitle is the title of the task window for platforms where the task window has a physical representation.

After Go is called, control is not returned to main, so no code should follow Go. In fact, there should be very little code before Go is called. Very little should be done in main other than creating the application and invoking Go.

virtual void StartUp(void);

A virtual method that handles startup activities for the application. You can override it in your own particular application class. Before calling anything else inside of StartUp, the first thing you must do is call the inherited StartUp method. 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);

A virtual method that handles the shutdown activities of an application. You can override this method in your application class. The last thing your application should do is call the inherited ShutDown method and specify the actions you want it to take upon application shutdown. However, the CGlobalUser object must be deleted before calling the inherited ShutDown method, or ShutDown will 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.

Override:

The user is responsible for deleting the CGlobalUser object. 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:

	CMyApplication::ShutDown(void)
	{

	delete GU;

	. . . 
	CApplication::ShutDown();

	}

BOOLEAN IsMultiByte() const;

Indicates whether the application is running with multibyte support, which is set when the application is constructed.

virtual void DoCommand(long theCommand, 
	void* theData=NULL);

A method that handles command events. It can be called either directly or by a document that has propagated the event upwards to the application. The void pointer theData can be used to pass any user-defined structure to the DoCommand method.

virtual void DoMenuCommand(MENU_TAG theMenuItem,
	BOOLEAN isShiftKey, BOOLEAN isControlKey);

Handles the events that occur when the user selects an item from the menubar. DoMenuCommand first 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. theMenuItem is the menu item number of the command, starting at one. Disabled commands and dividing lines count in the numbering. isShiftKey and isControlKey specify whether the mouse is used with the Shift key or Control key.

DoMenuCommand has 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."

M_FILE_QUIT

Calls the application's DoClose method. DoClose in turn queries every document for quitting and returns TRUE if all documents agree to close. If DoClose returns TRUE, the application terminates. See DoClose

M_FILE_OPEN
Calls the default DoOpen method when the user selects "Open" from the menu. See DoOpen.

M_FILE_CLOSE
Calls the default DoClose method when the user selects "Close" from the menu. See DoClose.

M_FILE_SAVE
Calls the default DoSave method when the user selects "Save" from the menu. See DoSave.

M_FILE_SAVE_AS
Calls the default DoSaveAs method when the user selects "Save As" from the menu. See DoSaveAs.

M_FILE_ABOUT
Calls the default DoAboutBox method when the user selects "About Box" from the menu. See DoAboutBox.

M_FILE_PG_SETUP
Calls the default DoPageSetup method when the user selects Page Setup from the menu. See DoPageSetup.

M_FILE_PRINT
Calls the default DoPrint method when the user selects "Print" from the menu. See DoPrint.

M_FILE_NEW
Calls the default method DoNew when the user selects "New" from the menu. See DoNew.

virtual void ChangeFont(const CFont &theFont);

When the user selects a font from the menubar, ChangeFont sends a font object, theFont, that indicates the current state of the Font/Style menu. ChangeFont is 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);

Automatically called to initialize menus, this method allows you to set up menus via the menubar-activating the File menu, creating a new menu, and so forth.

virtual void UpdateMenus(CMenuBar* theMenuBar);

Enables the application, based on some state, to set up the appropriate menus using 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 CApplication object.

virtual void DoAboutBox(void);

Displays an About box, either automatically through an explicit call or in response to a user selection from a menu. You may want to override this method to get your own animated About box using an XVT-Power++ type of window instead of an XVT Portability Toolkit type of window. In this case, do not call an inherited object, which brings up the standard About box.

virtual BOOLEAN DoClose(void);

Sends a DoClose message to all of the documents of the application. The documents can query the user before closing and return TRUE if the close operation succeeds. If all documents close, this method returns TRUE; otherwise, it returns FALSE to 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);

When the user selects "Open" from the File menu, the application object creates a new document and then calls this method, which opens the document. You must provide the appropriate action(s) in your derived class by overriding DoOpen.

Override:

Instantiate a new document and tell that document to open. This is where you put code for invoking an "Open" dialog box that gives access to some data.

virtual BOOLEAN DoNew(void);

Creates a new document when there is no data, unlike Open which gives access to existing data. You must provide the appropriate action(s) in your derived class by overriding this method.

Override:

Instantiate a new document and tell that document to open. This is where you put code for invoking an "Open" dialog box that gives access to some data.

virtual BOOLEAN DoPageSetUp(void);

A method that is called when the user selects the "Page SetUp" menu item. DoPageSetUp calls the XVT Portability Toolkit xvt_dm_post_page_setup function, which sets up the standard page setup dialog. This method returns a BOOLEAN value of TRUE or 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);

Takes all the open windows in the application, dumps each window onto a separate page, and sends it to the printer.

virtual BOOLEAN DoSave(void);

Calls the CDocument DoSave method on any documents that need saving. This method returns a BOOLEAN value of TRUE if all save operations are successful.

virtual BOOLEAN DoSaveAs(void);

Calls the CDocument DoSaveAs method on any documents that need saving. If all save operations are successful, DoSaveAs returns a BOOLEAN value of TRUE.

virtual void DoKey(const CKey&);

Method sent to the application when one of its documents receives a keyboard event but is unable to handle it. DoKey() is provided with a CKey object 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;

Searches for a document using the ID number assigned to it upon creation and stored in RWOrdered, the document ID list maintained by the application.

virtual void CloseAll(void);

Closes and deletes all the documents in the application. Unlike DoClose, this method disregards whether documents need saving or not.

virtual int GetNumDocuments(void);

Returns the number of documents in the application.

virtual RWOrdered* GetDocuments(void) const;

Returns a list of the application's documents.

virtual const RWOrdered* GetSubObjects(void) const;

A pure virtual method that must be defined by any class derived from CBoss, specifically, CApplication, CDocument, CView, and 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;

Returns the application's global environment.

virtual void DoSetEnvironment(
	const CEnvironment& theNewEnvironment, 
	BOOLEAN isUpdate = FALSE);

Sets the application's global environment to the given environment, theNewEnvironment. In addition it sends an "update environment" message to all documents that depend on the global environment.

virtual void SetEnvironment(
	const CEnvironment& theNewEnvironment);

Sets the environment for the application using theNewEnvironment that is passed to it. By default, all objects of the application share this environment. However, you can use the CView::SetEnvironment method 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;

Returns the application's global print record, which supplies the necessary information about the printing set-up, such as the page set-up, the current printer, and so on. On some platforms, it may also keep track of information on the job status as it progresses. Each application has a global print record that is available through the CApplication class by means of this method.

virtual void DoTimer(long theTimerId);

A method that is called when the XVT Portability Toolkit generates a timer (E_TIMER) event. You set a timer using the XVT Portability Toolkit's xvt_timer_create function, 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 theTimerId of DoTimer. When the timer generates a timer event, CSwitchBoard passes 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);

A method that is called when the XVT Portability Toolkit generates a user (E_USER) event. As noted in the XVT Portability Toolkit Guide, user events allow you to pass custom events to windows and dialogs. theUserId is the ID number that designates a particular kind of user event. The void pointer theData can be used to pass any user-defined structure to DoUser, just as you would for a DoCommand. As with timer events, CSwitchBoard passes 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);

Indicates whether the singleton CApplication object has been instantiated.

BOOLEAN IApplication(CGlobalUser *theGlobalUser);

When you develop an XVT-Power++ application, certain objects, or variables, need to be globally accessible to any object in the hierarchy. The CGlobalUser object provides a central place to store global objects for user-derived application objects in a concise, uniform way. IApplication allows you to set up the global user for the user-derived application object. IApplication returns a BOOLEAN value of TRUE if it has succeeded. See CGlobalUser.

virtual void AddDocument(CDocument *theDocument);

Adds a document to the application.

virtual void RemoveDocument(CDocument *theDocument);

Removes a document from the application.

static void SetInstantiated(BOOLEAN isInstantiated);

Internal method called to indicate that the singleton application object has been instantiated.

virtual void InstallFactories(CFactoryMgr*);

Virtual method called to install any framework factories used by the application. This method installs the default factories defined in Power++. You may override the methods to register additional factories, but make sure this method is called at the top of the overriding method.

Overrides:
Nothing must be overridden, but you may want to write new event handling methods since most of the ones provided are empty.