Inside Macintosh: OpenDoc Programmer's Guide / Part 2 - Programming

Chapter 4 - Drawing

Canvases

Canvases are inherently platform specific. OpenDoc canvas objects are basically wrappers for structures that differ across platforms. This section discusses how to use canvas objects regardless of the platform for which you are developing, with some information specific to the Mac OS platform provided where appropriate.

Using Canvases

The class ODCanvas is OpenDoc's wrapper for a platform-specific (or graphics-
system-specific) structure that represents a drawing environment. A drawing canvas can refer to anything from a bitmap or a structured display list to a stream of PostScript™ code. It represents the destination for drawing commands, the environment for constructing a rendered image. A canvas has a coordinate system and may retain state information (for example, pen color) that influences how the system interprets drawing commands.

On the Mac OS platform, for example, a canvas could represent an onscreen or offscreen graphics port under the QuickDraw graphics system or a view port under the QuickDraw GX graphics system. A canvas object holds a reference to its graphics port or other system-specific structure, and that structure is not deleted when the canvas is released. If you create a canvas, you must create the underlying structure separately, and you are responsible for deleting that structure when the canvas is deleted.

Canvas Features

Canvases are either dynamic or static--that is, they are used either for video display or for printing display, respectively. Your part editor can determine whether it is drawing to a static or dynamic canvas and adjust its procedures accordingly.

Canvases can be onscreen or offscreen. Your part editor can create special effects or improve performance by a drawing a complex image to an offscreen cache and then quickly transferring the completed image to the screen. For added convenience, offscreen canvases maintain clipping and updating information that mirrors their onscreen equivalents.

Canvases are attached to individual facets. See, for example, Figure 4-1, which shows the same document with the same facet hierarchy as in Figure 3-1. The document in the figure has two attached canvases:

• An offscreen canvas is attached to the movie part's facet.
• An onscreen canvas is attached to the root part's facet. (A canvas attached to the root facet of a window is also called a window canvas; every window has a window canvas, assigned to its root facet by OpenDoc when you first register the window.)

Figure 4-1 Facets and canvases

If a particular facet in a window's facet hierarchy has an attached canvas, all of its embedded facets (and their embedded facets, and so on) draw to that canvas. Thus, for most drawing, only a window's root facet needs a canvas. In Figure 4-1, for example, any drawing done to the text facet, draw facet, or clock facet is rendered on the window canvas.

However, if a particular part needs an offscreen canvas, for itself or for an embedded part, it can attach a canvas to a facet anywhere within the hierarchy. Any drawing done to the movie facet in Figure 4-1, for example, is rendered on the offscreen canvas.

The onscreen canvas in Figure 4-1 is the parent canvas of the offscreen canvas; that is, it is the canvas immediately above the offscreen canvas in the facet hierarchy. Every canvas has an owner, a part that is responsible for transferring images drawn on its canvas to the parent of that canvas. In Figure 4-1, for example, the movie images drawn to the offscreen canvas must be transferred to the window canvas in order to be viewed onscreen. The owner decides when and how to transfer images from a canvas to its parent. The owner of the offscreen canvas in Figure 4-1 might be the movie part or the text part that contains the movie part.

Adding and Removing Canvases

This section describes how to create and delete canvases for your parts. For specific information on using canvases for offscreen drawing, see "Offscreen Drawing".

If you want to create a canvas and attach it to a facet, take these steps:

1. Create and initialize the platform-specific drawing structure that underlies the canvas.
2. Create a canvas object, using the CreateCanvas method of ODFacet or ODWindowState. In calling the method you assign the platform-specific drawing structure to the new canvas, and you also define the canvas as static or dynamic, and onscreen or offscreen. (These values cannot change for the lifetime of the canvas.)
3. Designate your part as owner of the canvas by calling the SetOwner method of the canvas.
4. Assign the canvas to a facet. Because only the owner of a canvas can remove it from a facet, the timing of assigning the canvas is important:
   • If your part is a containing part assigning an offscreen canvas to one of its embedded parts, you should assign the canvas when you first create the embedded facet--that is, when you first call the CreateEmbeddedFacet method of the embedded part's containing facet. Otherwise, the embedded part may assign a canvas to the facet, precluding you from doing so.
   • If your part is a containing part and one of its embedded parts has an existing facet with no assigned canvas, you can add one by calling the ChangeCanvas method of the embedded facet. When you do so, OpenDoc communicates the change to all embedded parts that use that facet, by calling their CanvasChanged methods.
   • Your part can add a canvas to any of its own display frames' facets at any time, as long as the facet does not already have an assigned canvas. It is probably best to attach the canvas as soon as the facet is created, by calling ChangeCanvas from within your part's FacetAdded method. If the containing part of your part has already attached a canvas to your new facet, you cannot assign a different canvas to it.
   • If your part absolutely needs to attach its own canvas to a facet that already has an assigned canvas, you can get around this restriction by creating a subframe of the facet's frame, creating a facet for that frame, and assigning the canvas to that facet.

To remove a canvas from a facet, take these steps:

1. Call the facet's ChangeCanvas method, passing it a null value for the canvas reference.
2. Delete the graphics-system-specific structures that the canvas had referenced.
3. Delete the canvas object, by calling delete (in C++).

Main | Page One | What's New | Apple Computer, Inc. | Find It | Contact Us | Help