Category: MFC

This article represents a follow-up of the last article, “Versionable Object’s Serialization using MFC in non Document View applications”. In that article I presented to you a way to solve incompatibility issues between different file versions of the same application, based on MFC serialization into a dialog base application.
But, the dialog base applications are not the best way to use and apply MFC serialization.
Applications base on document view architecture (MDI or SDI) are the best solution when we want to develop MFC application with serialization support.
Document View MFC architecture offers support for automatic save and load document to/from a file on a storage area, using a serialization mechanism. MDI (Multiple Document Interface) and SDI (Single Document Interface) application offers default serialization basic mechanism.

The serialization is customizable. It’s important to define the right binary elements format, file version and element count. Finally, we have to complete the serialize method.
Into a document view application some document class’s methods are mapped over New, Open, Save and Save As items, available in File menu. The application’s user can use these commands in order to create or open files, tracking document status changes and serialize data to/from a file.
MDI applications create a CDocument derived class instance for each open document. SDI applications reuse the same single CDocument derived class instance for each open file.
In a MDI application CDocument class and the classes derived from this are responsible with internal objects serialization control. This class tracks each change that appears in our document. In this way, our application knows that some changes have been made when we accidentally want to close the application, without saving last changed data.
When a document is loaded, a CArchive instance is created for reading file internal data. When we create a new document, a CArchive store instance is created and this instance is used for store to a file process.
CArchive routines are strongly optimized in order to provide a viable store/load mechanism, even if we are serializing a huge number of small items.

In my demo application, I used the same idea as in my last article: an address book with two versions.

In current application the serialization process it’s very different then the old application. The serialization process is realized by a CDocument class instance that interaction with the rest application classes. CAddressBook class place was taken by the document class CSerAddressBookMDIDoc.

In a real application it’s recommended to use unique identifier (UID) in order to “detect” the right object. For simplicity, in my demo application this unique identifier was defined “name” attribute. For instance, I’m using it for a contact update process.

Document class – CSerAddressBookMDIDoc

The interface of document class looks like this:
[cpp]
class CSerAddressBookMDIDoc : public CDocument
{
protected: // create from serialization only
CSerAddressBookMDIDoc();
DECLARE_DYNCREATE(CSerAddressBookMDIDoc)

// Attributes
public:

// Operations
public:

// Overrides
public:
virtual BOOL OnNewDocument();
virtual void Serialize(CArchive& ar);

void SetFileVersion(UINT nFV) { m_nFileVersionSchema = nFV; }
UINT GetFileVersion() const { return m_nFileVersionSchema; }

const ContactList& GetContacts() const {return m_cContactsList;}
bool AddContact(const Contact& contact);
bool RemoveContact(const CString& firstname, const CString& lastname);
POSITION FindContact(const CString& firstname) const;
bool FindContact(const CString& firstname, Contact& contact) const;
bool UpdateContact(const CString& firstname, Contact& contact);

// Implementation
public:
virtual ~CSerAddressBookMDIDoc();
BOOL DoSave(LPCTSTR lpszPathName, BOOL bReplace); // need to override this
virtual BOOL OnSaveDocument(LPCTSTR lpszPathName);

#ifdef _DEBUG
virtual void AssertValid() const;
virtual void Dump(CDumpContext& dc) const;
#endif

ContactList m_cContactsList;

// Generated message map functions
protected:
DECLARE_MESSAGE_MAP()

private:
INT m_nFileVersionSchema;
};
[/cpp]

As you can see, this time I’m using DECLARE_DYNCREATE() macro. This macro allows dynamic document objects runtime creation (a MDI application’s requirement).
In this class I reused some CAddressBook’s methods. These methods handle objects from m_cContactsList list.
ContactList is an alias for our Contacts MFC list:
[cpp]typedef CList ContactList;[/cpp]

The serialization data method of this document class is listed down:
[cpp]
void CSerAddressBookMDIDoc::Serialize(CArchive& ar)
{
if (ar.IsStoring()) // storing
{
ar << m_nFileVersionSchema; // write the number of contacts ar << (int)m_cContactsList.GetCount(); Contact::SetCurrentContactVersion(m_nFileVersionSchema); // write all the contacts POSITION pos = m_cContactsList.GetHeadPosition(); while(pos != NULL) { Contact contact = m_cContactsList.GetNext(pos); contact.Serialize(ar); } } else // loading { ar >> m_nFileVersionSchema;

m_cContactsList.RemoveAll();

int count = 0;
ar >> count;

// read the number of contacts
while (count– > 0)
{
Contact contact;
contact.Serialize(ar);

m_cContactsList.AddTail(contact);
}
}
UpdateAllViews(NULL);
}
[/cpp]

This method read (load) or write (store) serialized Contact class’s object using a CArchive object at runtime. If the code flow runs over true branch all information is saving from our list to our file. If code flow choose else branch it means that we are loading an existing file and all file data is loaded in our list.

In order to store data in a file, initially I save file version (m_nFileVersionSchema) and items count. Then I iterate over all m_cContactsList items (Contact type item) and I serialize this data in order to store in my new file.

If I want to load data from a file, I am reading file version, I clean my list, I get Contact stored items count and as long as this count variable value is positive I serialized with load flag all Contact file data.
All serialized Contact entities go to m_cContactsList list. Each time we want to display our files data we have to iterate over this list.

Internal serialized class – Contact

As you have seen, in CSerAddressBookMDIDoc::Serialize() method, for both situations (store/load) a new Contact instance is created and this object is passed to Contact::Serialize() for load/store operation.
The serializing Contact items method looks like this:
[cpp]
void Contact::Serialize( CArchive& ar )
{
if (ar.IsStoring())
{
CRuntimeClass* pruntime = Contact::GetRuntimeClass();
int oldnr = pruntime->m_wSchema;
pruntime->m_wSchema = CURRENT_VERSION;

ar.SerializeClass(pruntime);

switch (CURRENT_VERSION)
{
case 1:
ar << m_strFirstName << m_strLastName << m_strAddress << m_strPhone; break; case 2: ar << m_strFirstName << m_strLastName << m_strAddress << m_strPhone << m_strMobilePhone << m_strEmail; break; default: // unknown version for this object AfxMessageBox(_T("Unknown file version."), MB_ICONSTOP); break; } pruntime->m_wSchema = oldnr;
}
else // loading code
{
ar.SerializeClass(RUNTIME_CLASS(Contact));

UINT nVersion = ar.GetObjectSchema();

switch (nVersion)
{
case 1:
ar >> m_strFirstName >> m_strLastName >> m_strAddress >> m_strPhone;
m_strMobilePhone = _T(“”);
m_strEmail = _T(“”);
break;

case 2:
ar >> m_strFirstName >> m_strLastName >> m_strAddress >> m_strPhone >> m_strMobilePhone >> m_strEmail;
break;

default:
// unknown version for this object
AfxThrowArchiveException(CArchiveException::badSchema);
break;
}
}
}
[/cpp]

If I want to store my data to a file, I obtain a runtime pointer to my serialized class, in order to set my file version schema. Then, depending on file version I serialize right object data and finally I reassign initial version schema value of my runtime class.

If I am loading a file, I call Contact::Serialize() method, I get file version schema and depending on schema value, I add right data to my document class.

View class – CSerAddressBookMDIView
This class is responsible with document class content (loaded file’s data) graphical representation. In my demo application, the view class is derived from CListView and has REPORT flag set in order to display data into a grid like.

Main responsible method with client window’s list control population is CSerAddressBookMDIView::PopulateList() and is listed down:
[cpp]
void CSerAddressBookMDIView::PopulateList()
{
CSerAddressBookMDIDoc* pDoc = GetDocument();
ASSERT_VALID(pDoc);

CreateViews(pDoc->GetFileVersion());

CListCtrl *pListCtrl = &GetListCtrl();
ASSERT_VALID(pListCtrl);

// get a reference to the contacts list
const ContactList& contacts = pDoc->GetContacts();

// iterate over all contacts add add them to the list
int nCurrentItem = 0;
POSITION pos = contacts.GetHeadPosition();
while(pos != NULL)
{
const Contact contact = contacts.GetNext(pos);

nCurrentItem = pListCtrl->InsertItem(nCurrentItem, contact.GetFirstName());
pListCtrl->SetItemText(nCurrentItem, 1, contact.GetLastName());
pListCtrl->SetItemText(nCurrentItem, 2, contact.GetAddress());
pListCtrl->SetItemText(nCurrentItem, 3, contact.GetPhoneNumber());

switch(pDoc->GetFileVersion())
{
case 1:
break;
case 2:
pListCtrl->SetItemText(nCurrentItem, 4, contact.GetMobileNumber());
pListCtrl->SetItemText(nCurrentItem, 5, contact.GetEmail());
break;
default:
break;
}
}
}
[/cpp]

First, we obtain a pointer to our current document. Then, we call the method that inserts right list control columns, depending on file version (CreateViews() method).
We obtain a CListView pointer and an object reference to fist contact from contacts list. Then, as long as we have elements, we iterate over list’s elements (in a while() loop) and insert data to our list control.

PopulateList() method is called from overwrite CSerAddressBookMDIView::OnUpdate() method. OnUpdate() method is called by MFC framework as long as a document is changed.
The original OnUpdate() method is called by CDocument::UpdateAllViews() and is implemented in CView class.

In order to add/remove/update records from our documents I created a special dialog, launched from my Menu menu.
Display modal dialog method is listed down:
[cpp]
void CSerAddressBookMDIView::OnMymenuChangedata()
{
CSerAddressBookMDIDoc *pDoc = GetDocument();
ASSERT_VALID(pDoc);

CManipulateDataDlg dlg;

dlg.SetAddressDocument(pDoc);

if (IDOK == dlg.DoModal())
{
PopulateList();
}
}
[/cpp]

Because I have to interact from my dialog window with contacts list of current document, I have to pass the pointer of my document class ( dlg.SetAddressDocument(pDoc) ) to my dialog window class. If the dialog is closed using Exit button (IDOK id) then the view is refilled, using PopulateList() call.

CManipulateDataDlg class

This class is responsible with the management of document contact list items. The difference between this dialog class and the dialog class of last article is that this class is not responsible with load/store process. This role was taken by document view architecture.

Dialog’s control list population method looks like this:
[cpp]
void CManipulateDataDlg::PopulateList()
{
// delete all current members
m_cList.DeleteAllItems();

// get a reference to the contacts list
const ContactList& contacts = m_pAddressDoc->GetContacts();

// iterate over all contacts add add them to the list
int nCurrentItem = 0;
POSITION pos = contacts.GetHeadPosition();
while(pos != NULL)
{
const Contact contact = contacts.GetNext(pos);

nCurrentItem = m_cList.InsertItem(nCurrentItem, contact.GetFirstName());
m_cList.SetItemText(nCurrentItem, 1, contact.GetLastName());
m_cList.SetItemText(nCurrentItem, 2, contact.GetAddress());
m_cList.SetItemText(nCurrentItem, 3, contact.GetPhoneNumber());

switch(m_pAddressDoc->GetFileVersion())
{
case 1:
break;
case 2:
m_cList.SetItemText(nCurrentItem, 4, contact.GetMobileNumber());
m_cList.SetItemText(nCurrentItem, 5, contact.GetEmail());
break;
}
}
}
[/cpp]

Each time we clean the contact list we obtain a reference to the beginning of document contacts list. Depending on file version schema (1 or 2), dialog’s controls are customized. Then, we iterate over contact list elements (ContactList) and I insert data into my control list.

MDI support for many file extension

Default MDI applications come with only one file support and only one file extension file format.
Sometimes, our applications need to support different file format and more file extensions. In my demo application is necessary to support two file format and two file version (version 1 (*.sab1) and version 2 (*.sab2)).
Same time, the application must support old file format conversion to new file format and vice versa.
You can find multi file support detailed information for document view MFC application to Microsoft KB 141921. Other useful reference you can find here.
Starting from these references my application support two file format. I figure some important changes that I made into my initialize method, CSerAddressBookMDIApp::InitInstance.
[cpp]
BOOL CSerAddressBookMDIApp::InitInstance()
{
// ———-
// MFC’s wizard generated code…
// ———-
SetRegistryKey(_T(“Local AppWizard-Generated Applications”));
LoadStdProfileSettings(4); // Load standard INI file options (including MRU)
// Register the application’s document templates. Document templates
// serve as the connection between documents, frame windows and views

m_pDocManager = new CMultiDocManager; // Silviu

CMultiDocTemplate* pDocTemplate;
pDocTemplate = new CMultiDocTemplate(IDR_SerAddressBookTYPE,
RUNTIME_CLASS(CSerAddressBookMDIDoc),
RUNTIME_CLASS(CChildFrame), // custom MDI child frame
RUNTIME_CLASS(CSerAddressBookMDIView));
if (!pDocTemplate)
return FALSE;
AddDocTemplate(pDocTemplate);

//Silviu
pDocTemplate = new CMultiDocTemplate(
IDR_SerAddressBook2TYPE,
RUNTIME_CLASS(CSerAddressBookMDIDoc),
RUNTIME_CLASS(CChildFrame), // custom MDI child frame
RUNTIME_CLASS(CSerAddressBookMDIView));
if (!pDocTemplate)
return FALSE;
AddDocTemplate(pDocTemplate);

//Silviu
pDocTemplate = new CMultiDocTemplate(
IDR_SerAddressBook3TYPE,
RUNTIME_CLASS(CSerAddressBookMDIDoc),
RUNTIME_CLASS(CChildFrame), // custom MDI child frame
RUNTIME_CLASS(CSerAddressBookMDIView));
if (!pDocTemplate)
return FALSE;
AddDocTemplate(pDocTemplate);

// create main MDI Frame window
CMainFrame* pMainFrame = new CMainFrame;
if (!pMainFrame || !pMainFrame->LoadFrame(IDR_SerAddressBookTYPE))
{
delete pMainFrame;
return FALSE;
}

// ———-
// MFC’s wizard generated code…
// ———-

return TRUE;
}
[/cpp]

First point that I should mention, after LoadStdProfileSettings() (function written by MFC wizard) call, is the initialization of m_pDocManager attribute (pointer to CDocManager class, used for document template management) with a new object pointer to CMultiDocManager (class defined be me according with Microsoft Knowledge Base 141921). CMultiDocManager class overwrites some methods from CDocManager: CreateNewDocument(), DoPromptFileName(), OnFileNew().

Then, besides default document application template (with resource ID IDR_SerAddressBookTYPE), I create two new templates for my two different files format.
All templates are added into my document template list (AddDocTemplate()). Last significant change from InitInstance() means the right frame window (IDR_SerAddressBookTYPE – contains Save and Save As options).

Conclusion:
Multiple Document Interface (MDI) architecture is the best for this kind of data container application. MFC framework offers stable and complete support for objects serialization: storing and loading process.
Many of Microsoft Office applications are based on this architecture.

Download demo application: SerAddressBookMDI (Visual C++ 2005 project)