CDocumentclass resides at the second layer of the XVT-Power++ application framework. Like
CDocumenthas access to the functions on the menubar: Open, Close, Print, Save, and so on.
CDocumentobjects create and manage a common set of windows:
CDocumentobject can display the same data in one or more windows-in both a spreadsheet and a graph, for example. A wire frame document maintains any data shared by its windows. Finally, a particular
CDocumentmay handle events, such as menu commands, that one of its windows has received.
CApplication-derived class has the responsibility to instantiate one or more user-defined and derived
Group your application windows by functionality or other similarities and use one
CDocumentobject to create and manage those windows. To derive a class from
CDocument, overload the
BuildWindowmethod, which is a pure virtual. Put into this method the code to create the specific type of view for the data. Typically, you will also overload the constructor so that it calls the
BuildWindowmethod and starts the window. Also,
is a very good method to overload.
||List of the document's windows|
||Pointer to document file|
||Contains the environment (colors, fonts, pen width, and so on)|
||Whether the data needs to be saved|
||Allows windows to self-add and self-remove|
long theid = PWRIdBase);
CDocumentobject uses the
CApplicationobject's environment, so its environment is set to
CDocumentobject is responsible for managing a set of one or more windows for viewing its data; it has an associated list of windows called
itsWindows. Initially, this list is empty.
The data member
itIsSavedis initially set to
FALSE, meaning that there is no data to save.
CDocument(const CDocument& theDocument);
theDocument. It does not copy the document's windows; it just clones the actual object.
CDocument& operator= (const CDocument& theDocument);
CDocumentobject. It does not copy a document's windows.
BOOLEAN NeedsSaving(void) const;
BOOLEANvalue indicating whether the document's data needs to be saved. You can call
NeedsSavingto determine whether to enable or disable the "Save" and the "Save As" items on the File menu.
void SetSave(BOOLEAN needsSaving);
UpdateMenusfor each window, which can be overridden in your code to enable the "Save" and the "Save As" items on the File menu. You should call
SetSave(TRUE);every time the document's data changes, and you should call
SetSave(FALSE);after the document's data has been saved (or after the changes have been discarded).
virtual BOOLEAN IsEnvironmentShared(void) const;
FALSEif the view is using an environment of its own.
virtual const CEnvironment* GetEnvironment(void) const;
CEnvironmentpointer. If no environment is specified for the document,
GetEnvironmentreturns the application's environment.
virtual void SetEnvironment(
const CEnvironment& theNewEnvironment,
BOOLEAN isUpdate = FALSE);
theNewEnvironmentthat is passed to it. As soon as you use
SetEnvironmentto give a document an environment of its own, the document uses that environment instead of a shared environment.
When the global environment is changed, all documents sharing that environment get a
SetEnvironmentmessage with the
isUpdateparameter set to
isUpdateparameter indicates whether this
SetEnvironmentmessage is simply an update message or whether it is a "real"
SetEnvironment message meaning that this particular document should set its own environment to the new environment.
virtual void DoSetEnvironment(
const CEnvironment& theEnvironment,
BOOLEAN isUpdate = FALSE);
isUpdateparameter indicates whether this
DoSetEnvironmentmessage is simply an update message or whether it is a "real"
DoSetEnvironmentmessage meaning that this particular document should set its own environment to the new environment and pass this change to all of its windows who are sharing its environment.
virtual void ChangeFont(const CFont &theFont);
theFont. If the document does not have an environment of its own, the event is propagated upwards to the application. This method is called after a Font menu selection. To change the font of the document internally, call
virtual PRINT_RCD* GetPrintRecord(void) const;
GetPrintRecordwithin a user-specific document class to return whatever print record is being used for that document.
virtual void BuildWindow(void) = 0;
BuildWindowmechanism can be called from
DoNew. It is where we recommend putting code for creating windows.
virtual void CloseAll(void);
CDocumentobject's list of windows, notifying each one to close. This is a way of deleting all of a document's views. This method disregards whether any data must be saved.
virtual CWindow* FindWindow(
long theId = PWRIdBase) const;
const RWOrdered* GetWindows(void) const;
virtual void DoCommand(long theCommand,
DoCommandhandler. It should be overridden and called by default to pass the
DoCommandup to the application. This
DoCommandis not associated with any XVT Portability Toolkit event, although it can be generated from an XVT Portability Toolkit event. The void pointer
theDatacan be used to pass any user-defined structure to the
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 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.
TRUEif all the windows closed successfully. If the document needs saving, a dialog box prompts the user to save, cancel, or discard.
virtual BOOLEAN DoPageSetUp(void);
DoPrintjust does a bitmap dump of the windows. You may want to override this method to do some further layout.
TRUEif saving was successful; you must provide the appropriate action(s) in your derived class by overriding this method. This method automatically sets the state of the document's
TRUEif saving was successful. This method prompts the user for a file name using a file name dialog box. It then calls
DoSaveto actually save the document..
Openwhich gives access to existing data.
BuildWindowis called if the operation succeeds in creating a document.
virtual void DoMenuCommand(MENU_TAG theMenuItem,
CApplication. It is called when the user makes a selection from the menubar. The menu event can come directly from a window to the document.
theMenuItemis the menu item number as defined in the URL menubar definition.
isControlKeyspecify whether the mouse is used with the Shift key or Control key.
DoMenuCommandhas some predefined actions it takes upon the File menu, which are just like those of
CApplication. The methods called by these predefined functions are presented immediately after this description of
DoMenuCommand. All of the methods called by these defaults call the default mechanism, which in turn calls the
CApplicationobject. When you override a method, always be sure to call the inherited method for these objects.
Calls the default
DoClosemethod when the user selects "Close" from the menu. See
virtual void UpdateMenus(CMenuBar* theMenuBar);
theMenuBar-checking menu items, unchecking them, and so forth-based on the document's state.
This method is also called when a window is selected. The window notifies its associated document that it can update its menu, if necessary. By default, the document object updates the save and deactivates the save, depending on whether the
itIsSavedflag has been set. If the data needs to be saved, the File menubar "Save" is enabled. If it does not need to be saved, the menu item is disabled. It is important to call the
inherited methodif you override
UpdateMenusbecause it does some operations for you automatically, such as the saving functions. When a window object updates its menus, the update event can pass up to its parent and chain upward, stopping at any point, till it reaches the
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, a subview would return a list of all its enclosed views, and so on.
CDocumentinitializer should call this method.
virtual BOOLEAN CloseWindow(CWindow *theWindow);
theWindow) may be closed. This method first determines whether the last window for the document is closing and if the document needs saving. If it does,
CDocument::CloseWindowhandles the saving of the document, including invoking a dialog box that gives the user the option of saving the data or cancelling. This method returns
TRUEif the window may be closed.
virtual void RemoveWindow(CWindow *theWindow);
virtual void AddWindow(CWindow * theWindow);
BuildWindowin order to attach windows to the document.