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.

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 );

Related topics

IXpsOMCanvas Interface

IXpsOMVisual Interface

IXpsOMVisualCollection Interface