Working with XPS OM Canvas and Visual Interfaces
This topic describes how to use the canvas-related interfaces of the XPS Document API in an XPS OM.
| Interface name | Logical child interfaces | Description |
|---|---|---|
The base class of the interfaces that define visual objects, such as text and graphics. Visual objects can be collected in an IXpsOMVisualCollection interface. |
||
A collection of visual objects that can be treated as a single visual object. |
IXpsOMVisual is the base interface; the visible objects of a page inherit from it. IXpsOMCanvas inherits from IXpsOMVisual and enables many other visual elements to be grouped and acted upon as a single visual element. For example, you could use an IXpsOMCanvas interface to create a page banner that contains a collection of text and graphical elements. Such a banner might contain a logo, the company slogan, and the company address. You could place all these elements into the IXpsOMVisualCollection of an IXpsOMCanvas interface, and then apply a single transform to the IXpsOMCanvas object to resize it to a particular page. This is much simpler than computing and applying a transform to each individual visual component in the banner.
You can also use a canvas to resize the page contents to fit the current page size. To accomplish this, place all contents of the page into a single canvas, then apply the appropriate transform to fit the canvas to the current page size. This is also much simpler than trying to resize each visual element in the collection of visuals in the page.
Move page contents to a canvas
The following code example moves the contents of a page to a canvas.
HRESULT hr = S_OK;
IXpsOMVisualCollection *pageVisuals;
IXpsOMVisualCollection *canvasVisuals;
IXpsOMVisual *oneVisual;
IXpsOMCanvas *newPageCanvas;
UINT32 numVisuals = 0;
UINT32 thisVisual;
// get the page's visual collection
// and how many objects it contains
hr = page->GetVisuals( &pageVisuals );
hr = pageVisuals->GetCount ( &numVisuals );
// create the new canvas object and
// its (empty) visual collection
hr = xpsFactory->CreateCanvas ( &newPageCanvas );
hr = newPageCanvas->GetVisuals ( &canvasVisuals );
// go through the page's list of visual objects,
// move each one from the page's list to the canvas' list
// release the local pointer
// remove it from the page's collection
thisVisual = 0;
while (thisVisual < numVisuals) {
hr = pageVisuals->GetAt (0, &oneVisual);
hr = canvasVisuals->Append (oneVisual);
hr = pageVisuals->RemoveAt (0);
thisVisual++;
}
// the page's visual collection should be empty
hr = pageVisuals->GetCount (&numVisuals);
_ASSERT (0 == numVisuals);
// add the new canvas to the page's visual collection
pageVisuals->Append ( newPageCanvas );