Chapter 16Chapter 16

Reading and Writing DocumentsReading and Writing Documents—SDI Applications—SDI Applications

SerializationSerialization

Use in the world of object-oriented Use in the world of object-oriented programmingprogramming

Persistent objects, Saving the object to Persistent objects, Saving the object to diskdisk

Saving and restoring objects is called Saving and restoring objects is called serializationserialization

Microsoft Foundation Class Microsoft Foundation Class (MFC) library(MFC) library

Designated classes have a member Designated classes have a member function named function named SerializeSerialize

All the objects associated with a document All the objects associated with a document are are sequentiallysequentially read from or written to a read from or written to a single disk file. single disk file.

No random accessNo random access

Disk Files CFileDisk Files CFile

In MFC the CFile object Represents disk In MFC the CFile object Represents disk filesfiles

Not a buffered I/O stream like fopenNot a buffered I/O stream like fopen It is a handle to a binary file It is a handle to a binary file The application framework uses the file The application framework uses the file

handles:handles:ReadFileReadFile, , WriteFileWriteFile, and , and SetFilePointerSetFilePointer . .

Disk FilesDisk Files

If you do no direct disk I/O in the If you do no direct disk I/O in the application you can depend on the application you can depend on the SerializeSerialize function to store your document function to store your document objects.objects.

Archive ObjectArchive Object

Between the Between the SerializeSerialize function and the function and the CFileCFile object is an archive object (of class object is an archive object (of class CArchiveCArchive))

ArchivesArchives

The The CArchiveCArchive object buffers data for the object buffers data for the CFileCFile object object

it maintains an internal flag that indicates it maintains an internal flag that indicates whether the archive is whether the archive is storingstoring (writing)(writing) or or loadingloading (reading)(reading) from the disk. from the disk.

Making a Class SerializableMaking a Class Serializable

Serializable class is derived from Serializable class is derived from CobjectCobjectClass declaration must contain the Class declaration must contain the

DECLARE_SERIALDECLARE_SERIAL macro macro Class implementation file must contain Class implementation file must contain

IMPLEMENT_SERIALIMPLEMENT_SERIAL macro macro

Writing a Writing a SerializeSerialize Function Function

You must write the Serialize functionYou must write the Serialize function It is a Vertual member function of the CObject It is a Vertual member function of the CObject

classclass It must match the parameters and return It must match the parameters and return

values of the CObject declarationvalues of the CObject declaration

Writing a Writing a SerializeSerialize Function Function

void CStudent::Serialize(CArchive& ar)void CStudent::Serialize(CArchive& ar){{ TRACE("Entering CStudent::Serialize\n");TRACE("Entering CStudent::Serialize\n"); if (ar.IsStoring()) if (ar.IsStoring()) ar << m_strName << m_nGrade; // intoar << m_strName << m_nGrade; // into else else ar >> m_strName >> m_nGrade; // out ofar >> m_strName >> m_nGrade; // out of}}

Example from CStudent of last ChapterExample from CStudent of last Chapter

Classes and Derived ClassesClasses and Derived Classes

Most serialization functions call the Most serialization functions call the SerializeSerialize functions of their base classes. If functions of their base classes. If CStudentCStudent were derived from were derived from CPersonCPerson, for , for example, the first line of the example, the first line of the SerializeSerialize function would be function would be

CPerson::Serialize(ar);CPerson::Serialize(ar);

CArchiveCArchive class class

This class has member function This class has member function CArchive::IsStoringCArchive::IsStoring

It also has overloadedIt also has overloaded insertion operators (<<) and extraction operators (>>) insertion operators (<<) and extraction operators (>>)

for many of the C++ built-in types for many of the C++ built-in types Next SlideNext Slide

You may have to cast data types e.g. enumerated You may have to cast data types e.g. enumerated typestypes

ar << (int) m_nType;ar << (int) m_nType;ar >> (int&) m_nType;ar >> (int&) m_nType;

C++ built-in typesC++ built-in types

TypeType DescriptionDescription

BYTEBYTE 8 bits, unsigned 8 bits, unsigned

WORDWORD 16 bits, unsigned16 bits, unsigned

LONGLONG 32 bits, signed32 bits, signed

DWORDDWORD 32 bits, unsigned 32 bits, unsigned

floatfloat 32 bits 32 bits

doubledouble 64 bits, IEEE standard 64 bits, IEEE standard

intint 32 bits, signed32 bits, signed

shortshort 16 bits, signed16 bits, signed

charchar 8 bits, unsigned 8 bits, unsigned

unsignedunsigned 32 bits, unsigned32 bits, unsigned

MFC classes MFC classes

MFC classes that are MFC classes that are notnot derived from derived from CObjectCObject, such as , such as CStringCString and and CRectCRect, have , have their own overloaded insertion and their own overloaded insertion and extraction operators for extraction operators for CArchiveCArchive. .

What about your own objects that are What about your own objects that are embedded in the CObject?embedded in the CObject?

Loading from an ArchiveLoading from an ArchiveEmbedded Objects vs. PointersEmbedded Objects vs. Pointers

Let's add a new data member to the Let's add a new data member to the CStudentCStudent class: class: public:public:

CTranscript m_transcript;CTranscript m_transcript;

CTranscript is a custom class derived from CTranscript is a custom class derived from CObjectCObject

It will have its own Serialize FunctionIt will have its own Serialize FunctionNo overload for >> or << operatorsNo overload for >> or << operators

An Embedded ObjectAn Embedded Objectm_transcriptm_transcript

CStudent::SerializeCStudent::Serialize function function

void CStudent::Serialize(CArchive& ar)void CStudent::Serialize(CArchive& ar){{ if (ar.IsStoring()) {if (ar.IsStoring()) { ar << m_strName << m_nGrade;ar << m_strName << m_nGrade; }} else {else { ar >> m_strName >> m_nGrade;ar >> m_strName >> m_nGrade; }}

m_transcript.Serialize(ar);m_transcript.Serialize(ar);}}

Embedded ObjectEmbedded Objectm_transcriptm_transcript PointersPointers

If I had a pointer to an ObjectIf I had a pointer to an Objectpublic: public:

CTranscript* m_pTranscript;CTranscript* m_pTranscript;

void CStudent::Serialize(CArchive& ar)void CStudent::Serialize(CArchive& ar){{ if (ar.IsStoring())if (ar.IsStoring()) ar << m_strName << m_nGrade;ar << m_strName << m_nGrade; else {else {

m_pTranscript = new CTranscript;m_pTranscript = new CTranscript; ar >> m_strName >> m_nGrade;ar >> m_strName >> m_nGrade; }}

m_pTranscript->Serialize(ar);m_pTranscript->Serialize(ar);}}

Embedded ObjectEmbedded Objectm_transcriptm_transcript PointersPointers

Or Because the <<, >> are overloaded for Or Because the <<, >> are overloaded for CObject, I can do the following:CObject, I can do the following:

void CStudent::Serialize(CArchive& ar)void CStudent::Serialize(CArchive& ar){{ if (ar.IsStoring())if (ar.IsStoring()) ar << m_strName << m_nGrade << ar << m_strName << m_nGrade << m_pTranscriptm_pTranscript;; elseelse ar >> m_strName >> m_nGrade >> ar >> m_strName >> m_nGrade >> m_pTranscriptm_pTranscript;;}}

Embedded ObjectEmbedded ObjectPointersPointers

When reading objects are dynamically When reading objects are dynamically constructed, by MACROSconstructed, by MACROS

In your Serialize functions care must be taken: In your Serialize functions care must be taken: To avoid a memory leak, you must be sure that To avoid a memory leak, you must be sure that

m_pTranscriptm_pTranscript does not already contain a pointer to a does not already contain a pointer to a

CTranscriptCTranscript object. object. If an object was just created it will have a If an object was just created it will have a

NULL pointerNULL pointer

Embedded ObjectEmbedded ObjectPointersPointers

The insertion and extraction operators do The insertion and extraction operators do notnot work with embedded objects of work with embedded objects of classes derived from classes derived from CObjectCObject, as shown , as shown here: here: ar >> m_strName >> m_nGrade >> &m_transcript;ar >> m_strName >> m_nGrade >> &m_transcript;

Null pointer will not workNull pointer will not work

Serializing Collections Serializing Collections

Classes derived from CObject will have Classes derived from CObject will have the DECLARE_SERIAL macrothe DECLARE_SERIAL macro

If you make a collection of them with If you make a collection of them with CObList CObList Serialize will be called for each member in the Serialize will be called for each member in the

collectioncollection

Serializing CollectionsSerializing Collections

Specifics about loading collections from an archive: Specifics about loading collections from an archive: If a collection contains pointers to objects of mixed classes If a collection contains pointers to objects of mixed classes

(all derived from (all derived from CObjectCObject), the individual class names are ), the individual class names are stored in the archive so that the objects can be properly stored in the archive so that the objects can be properly constructed with the appropriate class constructor. constructed with the appropriate class constructor.

If a container object, such as a document, contains an If a container object, such as a document, contains an embedded collection, loaded data is appended to the existing embedded collection, loaded data is appended to the existing collection. You might need to empty the collection before collection. You might need to empty the collection before loading from the archive. This is usually done in the loading from the archive. This is usually done in the document's virtual document's virtual DeleteContentsDeleteContents function, which is called by function, which is called by the application framework. the application framework.

Serializing CollectionsSerializing Collections

When a collection of When a collection of CObjectCObject pointers is loaded pointers is loaded from an archive, the following processing steps from an archive, the following processing steps take place for each object in the collection: take place for each object in the collection:

The object's class is identified. The object's class is identified.

Heap storage is allocated for the object. Heap storage is allocated for the object.

The object's data is loaded into the newly allocated The object's data is loaded into the newly allocated storage. storage.

A pointer to the new object is stored in the collection. A pointer to the new object is stored in the collection.

The The SerializeSerialize Function and the Function and the Application FrameworkApplication Framework

When will the first When will the first SerializeSerialize function get function get called to start the serialization process?called to start the serialization process?With the application framework, everything is With the application framework, everything is

keyed to the document keyed to the document Choosing Save or Open from the file menuChoosing Save or Open from the file menu

The app framework creates CArcive objectThe app framework creates CArcive objectThen it calls the document classes serialize Then it calls the document classes serialize

functionfunction

The SDI ApplicationThe SDI Application

Typically; SDI applications that have one Typically; SDI applications that have one Document Class and one View ClassDocument Class and one View Class

We will use this to explore the We will use this to explore the interrelationship among :interrelationship among :application object, main frame window, application object, main frame window,

document, view, document template object, document, view, document template object, and the associated string and menu and the associated string and menu resources. resources.

The Windows Application The Windows Application ObjectObject

The AppWizard generates the following The AppWizard generates the following from CWinAppfrom CWinAppCMyApp theApp;CMyApp theApp;

This is the mechanism that starts an MFC This is the mechanism that starts an MFC applicationapplication theApptheApp is a globally declared instance of the is a globally declared instance of the

class. This global object is called the Windows class. This global object is called the Windows application object. application object.

Startup steps in a Microsoft Startup steps in a Microsoft Windows MFC library AppWindows MFC library App

Windows loads your program into memory. Windows loads your program into memory. The global object The global object theApptheApp is constructed. (All is constructed. (All

globally declared objects are constructed globally declared objects are constructed immediately when the program is loaded.) immediately when the program is loaded.)

Windows calls the global function Windows calls the global function WinMainWinMain, which , which is part of the MFC library. (is part of the MFC library. (WinMainWinMain is equivalent is equivalent to the non-Windows to the non-Windows mainmain function—each is a main function—each is a main program entry point.) program entry point.)

Startup steps in a Microsoft Startup steps in a Microsoft Windows MFC library App Windows MFC library App Cont.Cont.

WinMainWinMain searches for the one and only instance of a searches for the one and only instance of a class derived from class derived from CWinAppCWinApp. .

WinMainWinMain calls the calls the InitInstanceInitInstance member function for member function for theApptheApp, which is overridden in your derived application , which is overridden in your derived application class. class.

Your overridden Your overridden InitInstanceInitInstance function starts the function starts the process of loading a document and displaying the main process of loading a document and displaying the main frame and view windows. frame and view windows.

WinMainWinMain calls the calls the RunRun member function for member function for theApptheApp, , which starts the processes of dispatching window which starts the processes of dispatching window messages and command messages. messages and command messages.

The Document Template ClassThe Document Template Class

CSingleDocTemplate* pDocTemplate;CSingleDocTemplate* pDocTemplate;pDocTemplate = new CSingleDocTemplate(pDocTemplate = new CSingleDocTemplate( IDR_MAINFRAME,IDR_MAINFRAME, RUNTIME_CLASS(CStudentDoc),RUNTIME_CLASS(CStudentDoc), RUNTIME_CLASS(CMainFrame), // main SDI frame windowRUNTIME_CLASS(CMainFrame), // main SDI frame window RUNTIME_CLASS(CStudentView));RUNTIME_CLASS(CStudentView));

AddDocTemplate(pDocTemplate);AddDocTemplate(pDocTemplate);

In the InitInstanceIn the InitInstance function that AppWizard generates function that AppWizard generates you will see:you will see:

AddDocTemplateAddDocTemplate

This is the only time you'll actually see a This is the only time you'll actually see a document template object.document template object. Unless you use splitter windows and multiple views,. Unless you use splitter windows and multiple views,. In this case (SDI), it's an object of class In this case (SDI), it's an object of class

CSingleDocTemplateCSingleDocTemplate, which is derived from , which is derived from CDocTemplateCDocTemplate

AddDocTemplateAddDocTemplate is a member function of class is a member function of class CWinAppCWinApp

AddDocTemplate AddDocTemplate ContCont

The The AddDocTemplateAddDocTemplate call, with the call, with the document template constructor call, document template constructor call, Establishes the relationships among Establishes the relationships among classesclasses

The application class, The application class, The document class, The document class, The view window class, The view window class, And the main frame window class. And the main frame window class.

Notable PointsNotable Points

The application object exists, before The application object exists, before template constructiontemplate constructionThe document, view, and frame objects are The document, view, and frame objects are

notnot constructed at this time. constructed at this time.The application framework later dynamically The application framework later dynamically

constructs these objects when they are constructs these objects when they are needed. needed.

Notable PointsNotable Points

This dynamic construction is a sophisticated use of the C++ This dynamic construction is a sophisticated use of the C++ language. language. The The DECLARE_DYNCREATEDECLARE_DYNCREATE and and IMPLEMENT_DYNCREATEIMPLEMENT_DYNCREATE

macros in a class declaration and implementation enable the MFC macros in a class declaration and implementation enable the MFC library to construct objects of the specified class dynamically. library to construct objects of the specified class dynamically.

If this dynamic construction capability weren't present, more If this dynamic construction capability weren't present, more relationships among your application's classes would have to be hard-relationships among your application's classes would have to be hard-coded. coded.

Your derived application class, for example, would need code for Your derived application class, for example, would need code for constructing document, view, and frame objects of your specific constructing document, view, and frame objects of your specific derived classes. derived classes. This would compromise the object-oriented nature of This would compromise the object-oriented nature of

your program.your program.

Relationships Among the Relationships Among the Various ClassesVarious Classes

Object RelationshipsObject Relationships

An SDI An SDI Can only have one Can only have one

TemplateTemplate and associated class and associated class

groupsgroups

When Running oneWhen Running one DocDoc Main FrameMain Frame

The Document Template The Document Template ResourceResource

IDR_MAINFRAMEIDR_MAINFRAME The first entryThe first entry

"ex17a\n" // application window caption"ex17a\n" // application window caption "\n" // root for default document name"\n" // root for default document name // ("Untitled" used if none provided)// ("Untitled" used if none provided) "Ex17a\n" // document type name"Ex17a\n" // document type name "Ex17a Files (*.17a)\n" // doc type desc + filter"Ex17a Files (*.17a)\n" // doc type desc + filter ".17a\n" // ext for doc of this type".17a\n" // ext for doc of this type "Ex17a.Document\n" // Registry file type ID"Ex17a.Document\n" // Registry file type ID "Ex17a Document" // Reg file type desc"Ex17a Document" // Reg file type desc

Multiple Views of an SDI Multiple Views of an SDI DocumentDocument

Chapter 20Chapter 20But you may provide a menu selection But you may provide a menu selection

with a switch statement in the OnDraw with a switch statement in the OnDraw function to control the way the document function to control the way the document class is displayed.class is displayed.

CWinApp::OnFileNewCWinApp::OnFileNew Function Function

Does the following: Does the following: Constructs the document object but does not attempt to Constructs the document object but does not attempt to

read data from disk. read data from disk.

Constructs the main frame object (of class Constructs the main frame object (of class CMainFrameCMainFrame); also creates the main frame window but ); also creates the main frame window but does not show it. The main frame window includes the does not show it. The main frame window includes the IDR_MAINFRAMEIDR_MAINFRAME menu, the toolbar, and the status bar. menu, the toolbar, and the status bar.

Constructs the view object; also creates the view window Constructs the view object; also creates the view window but doesn't show it. but doesn't show it.

CWinApp::OnFileNewCWinApp::OnFileNew Function Function Cont New app vs new doc (File - New) last 3 will be reusedCont New app vs new doc (File - New) last 3 will be reused

Establishes connections among the document, main frame, Establishes connections among the document, main frame, and view and view objectsobjects. Do not confuse these object connections . Do not confuse these object connections with the with the classclass connections established by the call to connections established by the call to AddDocTemplateAddDocTemplate. .

Calls the virtual Calls the virtual CDocument::OnNewDocumentCDocument::OnNewDocument member member function for the document object, which calls the virtual function for the document object, which calls the virtual DeleteContentsDeleteContents function. function.

Calls the virtual Calls the virtual CView::OnInitialUpdateCView::OnInitialUpdate member function for member function for the view object. the view object.

Calls the virtual Calls the virtual CFrameWnd::ActivateFrameCFrameWnd::ActivateFrame for the frame for the frame object to show the main frame window together with the object to show the main frame window together with the menus, view window, and control bars. menus, view window, and control bars.

OnNewDocumentOnNewDocument

An SDI application reuses the same An SDI application reuses the same document object So: document object So: You must override You must override OnNewDocumentOnNewDocument to to

initialize your document object each time the initialize your document object each time the user chooses File New or File Open. user chooses File New or File Open.

Connecting File Open Connecting File Open to Your Serialization Codeto Your Serialization Code

The CWinApp::The CWinApp::OnFileOpen OnFileOpen Function is mapped to Function is mapped to File File Open Open when called the following will occur:when called the following will occur: Prompts the user to select a file. Prompts the user to select a file.

Calls the virtual function Calls the virtual function CDocument::OnOpenDocumentCDocument::OnOpenDocument for the for the already existing document object. This function opens the file, already existing document object. This function opens the file, calls calls CDocument::DeleteContentsCDocument::DeleteContents, and constructs a , and constructs a CArchiveCArchive object set for loading. It then calls the document's object set for loading. It then calls the document's SerializeSerialize function, which loads data from the archive. function, which loads data from the archive.

Calls the view's Calls the view's OnInitialUpdateOnInitialUpdate function. function.

Document Class's Document Class's DeleteContentsDeleteContents

When you load a new file or create a new When you load a new file or create a new document you must erase the contents of document you must erase the contents of the current documentthe current document CDocument::DeleteContentsCDocument::DeleteContents virtual function in your virtual function in your

derived document class. The overridden function, as derived document class. The overridden function, as you've seen in you've seen in Chapter 16 Chapter 16 , does whatever is , does whatever is necessary to clean up your document class's data necessary to clean up your document class's data

members.members. It is not the destructorIt is not the destructor

File Save and File Save File Save and File Save AsAs to Your to Your Serialization CodeSerialization Code

AppWizard generates an application, it AppWizard generates an application, it maps the File Save menu item to the maps the File Save menu item to the OnFileSaveOnFileSave(As)(As) member function of the member function of the CDocumentCDocument class. class. OnFileSaveOnFileSave(As)(As) calls calls the the CDocumentCDocument function function OnSaveDocumentOnSaveDocument, which in turn calls your , which in turn calls your document's document's SerializeSerialize function with an function with an archive object set for storing. archive object set for storing.

The Document's "Dirty" FlagThe Document's "Dirty" Flag

CDocumentCDocument data member data member m_bModifiedm_bModifiedTRUETRUE if the document has been modified if the document has been modified (has become (has become

"dirty")"dirty") Otherwise, it is Otherwise, it is FALSEFALSE. . Accessed through the Accessed through the CDocumentCDocument member functions member functions

SetModifiedFlagSetModifiedFlag and and IsModifiedIsModified..The programmer, must call The programmer, must call SetModifiedFlagSetModifiedFlag function function

to set the flag to to set the flag to TRUETRUE when the document data when the document data changeschanges

EX16A ExampleEX16A ExampleSDI with SerializationSDI with Serialization

The EX17A example is similar to example The EX17A example is similar to example EX15B. The student dialog and the toolbar EX15B. The student dialog and the toolbar are the same, and the view class is the are the same, and the view class is the same. Serialization has been added, same. Serialization has been added, together with an update command UI together with an update command UI function for File Save. function for File Save.

Explorer Launch Explorer Launch (DBLCLICK)(DBLCLICK) and Drag and Dropand Drag and Drop

Program RegistrationProgram RegistrationUse the Advanced button in AppWizard Step Use the Advanced button in AppWizard Step

4. Will add to 4. Will add to InitInstanceInitInstanceRegisterShellFileTypes(TRUE);RegisterShellFileTypes(TRUE);.17A = Ex17a.Document (will be added to reg).17A = Ex17a.Document (will be added to reg)

Explorer Launch Explorer Launch (DBLCLICK)(DBLCLICK) and Drag and Dropand Drag and Drop

Double-Clicking on a DocumentDouble-Clicking on a DocumentAppWizard generates a call to AppWizard generates a call to

EnableShellOpenEnableShellOpen in the application class in the application class InitInstanceInitInstance function function

Enabling Drag and DropEnabling Drag and Dropm_pMainWnd->DragAcceptFiles();m_pMainWnd->DragAcceptFiles();

Explorer Launch Explorer Launch (DBLCLICK)(DBLCLICK) and Drag and Dropand Drag and Drop

Program Startup ParametersProgram Startup ParametersThe The InitInstanceInitInstance function processes the function processes the

command line with calls to command line with calls to ParseCommandLineParseCommandLine and and ProcessShellCommandProcessShellCommand..

Ex16c Example: An MTI Ex16c Example: An MTI Application Application

This example is an MTI version of the Ex16a we This example is an MTI version of the Ex16a we looked at in a previous section. To create this looked at in a previous section. To create this example, in the MFC Application Wizard select example, in the MFC Application Wizard select Multiple Top-Level Documents on the Multiple Top-Level Documents on the Application Type page and deselect Printing And Application Type page and deselect Printing And Print Preview on the Advanced Features page. Print Preview on the Advanced Features page. On the Generated Classes page, change the On the Generated Classes page, change the view’s base class to CFormView.view’s base class to CFormView.

See TextSee Text