Serialization in the Document Class Definition

The code in the definition of CSketcherDoc that enables serialization of a document object is shown shaded in the following fragment:

class CSketcherDoc : public CDocument
{
protected: // create from serialization only
   CSketcherDoc();
   DECLARE_DYNCREATE(CSketcherDoc)
        
// Rest of the class...
        
// Overrides
public:
   virtual BOOL OnNewDocument();
   virtual void Serialize(CArchive& ar);
        
// Rest of the class...
        
};

There are three things here that relate to serializing a document object:

1. The DECLARE_DYNCREATE() macro.
2. The Serialize() member function.
3. The default class constructor.

DECLARE_DYNCREATE() is a macro that enables objects of the CSketcherDoc class to be created dynamically by the application framework during the serialization input process. It’s matched by a complementary macro, IMPLEMENT_DYNCREATE(), in the class implementation. These macros apply only to classes derived from CObject, but as you will see shortly, they aren’t the only pair of macros that can be used in this context. For any class that you want to serialize, CObject must be a direct or indirect base because it adds the functionality that enables serialization to work. This is why the CElement class was derived from CObject. Almost all MFC classes are derived from CObject and are serializable.

The CSketcherDoc class definition also includes a declaration for a virtual function Serialize(). Every class that’s serializable must include this function. It’s called to perform both input and output serialization operations on the data members of the class. The object of type CArchive that’s passed as an argument determines whether the operation that is to occur is input or output. You’ll explore this in more detail when considering the implementation of serialization for the document class.

Note that the class explicitly defines a default constructor. This is also essential for serialization to work because the default constructor is used by the framework to synthesize an object when reading it from a file. The synthesized object produced by the no-arg constructor is filled out with the data from the file to set the values of the data members of the object.

Serialization in the Document Class Implementation

There are two bits of the SketcherDoc.cpp file that relate to serialization. The first is the IMPLEMENT_DYNCREATE() macro that complements the DECLARE_DYNCREATE() macro:

// SketcherDoc.cpp : implementation of the CSketcherDoc class
//
        
#include "stdafx.h"
// SHARED_HANDLERS can be defined in an ATL project implementing preview, 
// thumbnail and search filter handlers and allows sharing of document code
// with that project.
#ifndef SHARED_HANDLERS
#include "Sketcher.h"
#endif
        
#include "SketcherDoc.h"
#include "PenDialog.h"
        
#include <propkey.h>
        
#ifdef _DEBUG
#define new DEBUG_NEW
#endif
        
// CSketcherDoc
        
        
IMPLEMENT_DYNCREATE(CSketcherDoc, CDocument)
        
// Message map and the rest of the file...

This macro defines the base class for CSketcherDoc as CDocument. This is required for the proper dynamic creation of a CSketcherDoc object, including members that are inherited.

void CSketcherDoc::Serialize(CArchive& ar)
{
   if (ar.IsStoring())
   {
      // TODO: add storing code here
   }
   else
   {
      // TODO: add loading code here
   }
}

Functionality of CObject-Based Classes

There are three levels of functionality available in your classes when they’re derived from the MFC class CObject. The level you get in your class is determined by which of three different macros you use in the definition of your class:

Each of these macros requires that a complementary macro, named with the prefix IMPLEMENT_ instead of DECLARE_, be placed in the file containing the class implementation. As the table indicates, the macros provide progressively more functionality, so I’ll concentrate on the third macro, DECLARE_SERIAL(), because it provides everything that the preceding macros do and more. This is the macro you should use to enable serialization in your own classes. It requires that the macro IMPLEMENT_SERIAL() be added to the file containing the class implementation.

You may be wondering why the document class uses DECLARE_DYNCREATE() and not DECLARE_SERIAL(). The DECLARE_DYNCREATE() macro provides the capability for dynamic creation of the objects of the class in which it appears. The DECLARE_SERIAL() macro provides the capability for serialization of the class, plus the dynamic creation of objects of the class, so it incorporates the effects of DECLARE_DYNCREATE(). Your document class doesn’t need serialization because the framework only has to synthesize the document object and then restore the values of its data members; however, the data members of a document do need to be serializable, because this is the process used to store and retrieve them.

DECLARE_SERIAL(CElement)

IMPLEMENT_SERIAL(CElement, CObject, 1001)

How Serialization Works

The overall process of serializing a document is illustrated in a simplified form in Figure 17-1.

The Serialize() function in the document object calls the Serialize() function (or uses an overloaded insertion operator) for each of its data members. Where a member is a class object, the Serialize() function for that object serializes each of its data members in turn until eventually, basic data types are written to the file. Because most classes in MFC ultimately derive from CObject, they contain serialization support, so you can almost always serialize MFC class objects.

The data that you’ll deal with in the Serialize() member functions of your classes and the application document object are just the data members. The structure of the classes that are involved and any other data necessary to reconstitute your original objects are automatically taken care of by the CArchive object.

Where you derive multiple levels of classes from CObject, the Serialize() function in a class must call the Serialize() member of its direct base class to ensure that the direct base class data members are serialized. Note that serialization doesn’t support multiple inheritance, so there can only be one base class for each class defined in a hierarchy.

How to Implement Serialization for a Class

From the previous discussion, I can summarize the steps that you need to take to add serialization to a class:

1. Make sure that the class is derived directly or indirectly from CObject.
2. Add the DECLARE_SERIAL() macro to the class definition (and to the direct base class if the direct base is not CObject or another standard MFC class).
3. Declare the Serialize() function as a member function of your class.
4. Add the IMPLEMENT_SERIAL() macro to the file containing the class implementation.
5. Implement the Serialize() function for your class.

Now let’s look at how you can implement serialization for documents in Sketcher.

Recording Document Changes

There’s already a mechanism for noting when a document changes. It uses an inherited member of the CSketcherDoc class, SetModifiedFlag(). By calling this function consistently whenever the document changes, you can record the fact that the document has been altered in a data member of the document class object. This causes a prompt to be automatically displayed when you try to exit the application without saving the modified document. The argument to the SetModifiedFlag() function is a value of type BOOL, and the default value is TRUE. When you have occasion to specify that the document was unchanged, you can call this function with the argument FALSE.

At present, there are four occasions when you alter a sketch in the document object:

• When you call the AddElement() member of CSketcherDoc to add a new element.
• When you call the DeleteElement() member of CSketcherDoc to delete an element.
• When you call SendToBack() for the document object.
• When you move an element.

You can handle these situations easily. All you need to do is add a call to SetModifiedFlag() to each of the functions involved in these operations. The definition of AddElement() appears in the CSketcherDoc class definition. You can extend this to:

void AddElement(std::shared_ptr<CElement>& pElement)  // Add an element to the list
{
  m_Sketch.push_back(pElement); 
  UpdateAllViews(nullptr, 0, pElement.get());        // Tell all the views
  SetModifiedFlag();                                 // Set the modified flag
}

The definition of DeleteElement() is also in the CSketcherDoc definition. You should add one line to it, as follows:

void DeleteElement(std::shared_ptr<CElement>& pElement) 
{
  m_Sketch.remove(pElement);
  UpdateAllViews(nullptr, 0,  pElement.get());       // Tell all the views
  SetModifiedFlag();                                 // Set the modified flag
}

The SendToBack() function needs to have the same line added:

void SendToBack(std::shared_ptr<CElement>& pElement)
{
  if(pElement)
  {
    m_Sketch.remove(pElement);                // Remove the element from the list
    m_Sketch.push_back(pElement);             // Put a copy at the end of the list
    SetModifiedFlag();                        // Set the modified flag
  }
}

Moving an element occurs in the MoveElement() member of a view object that is called by the handler for the WM_MOUSEMOVE message, but you only change the document when the left mouse button is pressed. If there’s a right-button click, the element is put back to its original position, so you only need to call the SetModifiedFlag() function for the document in the OnLButtonDown() function:

void CSketcherView::OnLButtonDown(UINT nFlags, CPoint point)
{
  CClientDC aDC{this};                                // Create a device context
  OnPrepareDC(&aDC);                                  // Get origin adjusted
  aDC.DPtoLP(&point);                                 // convert point to Logical
  CSketcherDoc* pDoc {GetDocument()};                 // Get a document pointer
        
  if(m_MoveMode)
  { // In moving mode, so drop the element
    m_MoveMode = false;                               // Kill move mode
    auto pElement(m_pSelected);                       // Store selected address
    m_pSelected.reset();                              // De-select the element
    pDoc->UpdateAllViews(nullptr, 0, pElement.get()); // Redraw all the views
    pDoc->SetModifiedFlag();                          // Set the modified flag
  }
  // Rest of the function as before...
}

You call the inherited GetDocument() member of the view class to get access to a pointer to the document object and then use this pointer to call the SetModifiedFlag() function.

You now have all the places where you change the sketch. The document object also stores the element type, the element color and the pen width, so you need to track when they change too. Here’s how you can update OnColorBlack() for example:

void CSketcherDoc::OnColorBlack()
{
   m_Color = ElementColor::BLACK;                // Set the drawing color to black
   SetModifiedFlag();                            // Set the modified flag
}

Add the same statement to each of the handlers for the other colors and the element types. The handler for setting the pen width needs to be updated like this:

void CSketcherDoc::OnPenWidth()
{
     CPenDialog aDlg;                     // Create a local dialog object
    aDlg.m_PenWidth = m_PenWidth;         // Set pen width as that in the document
 
    if(aDlg.DoModal() == IDOK)             // Display the dialog as modal
    {
      m_PenWidth = aDlg.m_PenWidth;       // When closed with OK, get the pen width
     SetModifiedFlag();                   // Set the modified flag
    }
}

If you build and run Sketcher, and modify a document or add elements to it, you’ll now get a prompt to save the document when you exit the program. Of course, the File Save menu option doesn’t do anything yet except clear the modified flag and save an empty file to disk. You must implement serialization to get the document written to disk, and that’s the next step.

Serializing the Document

The first step is to implement the Serialize() function for the CSketcherDoc class. Within this function, you must add code to serialize the data members of CSketcherDoc. The data members that you have declared in the class are as follows:

protected:
  ElementType m_Element{ElementType::LINE };        // Current element type
  ElementColor m_Color{ ElementColor::BLACK };      // Current drawing color
  std::list<std::shared_ptr<CElement>> m_Sketch;    // A list containing the sketch
  int m_PenWidth{};                                 // Current pen width
  CSize m_DocSize { CSize{ 3000, 3000 } };          // Document size

These have to be serialized to allow a CSketcherDoc object to be deserialized. You need to insert the statements to store and retrieve these data members in the Serialize() member of the class. However, there is a slight problem. The list< std::shared_ptr<CElement>> object is not serializable because the template is not derived from CObject. In fact, none of the STL containers are serializeable, so you always have to take care of serializing STL containers yourself.

All is not lost, however. If you can serialize the objects that the pointers in the container point to, you will be able to reconstruct the container when you read it back.

You can implement serialization for the document object with the following code:

void CSketcherDoc::Serialize(CArchive& ar)
{
  if (ar.IsStoring())
  {
    ar << static_cast<COLORREF>(m_Color)        // Store the current color
       << static_cast<int>(m_Element)           // the element type as an integer
       << m_PenWidth                            // and the current pen width
       << m_DocSize;                            // and the current document size
       
    ar << m_Sketch.size();             // Store the number of elements in the list
 
    // Now store the elements from the list
    for(const auto& pElement : m_Sketch)
      ar << pElement.get();                     // Store the element pointer
  }
  else
  {
    COLORREF color {};
    int elementType {};
    ar >> color                                 // Retrieve the current color
       >> elementType                           // the element type as an integer
       >> m_PenWidth                            // and the current pen width
       >> m_DocSize;                            // and the current document size
    m_Color = static_cast<ElementColor>(color);
    m_Element = static_cast<ElementType>(elementType);
 
    // Now retrieve all the elements and store in the list
    size_t elementCount {};                     // Count of number of elements
    ar >> elementCount;                         // retrieve the element count
    CElement* pElement;
    for(size_t i {} ; i < elementCount ; ++i)
    {
      ar >> pElement;
      m_Sketch.push_back(std::shared_ptr<CElement>(pElement));
    }
  }
}

For four of the data members, you just use the extraction and insertion operators that are overloaded in the CArchive class. This won’t work for m_Color because the ElementColor type is not serializable. However, you can cast it to type COLORREF, which is serializable because type COLORREF is the same as type long. The m_Element member is of type ElementType, and the serialization process won’t handle this directly either. However, you can cast it to an integer for serialization, and then just deserialize it as an integer before casting the value back to ElementType.

For the list of elements, m_Sketch, you first store the count of the number of elements in the list because you will need this to be able to read the elements back. You then write the element pointers that are contained in the shared_ptr objects from the list to the archive in the for loop. Something remarkable happens as a result. The serialization mechanism recognizes that the objects pointed to will be required to reconstruct the document, and will take care of writing those to the archive.

The else clause for the if deals with reading the document object back from the archive. You use the extraction operator to retrieve the first four members from the archive in the same sequence that they were written. The color and element type are read into the local integer variables, color and elementType, and then stored in the m_Color and m_Element members as the correct type.

You read the number of elements recorded in the archive and store it locally in elementCount. Finally, you use elementCount to control the for loop that reads the elements back from the archive and stores them in the list. Note that you don’t need to do anything special to take account of the fact that the elements were originally created on the heap. The serialization mechanism takes care of restoring the elements on the heap automatically; all you need to do is pass the pointer for each element to the shared_ptr<CElement> constructor.

In case you are wondering where the list<shared_ptr<CElement>> object comes from when you are deserializing an object, it will be created by the serialization process using the default constructor for the CSketcherDoc class. This is how the basic document object and its uninitialized data members get created. Like magic, isn’t it?

That’s all you need for serializing the document class data members, but serializing elements from the list causes the Serialize() functions for the element classes to be called to store and retrieve the elements themselves, so you also need to implement serialization for those classes.

Serializing the Element Classes

All the element classes are serializable in principle because their base class, CElement, is derived from CObject. You specified CObject as the base for CElement solely to get support for serialization. Make sure that the default constructor is defined for each of the element classes. The deserialization process requires that this constructor be defined.

You can add support for serialization to each of the element classes by adding the appropriate macros to the class definitions and implementations, and adding the code to the Serialize() member function of each class to serialize its data members. You can start with the base class, CElement, where you need to modify the class definition as follows:

class CElement: public CObject
{
DECLARE_SERIAL(CElement)
protected:
  CPoint m_StartPoint;                         // Element position      
  int m_PenWidth;                              // Pen width
  COLORREF m_Color;                              // Color of an element
  CRect m_EnclosingRect;                         // Rectangle enclosing an element
 
public:
  virtual ~CElement();
  virtual void Draw(CDC* pDC, std::shared_ptr<CElement> pElement=nullptr) {} 
  virtual void Move(const CSize& aSize) {}       // Move an element
  virtual void Serialize(CArchive& ar)  override; // Serialize object
 
 
  // Get the element enclosing rectangle 
  const CRect& GetEnclosingRect() const 
  {
    return m_EnclosingRect;
  }
 
protected:
  // Constructors protected so they cannot be called outside the class
  CElement();              
  CElement(const CPoint& start, COLORREF color, int penWidth = 1);
 
  // Create a pen
  void CreatePen(CPen& aPen, std::shared_ptr<CElement> pElement)
  {
  if(!aPen.CreatePen(PS_SOLID, m_PenWidth,
                              (this == pElement.get()) ? SELECT_COLOR : m_Color))
   {
        // Pen creation failed
        AfxMessageBox(_T("Pen creation failed."), MB_OK); 
        AfxAbort();
   }
 }
};

You add the DECLARE_SERIAL() macro and a declaration for the virtual function Serialize(). You already have the default constructor that was created by the Application Wizard. You changed it to protected in the class, although it doesn’t matter what its access specification is as long as it appears explicitly in the class definition. It can be public, protected, or private, and serialization still works. If you forget to include a default constructor in a class, though, you’ll get an error message when the IMPLEMENT_SERIAL() macro is compiled.

You should add the DECLARE_SERIAL() macro to each of the derived classes CLine, CRectangle, CCircle, CCurve, and CText, with the relevant class name as the argument. You should also add an override declaration for the Serialize() function as a public member of each class.

In the file Element.cpp, you must add the following macro at the beginning:

IMPLEMENT_SERIAL(CElement, CObject, VERSION_NUMBER)

You can define the static constant VERSION_NUMBER in the Element.h file by adding the definition after the other static constant:

static const UINT VERSION_NUMBER {1001};     // Version number for serialization

You can then use the same constant when you add the macro to the .cpp file for each of the other element classes. For instance, for the CLine class you should add the line,

IMPLEMENT_SERIAL(CLine, CElement, VERSION_NUMBER)

and similarly for the other element classes. When you modify any of the classes relating to the document, all you need to do is change the definition of VERSION_NUMBER in the Element.h file, and the new version number applies in all your Serialize() functions.

void CElement::Serialize(CArchive& ar)
{
  CObject::Serialize(ar);              // Call the base class function
        
  if (ar.IsStoring())
   { // Writing to the file
     ar << m_StartPoint                // Element position 
        << m_PenWidth                  // The pen width
        << m_Color                     // The element color
        << m_EnclosingRect;            // The enclosing rectangle
  }
  else
  {  // Reading from the file
     ar >> m_StartPoint                // Element position 
        >> m_PenWidth                  // The pen width
        >> m_Color                     // The element color
        >> m_EnclosingRect;            // The enclosing rectangle
  }
}

void CLine::Serialize(CArchive& ar)
{
  CElement::Serialize(ar);             // Call the base class function
        
  if (ar.IsStoring())
  { // Writing to the file
    ar << m_EndPoint;                  // The end point
  }
  else
  { // Reading from the file
    ar >> m_EndPoint;                  // The end point 
  }
}

void CRectangle::Serialize(CArchive& ar)
{
  CElement::Serialize(ar);             // Call the base class function
  if (ar.IsStoring())
  { // Writing to the file
    ar << m_BottomRight;               // Bottom-right point for the rectangle
  }
  else
  { // Reading from the file
    ar >> m_BottomRight;
  }
}

void CCircle::Serialize(CArchive& ar)
{
  CElement::Serialize(ar);             // Call the base class function
  if (ar.IsStoring())
  { // Writing to the file
    ar << m_BottomRight;               // Bottom-right point for the circle 
  }
  else
  { // Reading from the file
    ar >> m_BottomRight;
  }
}

void CCurve::Serialize(CArchive& ar)
{
  CElement::Serialize(ar);             // Call the base class function
  // Serialize the vector of points
  if (ar.IsStoring())
  {
    ar << m_Points.size();             // Store the point count
    // Now store the points
    for)const auto& Point : m_Points)
      ar << point;
  }
  else
  {
    size_t nPoints {};                 // Stores number of points
    ar >> nPoints;                     // Retrieve the number of points
    // Now retrieve the points
    CPoint point;
    for(size_t i {} i < nPoints; ++i)
    {
      ar >> point;
      m_Points.push_back(point);
    }
  }
}

void CText::Serialize(CArchive& ar)
{
  CElement::Serialize(ar);             // Call the base class function
        
  if (ar.IsStoring())
  {
      ar << m_String;                  // Store the text string
  }
  else
  {
      ar >> m_String;                  // Retrieve the text string
  }
}

The Printing Process

Printing a document is controlled by the current view. The process is inevitably a bit messy because printing is inherently a messy business, and it potentially involves you in overriding quite a number of inherited functions in your view class. Figure 17-5 shows the logic of the process and the functions involved. It also shows how the sequence of events is controlled by the framework and how printing a document involves calling five inherited members of your view class, which you may need to override. The CDC member functions shown on the left side of the diagram communicate with the printer device driver and are called automatically by the framework.

The typical role of each of the functions in the current view during a print operation is specified in the notes alongside it. The sequence in which they are called is indicated by the numbers on the arrows. In practice, you don’t need to implement all of these functions, only those that you want to for your particular printing requirements. Typically, you’ll want at least to implement your own versions of OnPreparePrinting(), OnPrepareDC(), and OnPrint(). You’ll see an example of how these functions can be implemented in the context of Sketcher a little later in this chapter.

You write data to a printer in the same way as you write data to the display — through a device context. The GDI calls that you use to output text or graphics are device-independent, so they work just as well for a printer as they do for a display. The only difference is the physical output device to which the CDC object applies.

The CDC functions in Figure 17-5 communicate with the device driver for the printer. If the document to be printed requires more than one printed page, the process loops back to call the OnPrepareDC() function for each successive new page, as determined by the EndPage() function. All the functions in your view class that are involved in the printing process are passed a pointer to a CPrintInfo object that provides a link between all the functions that manage the printing process, so let’s take a look at the CPrintInfo class in more detail.

The CPrintInfo Class

A CPrintInfo object has a fundamental role in the printing process because it stores information about the print job being executed and details of its status at any time. It also provides functions for accessing and manipulating this data. This object is the means by which information is passed from one view function to another during printing, and between the framework and your view functions.

A CPrintInfo object is created whenever you select the File Print or File Print Preview menu options. It will be used by each of the functions in the current view that are involved in the printing process, and it is automatically deleted when the print operation ends.

All the data members of CPrintInfo are public. The ones we are interested in for printing sketches are shown in the following table.

MEMBER	USAGE
m_pPD	A pointer to the CPrintDialog object that displays the Print dialog.
m_bDirect	This is set to TRUE by the framework if the print operation is to bypass the Print dialog; otherwise, FALSE.
m_bPreview	A member of type BOOL that has the value TRUE if File Print Preview was selected; otherwise, FALSE.
m_bContinuePrinting	A member of type BOOL. If it is TRUE, the framework continues the printing loop shown in the diagram. If it’s FALSE, the printing loop ends. You only need to set this variable if you don’t pass a page count for the print operation to the CPrintInfo object (using the SetMaxPage() member). In this case, you’ll be responsible for signaling when you are finished by setting this variable to FALSE.
m_nCurPage	A value of type UINT that stores the page number of the current page. Pages are usually numbered starting from 1.
m_nNumPreviewPages	A value of type UINT that specifies the number of pages displayed in the Print Preview window. This can be 1 or 2.
m_lpUserData	This is of type LPVOID and stores a pointer to an object that you create. This allows you to create an object to store additional information about the printing operation and associate it with the CPrintInfo object.
m_rectDraw	A CRect object that defines the usable area of the page in logical coordinates.
m_strPageDesc	A CString object containing a format string used by the framework to display page numbers during print preview.

A CPrintInfo object has the public member functions shown in the following table.

FUNCTION	DESCRIPTION
SetMinPage( UINT nMinPage)	The argument specifies the number of the first page of the document. There is no return value.
SetMaxPage( UINT nMaxPage)	The argument specifies the number of the last page of the document. There is no return value.
GetMinPage() const	Returns the number of the first page of the document as type UINT.
GetMaxPage() const	Returns the number of the last page of the document as type UINT.
GetFromPage() const	Returns the number of the first page of the document to be printed as type UINT. This value is set through the print dialog.
GetToPage() const	Returns the number of the last page of the document to be printed as type UINT. This value is set through the print dialog.

When you’re printing a document consisting of several pages, you need to figure out how many printed pages the document will occupy, and store this information in the CPrintInfo object to make it available to the framework. You do this in your version of the OnPreparePrinting() member of the current view.

Page numbers are stored as type UINT. To set the number of the first page in the document, you call the SetMinPage() function for the CPrintInfo object, which accepts the page number as the argument. There’s no return value. To set the number of the last page, you call SetMaxPage(). If you later want to retrieve these values, you call the GetMinPage() and GetMaxPage() functions for the CPrintInfo object.

The page numbers that you supply are stored in the CPrintDialog object pointed to by the m_pPD member of the CPrintInfo object and displayed in the dialog that pops up when you select File Print... from the menu. The user can then specify the numbers of the first and last pages that are to be printed. You can retrieve the page numbers entered by the user by calling the GetFromPage() and GetToPage() members of the CPrintInfo object. In each case, the value returned is of type UINT. The dialog automatically verifies that the numbers of the first and last pages to be printed are within the range you supplied by specifying the minimum and maximum pages of the document.

You now know what functions you can implement in the view class to manage printing for yourself, with the framework doing most of the work. You also know what information is available through the CPrintInfo object that is passed to the functions concerned with printing. You’ll get a much clearer understanding of the detailed mechanics of printing by implementing a basic multipage print capability for Sketcher documents.

Getting the Overall Document Size

To figure out how many pages a particular document occupies, you need to know how big the sketch is, and for this, you want the rectangle that encloses everything in the document. You can do this easily by adding a function GetDocExtent() to the document class, CSketcherDoc. Add the following declaration to the public interface for CSketcherDoc:

CRect GetDocExtent() const;   // Get the bounding rectangle for the whole document

The implementation is no great problem. The code for it is:

// Get the rectangle enclosing the entire document
CRect CSketcherDoc::GetDocExtent()const
{
  if(m_Sketch.empty())                                   // Check for empty sketch
    return CRect {0,0,1,1};
  CRect docExtent {m_Sketch.front()->GetEnclosingRect()}; // Initial doc extent
  for(auto& pElement : m_Sketch) 
    docExtent.UnionRect(docExtent, pElement->GetEnclosingRect());
        
  docExtent.NormalizeRect();
  return docExtent;
}

You can add this function definition to the SketcherDoc.cpp file.

If the sketch is empty, you return a very small CRect object. The initial size of the document extent is the rectangle enclosing the first element in the list. The process then loops through every element in the document, getting the bounding rectangle for each element and combining it with docExtent. The UnionRect() member of the CRect class calculates the smallest rectangle that contains the two rectangles you pass as arguments, and stores that value in the CRect object for which the function is called. Therefore, docExtent keeps increasing in size until all the elements are contained within it.

Storing Print Data

The OnPreparePrinting() function in the view class is called by the application framework to enable you to initialize the printing process for your document. The basic initialization that’s required is to provide information about how many pages are in the document, which is information that the print dialog will display. You should also store information about the pages that your document requires, so you can use it later in the other view functions involved in the printing process. You can create an object of your own class type in the OnPreparePrinting() member of the view class to store this information and store a pointer to the object in the CPrintInfo object that the framework makes available. I adopted this approach primarily to show you how this mechanism works; in many cases you’ll find it easier just to store the data in your view object.

You’ll need to store the number of pages running the width of the document, m_nWidths, and the number of rows of pages down the length of the document, m_nLengths. You’ll also store the upper-left corner of the rectangle enclosing the document data as a CPoint object, m_DocRefPoint, because you’ll need this when you work out the position of a page to be printed from its page number. You can store the filename for the document in a CString object, m_DocTitle, so that you can add it as a title to each page. It will also be useful to record the size of the printable area within the page. The definition of the class to accommodate these is:

#pragma once
        
class CPrintData
{
public:
  UINT printWidth {1000};           // Printable page width - units 0.01 inches
  UINT printLength {1000};          // Printable page length - units 0.01 inches
  UINT m_nWidths;                   // Page count for the width of the document
  UINT m_nLengths;                  // Page count for the length of the document
  CPoint m_DocRefPoint;             // Top-left corner of the document contents
  CString m_DocTitle;               // The name of the document
        
};

The class definition specifies default values for the printable area that corresponds to an A4 page with half-inch margins all round. You can change this to suit your environment, and, of course, you can change the values programmatically in a CPrintData object.

Of course, you could define a constructor for the class and initialize the values of printWidth and printLength there. However, all the data members are public so you can always set their values directly. The CPrintData class is just a vehicle for packaging data items relating to the printing process so there is no necessity for complicating it. Specifying default values for members obviates the need to write constructors and thus simplifies the class definition.

You can add a new header file with the name PrintData.h to the project by right-clicking the Header Files folder in the Solution Explorer pane and then selecting Add New Item from the pop-up. You can now enter the class definition in the new file. You don’t need an implementation file for this class. Because an object of this class is only going to be used transiently, you don’t need to use CObject as a base or to consider any other complication.

The printing process starts with a call to OnPreparePrinting() so I’ll explore how you should implement that next.

Preparing to Print

The Application Wizard has already added versions of OnPreparePrinting(), OnBeginPrinting(), and OnEndPrinting() to CSketcherView. The base code provided for OnPreparePrinting() calls DoPreparePrinting() in the return statement, as you can see:

BOOL CSketcherView::OnPreparePrinting(CPrintInfo* pInfo)
{
   // default preparation
   return DoPreparePrinting(pInfo);
}

The DoPreparePrinting() function displays the Print dialog using information about the number of pages to be printed that is defined in the CPrintInfo object. Whenever possible, you should calculate the number of pages to be printed and store it in the CPrintInfo object before this call occurs. Of course, in many circumstances, you may need information from the device context for the printer before you can do this — when you’re printing a document where the number of pages is going to be affected by the size of the font to be used for example — in which case it won’t be possible to get the page count before you call DoPreparePrinting(). In these circumstances you can compute the number of pages in the OnBeginPrinting() member, which receives a pointer to the device context as an argument. This function is called by the framework after OnPreparePrinting(), so the information entered in the Print dialog is available. This means that you can also take account of the paper size selected by the user in the Print dialog.

Assuming that the page size is large enough to accommodate a 7.5-inch × 10-inch area to draw the document data, you can calculate the number of pages in OnPreparePrinting(). The code to do this is:

BOOL CSketcherView::OnPreparePrinting{CPrintInfo* pInfo}
{
  CPrintData* printData {new CPrintData};   // Create a print data object
  CSketcherDoc* pDoc {GetDocument()};       // Get a document pointer
  CRect docExtent {pDoc->GetDocExtent()};   // Get the whole document area

  printData->m_DocRefPoint = docExtent.TopLeft();// Save document reference point 
  printData->m_DocTitle = pDoc->GetTitle();      // Save the document filename


  // Calculate how many printed page widths are required
  // to accommodate the width of the document
  printData->m_nWidths = static_cast<UINT>(ceil(
                 static_cast<double>(docExtent.Width())/printData->printWidth));

  // Calculate how many printed page lengths are required
  // to accommodate the document length
  printData->m_nLengths = static_cast<UINT>(
            ceil(static_cast<double>(docExtent.Height())/printData->printLength));

  // Set the first page number as 1 and
  // set the last page number as the total number of pages
  pInfo->SetMinPage(1);
  pInfo->SetMaxPage(printData->m_nWidths*printData->m_nLengths);
  pInfo->m_lpUserData = printData;         // Store address of PrintData object
  return DoPreparePrinting(pInfo);
}

You first create a CPrintData object on the heap and store its address locally in the pointer. After getting a pointer to the document, you get the rectangle enclosing all of the elements in the document by calling the function GetDocExtent() that you added to the document class earlier in this chapter. You then store the corner of this rectangle in the m_DocRefPoint member of the CPrintData object, and put the name of the file that contains the document in m_DocTitle.

The next two lines of code calculate the number of pages across the width of the document, and the number of pages required to cover the length. The number of pages to cover the width is computed by dividing the document width by the width of the print area on a page and rounding up to the next highest integer using the ceil() function that is declared in the cmath header. For example, ceil(2.1) returns 3.0, ceil(2.9) also returns 3.0, and ceil(-2.1) returns -2.0. A similar calculation to that for the number of pages across the width of a document produces the number to cover the length. The product of these two values is the total number of pages to be printed, and this is the value that you’ll supply for the maximum page number. The last step is to store the address of the CPrintData object in the m_lpUserData member of the pInfo object.

Don’t forget to add an #include directive for PrintData.h to the SketcherView.cpp file.

Cleaning Up after Printing

Because you created the CPrintData object on the heap, you must ensure that it’s deleted when you’re done with it. You do this by adding code to the OnEndPrinting() function:

void CSketcherView::OnEndPrinting(CDC* /*pDC*/, CPrintInfo* pInfo)
{
   // Delete our print data object
   delete static_cast<CPrintData*>(pInfo->m_lpUserData);
}

That’s all that’s necessary for this function in the Sketcher program, but in some cases, you’ll need to do more. Your one-time final cleanup should be done here. Make sure that you remove the comment delimiters (/* */) from the second parameter name; otherwise, your function won’t compile. The default implementation comments out the parameter names because you may not need to refer to them in your code. Because you use the pInfo parameter, you must uncomment it; otherwise, the compiler reports it as undefined. You don’t need to add anything to the OnBeginPrinting() function in the Sketcher program, but you’d need to add code to allocate any GDI resources, such as pens, if they were required throughout the printing process. You would then delete these as part of the clean-up process in OnEndPrinting().

Preparing the Device Context

At the moment, Sketcher calls OnPrepareDC()for the view object which sets up the mapping mode as MM_ANISOTROPIC to take account of the scaling factor. You must make some additional changes so that the device context is properly prepared in the case of printing:

void CSketcherView::OnPrepareDC(CDC* pDC, CPrintInfo* pInfo)
{
  CScrollView::OnPrepareDC(pDC, pInfo);
  CSketcherDoc* pDoc {GetDocument()};
  pDC->SetMapMode(MM_ANISOTROPIC);           // Set the map mode
  CSize DocSize {pDoc->GetDocSize()};        // Get the document size
  pDC->SetWindowExt(DocSize);                // Now set the window extent
        
  // Get the number of pixels per inch in x and y
  int xLogPixels {pDC->GetDeviceCaps(LOGPIXELSX)};
  int yLogPixels {pDC->GetDeviceCaps(LOGPIXELSY)};
        
  // Calculate the viewport extent in x and y
  int scale {pDC->IsPrinting() ? 1 : m_Scale}; // If we are printing, use scale 1
  int xExtent {(DocSize.cx*scale*xLogPixels)/100};
  int yExtent {(DocSize.cy*scale*yLogPixels)/100};
        
  pDC->SetViewportExt(xExtent, yExtent);     // Set viewport extent
}

This function is called by the framework for output to the printer as well as to the screen. You should make sure that a scale of 1 is used to set the mapping from logical coordinates to device coordinates when you’re printing. If you left everything as it was, the output would be at the current view scale, but you’d need to take account of the scale when calculating how many pages were required, and how you set the origin for each page.

You determine whether or not you have a printer device context by calling the IsPrinting() member of the current CDC object, which returns TRUE if you are printing. When you have a printer device context you set the scale to 1. Of course, you must change the statements calculating the viewport extent to use the local variable scale rather than the m_Scale member of the view.

Printing the Document

You write the data to the printer device context in the OnPrint() function. This is called once for each page. You need to add an override for this function to CSketcherView, using the Properties window for the class. Select OnPrint from the list of overrides and then click <Add> OnPrint in the right column.

You can obtain the page number of the page to be printed from the m_nCurPage member of the CPrintInfo object that is passed to the function. You can then use this value to work out the coordinates of the point in the document that corresponds to the upper-left corner of the current page. The way to do this is best understood using an example, so imagine that you are printing page 7 of an 8-page document, as illustrated in Figure 17-7.

Remember that these are in logical coordinates and x is positive from left to right and y is increasingly negative from top to bottom. You can get an index to the horizontal position of the page by decrementing the page number by 1 and taking the remainder after dividing by the number of page widths required for the width of the document. Multiplying the result by printWidth produces the x-coordinate of the upper-left corner of the page, relative to the upper-left corner of the rectangle enclosing the elements in the document. Similarly, you can determine the index to the vertical position of the document by dividing the current page number reduced by 1 by the number of page widths required for the horizontal width of the document. By multiplying the result by printLength, you get the relative y-coordinate of the upper-left corner of the page. You can express this in the following statements:

CPrintData* p {static_cast<CPrintData*>(pInfo->m_lpUserData)};
int xOrg {p->m_DocRefPoint.x {static_cast<int>( p->printWidth*
                                        ((pInfo->m_nCurPage - 1)%(p->m_nWidths)))};
int yOrg {p->m_DocRefPoint.y {static_cast<int>( p->printLength*
                                         ((pInfo->m_nCurPage - 1)/(p->m_nWidths)))};

It would be nice to print the filename of the document at the top of each page and, perhaps, a page number at the bottom, but you want to be sure you don’t print the document data over the filename and page number. You also want to center the printed area on the page. You can do this by moving the origin of the coordinate system in the printer device context after you have printed the filename. This is illustrated in Figure 17-8.

Figure 17-8 illustrates the correspondence between the printed page area in the device context and the page to be printed in the reference frame of the document data. The diagram shows the expressions for the offsets from the page origin for the printWidth by printLength area where you are going to print the page. You want to print the information from the document in the dashed area shown on the printed page in Figure 17-8, so you need to map the xOrg, yOrg point in the document to the position shown in the printed page, which is displaced from the page origin by the offset values xOffset and yOffset.

By default, the origin in the coordinate system that you use to define elements in the document is mapped to the origin of the device context, but you can change this. The CDC object provides a SetWindowOrg() function for this purpose. This enables you to define a point in the document’s logical coordinate system that you want to correspond to the origin in the device context, in this case the point where (0,0) for the printer output will be. It’s important to save the old origin that’s returned from the SetWindowOrg() function. You must restore the old origin when you’ve finished drawing the current page; otherwise the m_rectDraw member of the CPrintInfo object is not set up correctly when you print the next page.

The point in the document that you want to map to the origin of the page has the coordinates xOrg-xOffset,yOrg-yOffset. This may not be easy to visualize, but remember that by setting the window origin, you’re defining the point that maps to the viewport origin. If you think about it, you should see that the xOrg, yOrg point in the document is where you want it on the page.

The complete code for printing a page of the document is:

// Print a page of the document
void CSketcherView::OnPrint(CDC* pDC, CPrintInfo* pInfo)
{
  CPrintData* p{static_cast<CPrintData*>(pInfo->m_lpUserData)};

  // Output the document filename
  pDC->SetTextAlign(TA_CENTER);        // Center the following text
  pDC->TextOut(pInfo->m_rectDraw.right/2, 20, p->m_DocTitle);
  CString str; 
  str.Format(_T("Page %u") , pInfo->m_nCurPage);
  pDC->TextOut(pInfo->m_rectDraw.right/2, pInfo->m_rectDraw.bottom-20, str);
  pDC->SetTextAlign(TA_LEFT);          // Left justify text

  // Calculate the origin point for the current page
  int xOrg {static_cast<int>(p->m_DocRefPoint.x + 
                           p->printWidth*((pInfo->m_nCurPage - 1)%(p->m_nWidths)))};

  int yOrg {static_cast<int>( p->m_DocRefPoint.y +
                          p->printLength*((pInfo->m_nCurPage - 1)/(p->m_nWidths)))};


  // Calculate offsets to center drawing area on page as positive values
  int xOffset {static_cast<int>((pInfo->m_rectDraw.right - p->printWidth)/2)};
  int yOffset {static_cast<int>((pInfo->m_rectDraw.bottom - p->printLength)/2)};

  // Change window origin to correspond to current page & save old origin
  CPoint OldOrg {pDC->SetWindowOrg(xOrg - xOffset, yOrg - yOffset)};

  // Define a clip rectangle the size of the printed area
  pDC->IntersectClipRect(xOrg, yOrg, xOrg + p->printWidth, yOrg + p->printLength);

  OnDraw(pDC);                         // Draw the whole document
  pDC->SelectClipRgn(nullptr);         // Remove the clip rectangle
  pDC->SetWindowOrg(OldOrg);           // Restore old window origin
}

The first step is to initialize the local pointer, p, with the address of the CPrintData object that is stored in the m_lpUserData member of the object to which pInfo points. You then output the file-name that you squirreled away in the CPrintData object. The SetTextAlign() member function of the CDC object allows you to define the alignment of subsequent text output in relation to the reference point you supply for the text string in the TextOut() function. The alignment is determined by the constant passed as an argument to the function. You have three possibilities for specifying the horizontal alignment of the text, as shown in the following table.

You define the x-coordinate of the filename on the page as half the page width, and the y-coordinate as 20 units, which is 0.2 inches, from the top of the page.

After outputting the name of the document file as centered text, you output the page number centered at the bottom of the page. You use the Format() member of the CString class to format the page number stored in the m_nCurPage member of the CPrintInfo object. This is positioned 20 units up from the bottom of the page. You then reset the text alignment to the default setting, TA_LEFT.

The SetTextAlign() function also allows you to change the position of the text vertically by OR-ing a second flag with the justification flag. The second flag can be any of those shown in the following table.

The next action in OnPrint() uses the method that I discussed for mapping an area of the document to the current page. You get the document drawn on the page by calling the OnDraw() function that is used to display the document in the view. This potentially draws the entire document, but you can restrict what appears on the page by defining a clip rectangle. A clip rectangle encloses a rectangular area in the device context within which output appears. Output is suppressed outside of the clip rectangle. It’s also possible to define irregularly shaped areas for clipping, called regions.

The initial default clipping area defined in the print device context is the page boundary. You define a clip rectangle that corresponds to the printWidth by printLength area centered in the page. This ensures that you draw only in this area and the filename and page number will not be overwritten.

After the current page has been drawn by the OnDraw() function call, you call SelectClipRgn() with a nullptr argument to remove the clip rectangle. If you don’t do this, output of the document title is suppressed on all pages after the first, because it lies outside the clip rectangle that would otherwise remain in effect in the print process until the next time IntersectClipRect() gets called.

Your final action is to call SetWindowOrg() again to restore the window origin to its original location, as discussed earlier in this chapter.

Getting a Printout of the Document

To get your first printed Sketcher document, you just need to build the project and execute the program (once you’ve fixed any typos). If you try File Print Preview and click on the Two Page button, you should get something similar to the window shown in Figure 17-9.

You get print preview functionality completely for free. The framework uses the code that you’ve supplied for the normal multipage printing operation to produce page images in the Print Preview window. What you see in the Print Preview window should be exactly the same as appears on the printed page.

EXERCISES

1. Update the code in the OnPrint() function in Sketcher so that the page number is printed at the bottom of each page of the document in the form “Page n of m,” where n is the current page number and m is the total number of pages.
2. As a further enhancement to the CText class in Sketcher, change the implementation so that scaling works properly with text. (Hint: Look up the CreatePointFont() function in the online help.)

WHAT YOU LEARNED IN THIS CHAPTER