TweetFollow Us on Twitter

March 95 - Getting Started With OpenDoc Graphics

Getting Started With OpenDoc Graphics

Kurt Piersol

The layout and imaging services offered by OpenDoc, Apple's compound-document architecture, provide extremely powerful support for document layout. However, with power comes a certain amount of complexity. The introduction to OpenDoc graphics given in this article reduces some common graphics operations to simple recipes. By following these recipes, you'll get a sense of how to use OpenDoc that you can later build on as you learn about its more sophisticated capabilities.

OpenDoc's layout and graphics model is designed to allow maximum flexibility at imaging time. You can use it to create very complex displays that include real-time motion, offscreen rendering and compositing, and more. But at first glance, it can appear complicated and bewildering. Don't despair: the good news, as you'll learn in this article, is that you can use it for simple tasks without much trouble.

I touched on some of the basics of the OpenDoc layout model and drawing code in my article "Building an OpenDoc Part Handler" in develop Issue 19 (which you need not have read before reading this article). Here I reiterate a little of that and add to it as I explain the basic terminology and concepts of OpenDoc graphics. Then I present a series of simple recipes (also provided on this issue's CD) that illustrate the use of OpenDoc graphics objects. You'll learn how to draw a part, scroll the part, zoom or rotate the part's content, make an embedded part visible, alter the coordinate system scaling, and do simple printing under QuickDraw.


OpenDoc objects work together to lay out and draw each piece of content (each part) in a compound document. We'll take a look at the layout model here before focusing on each of its constituent objects and how the objects relate to one another.


OpenDoc's layout model includes both a persistent representation and a runtime representation of a document's state. Persistent information is represented in objects called frames, while runtime information is captured in objects called facets. The two sets of objects, working together, produce the structure of the displayed or printed document.

Frames are arranged in a lattice (speaking in mathematical, not geometric, terms). Any frame can contain any other, but in practice they almost always fall into a strict hierarchy, with each frame contained in only one other frame. Frames always contain a pointer to their containing frame but not directly to their embedded frames. Some applications -- like Personal Information Managers, which handle lots of unstructured information -- have more sophisticated data models, however, so OpenDoc is built to accommodate these applications.

Facets are always arranged in a strict hierarchy, and every facet has pointers to every contained facet as well as to the containing facet. OpenDoc walks this structure at run time to perform drawing as well as to handle geometric events such as mouse clicks.

The runtime representation is hooked into the window system by means of a window object. This window object simply points to the topmost facet in that window's facet hierarchy.

To understand these objects in greater detail, you need to be familiar with three basic ideas that form the foundation of OpenDoc's layout and imaging capabilities: canvas, shape, and transform.

  • A canvas is simply a drawing context. Different platforms have different ideas of what a canvas might be, based on the particular graphics toolbox they provide. On the Macintosh, a canvas can be either a QuickDraw graphics port or a QuickDraw GX view port.

  • A shape is a way to describe an area of a canvas. OpenDoc provides a platform-independent shape definition based on polygons. In addition, for speed, QuickDraw regions and rectangles and QuickDraw GX shapes can serve as shape objects in OpenDoc.

  • A transform is a way of altering the coordinate system that applies to a particular canvas. You're familiar with the concept of transforms if you provide scrolling in your applications. When a window is scrolled, a new origin is set in the graphics port before drawing calls are performed. This offset is an example of a transform. In QuickDraw, the only transforms with built-in support are offsets and (partly) scaling, both of which require a certain amount of work on the programmer's part; QuickDraw GX offers offsets and scaling as well as more interesting transforms such as rotating and skewing. OpenDoc supports full two-dimensional transformations and provides hooks to supply your own transform types.
With these definitions in mind, let's take a closer look at frames, facets, and windows.


A containing part and its embedded part share a single frame object, which they use to communicate persistent layout information. Much of this information is communicated in the form of shapes, which are ways to describe a geometric area. Specifically, layout information is communicated by way of the frame shape, the used shape, and the internal transform associated with a frame.

The frame shape is how the container tells the embedded part how much area it has in which to lay itself out. The container "owns" this shape, meaning that it's allowed to set the value. If the embedded part wants a different frame shape, it must ask the container to change it, and the container might refuse.

The rule in this sort of negotiation is "Don't ask twice!" This means that if an embedded part asks for a new frame shape and is denied, it shouldn't ask again. It might want to request a different shape later, but it should never again request exactly the same shape. The reason, as you might imagine, is to avoid infinite loops in negotiation. Very long, dull, and useless negotiations between parts may well result if the "Don't ask twice!" rule isn't followed.

The used shape serves to inform the container exactly what part of the frame shape the embedded part decided to use, and is "owned" by the embedded part. For example, imagine that a word processing container passes a rectangular area as the frame shape, but an embedded pie chart uses only a circular area within the frame shape. The pie chart can inform the word processor of this by setting the used shape of the frame to the circular area actually used. It's then the responsibility of the container to fill in any unused areas of the frame with an appropriate background or drawing. This is what makes part transparency work.

The internal transform, also "owned" by an embedded part, captures information about how the embedded part wishes to transform its content when it's displayed. If, for example, the pie chart of the previous example were too big to fit in the allotted space in the word processor and wanted to scroll itself to a particular location, it could do so by setting the internal transform of the frame. We'll look at some examples in the recipes section to come.


A facet is similar to a QuickDraw GX view port, or to a QuickDraw graphics port on steroids; it's a description of the place where a particular frame of a part becomes visible. Typically passed in to your part handler by an object at drawing time, a facet has information about where the part should be drawing the content of the frame right now. It specifies the canvas where all drawing calls should be made and also includes clipping and transformation information.

The clipping information appears in the form of the clip shape. This shape specifies exactly where on a canvas a part handler can draw. It's equivalent to the content region of a window in a traditional Macintosh application. Actually, there are two versions of this shape that you can retrieve: the aggregate clip shape, which is the clipping information relative to your drawing canvas, and the clip shape, which is relative to the coordinate system of your container. Your container owns the clip shape and sets it in its own coordinate system. You should always clip any drawing calls you make to the aggregate clip shape of the facet you're drawing into.

The transformation information comes in the form of a set of transform objects that are available from the facet, each one specifying a particular coordinate system related to the frame being displayed. The external transform of a facet specifies where the facet sits in relation to its container. For example, as illustrated in Figure 1, if the embedded facet should be offset by (100,100) from the origin of its container, the external transform would specify an offset of (100,100). Note that in this figure, only a portion of the content is being displayed in the embedded facet, and the coordinates (0,0) refer to the content and indicate that the content's upper left corner presently coincides with the upper left corner of the facet.

The internal transform of a frame is composed with the external transform of its facet plus all the transforms above it in the facet hierarchy to give the complete transformation used to draw into the facet, called the content transform. In Figure 2, which illustrates this process of composition, both transforms are simply offsets. The external transform specifies an offset of (100,100), so the embedded facet is offset by (100,100) from the origin of its container, the same as in Figure 1. The internal transform specifies an offset of (0,-75), so the content is scrolled upward from its position in Figure 1. A different portion of it now shows in the embedded facet, which remains the same size as before.

Figure 1. An embedded facet with an external transform of (100,100)

Figure 2. Composing internal and external transforms to obtain a content transfrom

This composition is recursive, so every level of embedding adds a new external and internal transform to the final transformation. All of the transforms must be composed together to produce a correct graphical result. When drawing occurs, the content transform should be applied to any drawing commands. The only exception to this rule is if you're drawing content that shouldn't scroll as well as content that should. In this case, use the content transform for scrolling content and use a different transform, called the frame transform, to draw the rest. The frame transform is exactly the same as the content transform except that it doesn't include the internal transform of the innermost frame.


Windows are the objects that hook OpenDoc facets and frames into the Macintosh window structure. A window object holds a Macintosh window structure, as well as a pointer to the topmost facet visible in the window. We call this facet the root facet because it's the root of the facet hierarchy in that window. The frame being displayed through that facet is called the root frame, and the part being displayed in the root frame is called the root part.


When a window is visible, it points to a facet at the root of the window. The graphics port, or root QuickDraw GX view port, of that window is used as the canvas on which that facet appears.

Every facet displays a particular frame, but a frame can be visible in more than one facet at the same time. Every frame displays a particular part, but a part can be displayed in more than one frame, as shown in Figure 3. Here we see a window displaying two parts: a drawing container that has chosen to split itself into two independently scrollable sections, and an embedded charting part. To split itself, the container has set up two facets on the same frame of its embedded charting part, as indicated in the schematic to the right of the window (in which the arrows represent pointers). This automatically causes the embedded charting part to display synchronized views of itself in the two scrollable sections. This is the model that people who already do splitting in their code are most likely to implement, although there are more elegant models included in the standard recipes that are part of the OpenDoc Software Development Kit.

Figure 3. A split window using multiple facets of the same frame

When the information in a part changes, the part needs to update every frame in which it's displayed. When a part updates the information in a frame, it should redraw into every facet of the frame. Let's assume, for example, that we have a charting part that can display a bar chart. When someone changes a data value, the part should make sure that every frame is redrawn. Since every frame may have multiple facets, the part handler should iterate through every display frame, iterate through each frame's visible facets, and draw the content into each. To accomplish this, you can decide to invalidate all of the affected frames and let OpenDoc make sure everything is redrawn correctly. However, if performance or timing constraints make this impractical, or if flicker is an issue, your part handler can draw directly into each facet or each affected frame, using a doubly nested loop.


Now let's look at a series of examples of how to use these objects to perform basic graphics operations. Each of the following recipes is, by nature, just a skeleton. Every part handler has different drawing code, so we'll concentrate on outlining general recipes and wave our hands over the specific drawing commands.

The examples are all based on Color QuickDraw, on the assumption that more readers will be familiar with these calls than with the QuickDraw GX equivalents. I'm counting on you QuickDraw GX aficionados to perform the necessary mapping between QuickDraw and QuickDraw GX as you read. The QuickDraw GX equivalent calls will work equally well to clip, set up drawing contexts, and perform geometric operations. Of course, you'll find QuickDraw GX helps tremendously in implementing scaling, rotation, and other transformations. Even though these examples are in Color QuickDraw, I urge you to use QuickDraw GX as your basic imaging model if you can.

The example code you'll see here is a simplified version of code written by Steve Smith and Eric House. The good ideas are theirs; the mistakes are probably mine. This is not intended to be working code, since error handling and some other pieces have been left out for the sake of simplicity.


Our first recipe tells how to draw a part. There are only a few simple steps here, for the most basic case. Take a look at Listing 1 as we discuss the recipe. To keep things as simple as possible, we'll ignore scrolling and printing for the moment. The basic steps are as follows:
  • Get the canvas of the facet you're drawing into and set the graphics port to that.

  • Get the content transform out of the facet and use it to set offset information.

  • Get the aggregate clip shape out of the facet and use it to set the clipping region.

  • Draw your content.

  • Clean up.
Listing 1. MyPart::Draw, simplest case
void MyPart::Draw(Environment* ev, ODFacet* facet,
         ODShape* invalShape)
   // Set up graphics port.
   GrafPtr port = facet->GetCanvas(ev)->GetQDPort(ev);

   // Set up graphics port offset for drawing content.
   ODTransform* localToGlobal =
       facet->GetContentTransform(ev, kODNULL);
   ODPoint offset(0,0);
   offset = localToGlobal->TransformPoint(ev, &offset);
   SetOrigin(-offset.IntX(), -offset.IntY());

   // Set up graphics port clip; save old clip.
   RgnHandle saveClip = NewRgn();
   ODShape* clipShape = facet->GetAggregateClipShape(ev, kODNULL);
   RgnHandle clip = clipShape->GetQDRegion(ev);

   // And draw (insert your drawing code here).
   // Remember to respect the scaling and rotation information
   // in your content transform, if possible. If you can't do this,
   // it's graceful to at least try to draw as best you can, rather
   // than simply signaling an error.

   // Clean up.
As you may have noticed, this is only slightly more complex than using the existing window system. Luckily, all of the added complexity comes only in the setup code, not in the actual drawing calls. Once the drawing environment has been set up, you're free to make the same drawing calls you always have.

Incidentally, there's an easy way to get all of the correct setup code done for you: a public utility called FocusLib, available as part of the OpenDoc Software Development Kit, reduces the setup code you see in this and the following examples to a single call. I didn't use it here because I wanted you to see exactly what needs to be done, just in case FocusLib doesn't meet your precise requirements and you must do it yourself. For instance, FocusLib is in C++, so not everyone can use it.


Creating a scrolling part is only a bit more complex than making one that doesn't scroll. The best way to scroll in OpenDoc is to modify the internal transform of your part's display frame. This has the effect of automatically scrolling any embedded parts that are visible right now, without any extra work on your part. Check out Listing 2, which shows the changes in the draw method for this slightly more complex case. The basic steps are as follows:
  • Get the canvas of the facet you're drawing into and set the graphics port to that.

  • Get the frame transform out of the facet and use it to set offset information.

  • Get the aggregate clip shape out of the facet and use it to set the clipping region.

  • Draw your scroll bar control.

  • Get the content transform out of the facet and use it to set offset information.

  • Make sure the scroll bar area is removed from the clipping region.

  • Draw your content.

  • Clean up.

Listing 2. MyPart::Draw, with scrolling

void MyPart::Draw(Environment* ev, ODFacet* facet,
         ODShape* invalShape)
   Point      spclOffset = {0,0};
   Point      contentOffset = {0,0};
   // Set up graphics port.
   GrafPtr port = facet->GetCanvas(ev)->GetQDPort(ev);

   // Set up graphics port offsets for controls.
   ODTransform* localToGlobal =
       facet->GetFrameTransform(ev, kODNULL);
   ODPoint tempOffset1(0,0);
   tempOffset1 = localToGlobal->TransformPoint(ev, &tempOffset1);
   SetOrigin(-tempOffset1.IntX(), -tempOffset1.IntY());

   // Set up special offset for later efficient reset of clipping
   // region.
   spclOffset = localToGlobal->GetQDOffset(ev);
   ODTransform* contentTransform = facet->GetContentTransform(ev, 
   contentOffset = contentTransform->GetQDOffset(ev);
   spclOffset.v -= contentOffset.v; spclOffset.h -= contentOffset.h;

   // Set up graphics port clipping.
   RgnHandle saveClip = NewRgn();
   ODShape* clipShape = facet->GetAggregateClipShape(ev, kODNULL);
   RgnHandle clip = clipShape->GetQDRegion(ev);

   // Draw your controls (such as scroll bars) here, using the
   // standard Toolbox calls. Remember to respect the scaling
   // and rotation information in your transform, or at least
   // try to draw as best you can, rather than simply signaling
   // an error.
   // Set up graphics port for drawing content.
   ODPoint tempOffset2(0,0);
   tempOffset2 = contentTransform->TransformPoint(ev, &tempOffset2);
   SetOrigin(-tempOffset2.IntX(), -tempOffset2.IntY());
   // Use the special offset we set up earlier to keep the clip in
   // the right place relative to the origin. Remember to remove the
   // scroll bar area from the clipping region.
   OffsetRgn(clip, spclOffset.h, spclOffset.v);

   // And draw (insert your drawing code here).
   // Remember to respect the scaling and rotation information
   // in your content transform if possible, as mentioned above.


   // Clean up.
   SetOrigin(0, 0);
Listing 3 shows how you would handle the actual scrolling. The recipe here is also quite simple. By altering the internal transform of the frame being displayed, you change not only the display of the content but also the position of all embedded facets. For this recipe to work, the previous recipe must have been implemented. The steps are as follows:
  • Track the scroll bar control.

  • Decide the scrolling distance.

  • Create a transform that offsets by the correct amount.

  • Call ScrollRect; invalidate the correct areas of the screen.

  • Change the internal transform of the frame being scrolled.
You can no doubt imagine much more complex scrolling behavior, with significantly better optimization than you see in these examples.

Listing 3. Handling the scrolling

ODBoolean MyPart::HandleMouseDownScrollBar(Environment* ev,
      Point mouse, ODFrame* frame)
   ODSShort partcode = TrackControl(fScrollBar, mouse, kODNULL);
   Point transPt;
   ODSShort setting = GetControlValue(fScrollBar);

   if (partcode) {
      // Deal with the scroll bar and choose the scroll distance.
      switch (partcode) {
         case inUpButton:
         case inDownButton:
         case inPageUp:
            if ((setting - kPBPageSize) < 0) setting = 0;
            else setting -= kPBPageSize;
         case inPageDown:
            ODSShort max = GetControlMaximum(fScrollBar);
            if ((setting + kPBPageSize) > max) setting = max;
            else setting += kPBPageSize;
      SetControlValue(fScrollBar, setting);
      SetPt(&transPt, 0, (0-setting));   // This is a vertical
                                 // scroll bar.
      // Set up the transform.
      ODTransform* newIntTrans = frame->CreateTransform(ev);
      newIntTrans->SetQDOffset(ev, &transPt);
      frame->ChangeInternalTransform(ev, newIntTrans, kODNULL);

      // Here's some simplified code for invalidating any embedded 
      // facets that have been moved. This is a "saturation bombing"
      // approach rather than the tuned code of a real application,
      // but it gets the basic idea across. Typically, we do a
      // ScrollRect followed by invalidation of the revealed area.
      // Here we simply invalidate everything.
      frame->Invalidate(ev, kODNULL, kODNULL);
      return kODTrue;
   return kODFalse;

There's a bit of human interface to mention at this juncture. You shouldn't grab the selection focus simply because scrolling is occurring. At first blush, it might make sense to imagine that a part should become active when scrolling. There's no particular reason to do this, though. Scroll bars should become active when the window is frontmost, but a part should become active (that is, grab the selection focus) only when a selection is made within it.


The process of zooming or rotating your content is closely related to the scrolling recipe we just examined. Again, the internal transform can be used to apply to not only your own content but that of embedded parts as well. Listing 4 is a simple example of a 4x scaling operation that zooms in by a factor of 4. As before, it assumes correct behavior from the drawing code, as illustrated in Listing 1.

The recipe for both zooming and rotating is fairly simple:

  • Set up a transform that captures the desired transformation.

  • Change the internal transform of the frame.

  • Invalidate the frame to make sure it gets redrawn.
Listing 4. A 4x scaling operation
void MyPart::ZoomContents4X(Environment* ev, ODFrame* frame)
   ODPoint      frameScale(4, 4);

   // Apply the zoom transformation.
   ODTransform* intTrans = frame->GetInternalTransform(ev, kODNULL);
   intTrans->ScaleBy(ev, &frameScale);

   // Invalidate the frame for redrawing.
   frame->Invalidate(ev, kODNULL, kODNULL);


When you're writing a handler for parts that can contain other parts, there comes a time when you have a pointer to a part that hasn't yet been made visible. We won't go into exactly how such a part is obtained from the Clipboard or the drag and drop object. Suffice it to say that if you do things correctly, you'll end up with a pointer to a storage unit that has part data inside it.

To embed this part, you must create a frame and a facet for it. Once you've done that, you probably want to remember the frame and the facet for further reference. Take a look at Listing 5 for an example. The recipe for making a part visible and embedding it inside your part is as follows:

  • Get the part, using the draft, from the storage unit pointer.

  • Create a frame to display the part.

  • Create a facet to make the frame visible.

  • Invalidate the facet.

  • Clean up.
Listing 5. Making an embedded part visible
void MyPart::EmbedPartFromSU(Environment* ev, ODStorageUnit* newSU,
      ODFacet* myFacet)
   ODPart* newPart = newSU->GetDraft(ev)->GetPart(ev, newPartID);
   ODRect rect(0, 0, kPBDefaultFrameSize, kPBDefaultFrameSize);
   ODShape* newFrameShape = myFacet->CreateShape(ev);
   newFrameShape->SetRectangle(ev, &rect);
   ODFrame* newFrame = newSU->GetDraft(ev)->CreateFrame(ev,
         kODNULL,                   // Use the default frame type.
         myFacet->GetFrame(ev),  // Containing frame is my frame.
         newFrameShape,             // Use the frame shape we set up.
         (ODCanvas*)kODNULL,        // No special canvas.
         newPart,                   // The part in the frame.
         fSession->Tokenize(ev, kODViewAsFrame),
                                    // View as a frame.
         kODNullTypeToken,          // Undefined presentation.
         kODFalse,                  // Not a root frame.
   kODFalse);   // Not overlaid.
   // Set up a clip shape, same as frame shape.
   ODShape* frameShape = newFrame->GetFrameShape(ev, kODNULL);
   ODShape* newClipShape = frameShape->Copy(ev);
   Point offset = {100,100};
   ODTransform* newExternalXForm = myFacet->CreateTransform(ev);
   newExternalXForm->SetQDOffset(ev, &offset);
   ODFacet* newFacet = myFacet->CreateEmbeddedFacet(ev,
         newFrame,           // Of this frame.
         newClipShape,       // With this clip shape.
         newExternalXForm,   // At this location/scale/rotation.
         kODNULL,            // No special canvas.
         kODNULL,            // No special bias canvas.
         kODNULL,            // No sibling specified.
         kODFrameInFront);   // Put this facet at front.

   // At this point, we probably want to remember the new frame
   // and facet in some data structure.
   this->rememberFrame(newFrame, newFacet);

   // Invalidate facet so that it displays. We need to invalidate our
   // entire frame because the new facet may interact with other
   // content in various ways. This is the simplest correct method,
   // although optimizations may be reasonable in production code.
   myFacet->GetFrame(ev)->Invalidate(ev, kODNULL, kODNULL);

   // Clean up.


A common misconception about OpenDoc is that its base coordinate system is insufficient to handle truly large documents. The coordinate system is in fixed-point 16.16 numbers, where the number 72.0 represents 1 inch. If we take this literally, it means that coordinates in this space can only represent an area of about 455 inches on a side and that we can place elements in that area to a precision of about 1/2,000,000 of an inch.

Clearly, we could trade off a little bit of that precision for a larger working area. This would involve scaling any incoming points or shapes. Actually, by doing this, we can easily lay out an area about 2,000 typical pages on a side at a precision of about 1/4,000 of an inch, including some bits for round-off error in the scaling multiplications. You can ask why we chose 72.0 as the basic scale of our coordinate system, but we won't tell you.

The key here is to work internally in coordinates that suit you, without disturbing the coordinate scaling of your embedded parts. The best way to do this is to apply an

internal scaling transform for your own graphics and then apply external scaling transforms to all of your embedded parts.

For example, to get a larger area that still has adequate placement, you might decide to work in a coordinate system where 1.0 = 1 inch. This would still let you place elements with an accuracy of about 1/32,767 of an inch but would let you work in a layout space that was 32,767 inches on a side. This is about 3,000 pages high, a pretty good size. You'll probably get some rounding error during multiplication, though, so it's best not to count on exact placement within more than about 1/1,000 of an inch at this scaling. Listing 6 is an example of how to do this particular transformative trick.

Listing 6. Altering the coordinate system scaling

   ODPoint      frameScale(72,72);

   // Set up the transform.
   ODTransform* existingTransform = frame->GetInternalTransform(ev,
   ODTransform* newIntTrans = existingTransform->Copy(ev);
   newIntTrans->ScaleDownBy(ev, &frameScale);
   // Apply the zoom transformation within myself.
   frame->ChangeInternalTransform(ev, newIntTrans, kODNULL);

   // Now, be a good citizen and iterate over every facet of myself.
   ODFrameFacetIterator* facets = frame->CreateFacetIterator(ev);
   for (ODFacet* facet = facets->First(ev);
         facets->IsNotComplete(ev); facet = facets->Next(ev)) {
      // For each facet of myself, find every embedded facet.
      ODFacetIterator* embeddedFacets = facet->CreateFacetIterator
         (ev, kODTopDown, kODFrontToBack);
      for (ODFacet* embeddedFacet = embeddedFacets->First(ev);
            embeddedFacet = embeddedFacets->Next(ev)) {
         // Alter the transform of each embedded facet.
         existingTransform = embeddedFacet->GetExternalTransform(ev,
         ODTransform* newExtTrans = existingTransform->Copy(ev);
         // Notice that we scale in the opposite direction in 
         // each embedded frame.
         newExtTrans->ScaleBy(ev, &frameScale);
         embeddedFacet->ChangeGeometry(ev, kODNULL, newExtTrans,
   ODDeleteObject(facets); }


The last and most complicated recipe is getting a part to print under QuickDraw. As you know, any printing activity on the Macintosh is fairly complex. OpenDoc doesn't add much complexity to the process, as you'll see from the example.

First, every part needs to understand how to draw correctly to a PostScript(TM) printer. There's a trick to this because of how the LaserWriter drivers operate. They don't clip to regions if asked to do so; instead, they merely clip to the bounding rectangle of the suggested region. So to set a clipping region when printing to a PostScript device, you'll need to create a clipping polygon in PostScript. This is true even for parts that are always rectangular, because they might be clipped irregularly.

You can detect the presence of a PostScript device by examining the printing job at draw time. The printing job is always available in the canvas when you're being asked to draw to a PostScript device. There are a number of ways to check this, but no standard method that Apple supports; typically, you check the device number and make a choice based on a table kept in your code. If you are in fact drawing to a PostScript device, call the routines shown in Listing 7, rather than SetClip, to set clipping for your part. You don't have to do this when you're printing to a non-PostScript printer, because simple region clipping works just fine there.

Listing 7. Setting clipping when printing to a PostScript device

#define kPostScriptBegin    190   // Picture comments for PostScript
#define kPostScriptEnd      191   // printing.
#define kPostScriptHandle   192

void ODBeginPostScriptClip(Environment* ev, ODShape *shape)
   ODPolygon poly = shape->CopyPolygon(ev);
   Handle clipHandle = NewEmptyHandle();
   AppendString("\pgrestore", clipHandle);
                                         // Utility routine to append
   AppendString("\pnewpath", clipHandle);      // string to a handle.

   char buf[128];
   ODContour *cont = poly.FirstContour();

   for (long n=poly.GetNContours(); n>0; n--) {
      const ODPoint *v = cont->vertex;
      long m = cont->nVertices;
      if (m > 2) {
         sprintf(buf, "%.2f %.2f moveto", v->x/65536.0,
         AppendBuf(buf, strlen(buf), clipHandle);
              // Utility routine to append string buffer to a handle.
         while (--m > 0) {
            sprintf( buf, "%.2f %.2f lineto", v->x/65536.0,
            AppendBuf(buf, strlen(buf), clipHandle);
      AppendString("\pclosepath clip", clipHandle);
      cont = cont->NextContour();
   // Set pic comment; then delete clipHandle.
   AppendString("\pgsave", clipHandle);
   PicComment(kPostScriptBegin, 0, kODNULL);
   PicComment(kPostScriptHandle, GetHandleSize(clipHandle),
   PicComment(kPostScriptEnd, 0, kODNULL);

void ODEndPostScriptClip( )
   Handle clipHandle = NewEmptyHandle();
   AppendString("\pgrestore", clipHandle);
   PicComment(kPostScriptBegin, 0, kODNULL);
   PicComment(kPostScriptHandle, GetHandleSize(clipHandle),
   PicComment(kPostScriptEnd, 0, kODNULL);
You may well want to consider using ColorSync during printing. There's nothing special to worry about in OpenDoc; just go ahead and take advantage of it as desired. Other parts may be using ColorSync independently when they draw as well, and all of these may use independent color-matching methods.

Every part should understand how to perform printing of the window if it's the root part of that window. You'll invoke this recipe when the Print command is chosen from the Document menu. The recipe presented here works for rather simple parts but probably not for complex parts like full word processors or page layout programs that have hundreds of pages to lay out and print. In addition, to simplify the look of the code, a special helper object handles most of the direct calls to the printer driver. Finally, this part doesn't alter its layout for printing, as some parts might want to do.

Given these caveats, though, the basic recipe is as follows:

  • Create a printing job.

  • Use the graphics port from the printing job to create a canvas.

  • Add a facet to your root frame on the canvas.

  • Loop through copies and pages.
    a. Reset the offset and clipping of the facet so that the correct page is showing on the canvas.
    b. Invalidate the facet to cause it to draw.
  • Clean up.
Listings 8 through 10 contain some code to help you implement this recipe. Rather than attempt to show you an entire printing loop here, I'll show three routines that correspond to the key differences in the OpenDoc model of printing.

Listing 8 shows how to perform steps 2 and 3 of the recipe above. This routine expects to be passed a printing port, the page rectangle for the first page of the print job, and the root frame of the window being printed. The routine takes this information and creates a facet on the root frame. It then builds a canvas on the print job's printing port and sets the facet to draw on that canvas. We do this so that we can use OpenDoc's drawing code to image the page. Once we have a facet set up, we need only force the facet to update to get all of the parts to image on the page.

Listing 8. Setup for basic printing

ODFacet* MyPart::BeginPrinting(Environment *ev, ODFrame* rootFrame,
      TPrPort* thePrPort, ODRect *pageRect)
   // Set up identity transform, get page rect, set up to clip to it.
   ODTransform* xtransform = rootFrame->CreateTransform(ev);
   ODShape* clipshape = rootFrame->CreateShape(ev);
   clipshape->SetRectangle(ev, pageRect);

   // Create a facet with the specific geometry we just set up.
   ODFacet* prFacet = fSession->GetWindowState(ev)->
         CreateFacet(ev, rootFrame, clipshape, xtransform, kODNULL,

   // Set up a canvas based on the print job's port.
   ODCanvas* prCanvas = prFacet->CreateCanvas(ev, kODQuickDraw,
         (GrafPtr)thePrPort, kODFalse, kODFalse);
   prCanvas->SetPlatformPrintJob(ev, kODQuickDraw,
   // Make it the canvas of the facet we created.
   prFacet->SetCanvas(ev, prCanvas);
   rootFrame->FacetAdded(ev, prFacet);
   // Return the facet to the main print routine.
   return prFacet;
Note that this particular setup routine doesn't handle a very important case: QuickDraw GX-based part handlers. To set these up correctly, we would replace steps 1 and 2 of the recipe above with the following:
  • oCheck for the existence of QuickDraw GX printing using Gestalt.

      oIf QuickDraw GX printing isn't present, set up a normal Color QuickDraw print job.

      If QuickDraw GX printing is present, set up a QuickDraw GX print job. Also, set up a Color QuickDraw graphics port, for use with the QuickDraw-to-QuickDraw GX translator.

  • Set up a canvas representing the printing job, ready for use by both QuickDraw and QuickDraw GX.

      Install the QuickDraw-to-QuickDraw GX translator in your Color QuickDraw graphics port.

      Install the Color QuickDraw graphics port as the QuickDraw platform canvas in the canvas object.

      Install a view port that embedded part handlers can use as the QuickDraw GX platform canvas in the canvas object.

By setting up translators, a QuickDraw GX-based part handler can still work with embedded QuickDraw-based parts. This is a fairly complex (though straightforward) bit of code, one that we'll avoid for the purposes of this article. There's a complete recipe in the OpenDoc Software Development Kit for handling this case.

The next step is to loop through the pages, drawing each one. We'll assume that you can handle the details of creating a standard print loop yourself. Listing 9 shows the correct code to call in the middle of the page loop. This corresponds to steps 4a and 4b of our printing recipe. This routine gets the basic page geometry, resets the offsets and clipping for the page, and then forces the parts visible on the page to draw by calling an update on the root facet we've created elsewhere.

Listing 9. Printing a page

void MyPart::PrintPage(Environment *ev, ODFacet* prFacet,
   ODUShort page, ODRect *pageRect)
   // Get some basic printing geometry.
   ODRect   bbox;
   Rect      frect, qdPRect;
   ODShape* frameShape = prFacet->GetFrame(ev)->
         GetFrameShape(ev, kODNULL);
   frameShape->GetBoundingBox(ev, &bbox);
   Point pt = {0,0};
   ODUShort locator = page-1;
   // Pick an appropriate offset, based on page number.
   while (locator) {
      pt.v += (qdPRect.bottom+1);
      if (PtInRect(pt, &frect))
      else {
         pt.v = 0; pt.h += (qdPRect.right+1);
   // Make a transform for that offset.
   ODTransform* xtransform = prFacet->CreateTransform(ev);
   xtransform->SetQDOffset(ev, &pt);

   // Create a clip shape for the page, based on the transform.
   ODShape* clipshape = prFacet->CreateShape(ev);
   clipshape->SetRectangle(ev, pageRect);
   ODShape* invalshape = clipshape->Copy(ev);
   clipshape->Transform(ev, xtransform);

   // Change the geometry of the printing facet.
   prFacet->ChangeGeometry(ev, clipshape, xtransform, kODNULL);
   // Draw everything on the page. OpenDoc will call the Draw method
   // on every part visible on the page.
   prFacet->Update(ev, invalshape, kODNULL);

   // Clean up.
Once the print loop is complete, we'll want to clean up. Listing 10 shows the routine that corresponds to step 5 of our printing recipe. It simply tosses away the facet and the canvas we created in Listing 8.

Listing 10. Cleanup after printing

void MyPart::EndPrinting(Environment *ev, ODFacet* prFacet)
   // Find the printing canvas and facet; delete them.
   ODCanvas* prCanvas = prFacet->GetCanvas(ev);
   prFacet->GetFrame(ev)->FacetRemoved(ev, prFacet);
   delete prCanvas;
   delete prFacet;
If you're performing more advanced printing, you may want to allow embedded parts to lay themselves out differently based on whether they're printing to a static or a dynamic canvas. In this case, you'll need to create new frames and perform layout negotiation. You should create nonpersistent frames, or they'll needlessly be written out to the document the next time the user saves. You'll probably want to do this:

  • Create a new nonpersistent frame for your part (the "master frame").

  • Create new nonpersistent frames for each embedded part and allow shape negotiation to occur on these new embedded frames.

  • Use the previous recipe to print the master frame.


    For simple cases, as you can see, the OpenDoc layout and graphics model isn't much more complex than what you probably already do. Even better, most of your code will work fine in the new model with just some additional setup and cleanup code. This is no accident, as OpenDoc has been designed from the start to allow you to reuse large parts of your code. So go ahead and show us some cool new parts with great graphics.

    KURT PIERSOL is a system architect at Apple and has been involved with the Apple events project, AppleScript, and OpenDoc. You can recognize him by his eccentric fashion sense and his tendency to use funny accents during heated engineering discussions.

    Early releases of OpenDoc will be made available through a number of different sources, including develop.

    Thanks to our technical reviewers Jens Alfke, Steve Smith, and Joshua Susser.


    Community Search:
    MacTech Search:

    Software Updates via MacUpdate

    Carbon Copy Cloner 4.1.18 - Easy-to-use...
    Carbon Copy Cloner backups are better than ordinary backups. Suppose the unthinkable happens while you're under deadline to finish a project: your Mac is unresponsive and all you hear is an ominous,... Read more
    Hopper Disassembler 4.2.14- - Binary dis...
    Hopper Disassembler is a binary disassembler, decompiler, and debugger for 32- and 64-bit executables. It will let you disassemble any binary you want, and provide you all the information about its... Read more
    BetterTouchTool 2.291 - Customize Multi-...
    BetterTouchTool adds many new, fully customizable gestures to the Magic Mouse, Multi-Touch MacBook trackpad, and Magic Trackpad. These gestures are customizable: Magic Mouse: Pinch in / out (zoom... Read more
    Sound Studio 4.8.11 - Robust audio recor...
    Sound Studio lets you easily record and professionally edit audio on your Mac. Easily rip vinyls and digitize cassette tapes, or record lectures and voice memos. Prepare for live shows with live... Read more
    Sound Studio 4.8.11 - Robust audio recor...
    Sound Studio lets you easily record and professionally edit audio on your Mac. Easily rip vinyls and digitize cassette tapes, or record lectures and voice memos. Prepare for live shows with live... Read more
    BetterTouchTool 2.291 - Customize Multi-...
    BetterTouchTool adds many new, fully customizable gestures to the Magic Mouse, Multi-Touch MacBook trackpad, and Magic Trackpad. These gestures are customizable: Magic Mouse: Pinch in / out (zoom... Read more
    Carbon Copy Cloner 4.1.18 - Easy-to-use...
    Carbon Copy Cloner backups are better than ordinary backups. Suppose the unthinkable happens while you're under deadline to finish a project: your Mac is unresponsive and all you hear is an ominous,... Read more
    Hopper Disassembler 4.2.14- - Binary dis...
    Hopper Disassembler is a binary disassembler, decompiler, and debugger for 32- and 64-bit executables. It will let you disassemble any binary you want, and provide you all the information about its... Read more
    VOX 2.8.30 - Music player that supports...
    VOX just sounds better! The beauty is in its simplicity, yet behind the minimal exterior lies a powerful music player with a ton of features and support for all audio formats you should ever need.... Read more
    Default Folder X 5.1.6b3 - Enhances Open...
    Default Folder X attaches a toolbar to the right side of the Open and Save dialogs in any OS X-native application. The toolbar gives you fast access to various folders and commands. You just click on... Read more

    The best 2v2 card combos in Clash Royale
    2v2 is making it's grand return toClash Royalequite soon. 2v2 has quickly become one of the game's most popular gameplay modes, though they still have yet to make it a permanent fixture in the game. 2v2 is exciting and adds some new flavor to... | Read more »
    The best games we played this week - Aug...
    Another busy week has come to a close. We played a lot of excellent games this week and now it's time to look back and reflect on some our favorites. Here are our picks for the week of August 18. [Read more] | Read more »
    War Wings beginner's guide - how to...
    War Wings is the newest project from well-established game maker Miniclip. It's a World War II aerial dogfighting game with loads of different airplane models to unlock and battle. The game offers plenty of single player and multiplayer action. We... | Read more »
    How to win every 2v2 battle in Clash Roy...
    2v2 is coming back to Clash Royale in a big way. Although it's only been available for temporary periods of time, 2v2 has seen a hugely positive fan response, with players clamoring for more team-based gameplay. Soon we'll get yet another taste of... | Read more »
    Roll to Win with Game of Dice’s new upda...
    Joycity’s hit Game of Dice gets a big new update this week, introducing new maps, mechanics, and even costumes. The update sets players loose on an exciting new map, The Cursed Tower, that allows folks to use special Runes mid-match. If you feel... | Read more »
    Bottom of the 9th (Games)
    Bottom of the 9th 1.0.1 Device: iOS iPhone Category: Games Price: $4.99, Version: 1.0.1 (iTunes) Description: Play the most exciting moment of baseball in this fast-paced dice and card game! | Read more »
    The best apps for viewing the solar ecli...
    If you somehow missed the news, many parts of the United States will be witness to a total solar eclipse on August 21 for the first time in over 90 years. It'll be possible to see the eclipse in at least some capacity throughout the continental U... | Read more »
    The 5 best mobile survival games
    Games like ARK: Survival Evolved and Conan Exiles have taken the world of gaming by storm. The market is now flooded with hardcore survival games that send players off into the game's world with nothing but maybe the clothes on their back. Never... | Read more »
    Portal Walk (Games)
    Portal Walk 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: Portal Walk is adventure and relaxing platform game about Eugene. Eugene stuck between worlds and trying to find way back home.... | Read more »
    Technobabylon (Games)
    Technobabylon 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: City of Newton, 2087. Genetic engineering is the norm, the addictive Trance has replaced almost any need for human interaction,... | Read more »

    Price Scanner via

    Weekend sale: 13-inch MacBook Pros for up to...
    Amazon has new 2017 13″ MacBook Pros on sale today for up to $200 off MSRP, each including free shipping: – 13″ 3.1GHz/256GB Space Gray MacBook Pro (MPXV2LL/A): $1599.99 $200 off MSRP – 13″ 3.1GHz/... Read more
    Back To School With The Edge Desk All-in-one...
    Back to school is just around the corner, and the ergonomically correct Edge Desk all-in-one portable kneeling desk is ideal for students living in dorms and small apartments, Edge Desk features:... Read more
    Norton Core Secure Wi-Fi Router Now Available...
    First introduced at the 2017 Consumer Electronics Show (CES), Norton Core, a secure, high-performance Wi-Fi router, fundamentally changed the concept of Wi-Fi routers by making security the primary... Read more
    ViewSonic Adds New 27-inch 4K UHD Monitor to...
    ViewSonic Corp. has introduced the VP2785-4K, a 27-inch 4K UHD (3840×2160) monitor that delivers precise and consistent color representation and performance to ensure incredible image quality. Built... Read more
    Apple now offering Certified Refurbished 2017...
    Apple is now offering Certified Refurbished 2017 27″ iMacs for up to $350 off original MSRP. Apple’s one-year warranty is standard, and shipping is free. The following models are available: – 27″ 3.... Read more
    13-inch 2.3GHz MacBook Pros on sale for $100...
    Amazon has the new 2017 13″ 2.3GHz MacBook Pros on sale today for $100 off MSRP, each including free shipping: – 13″ 2.3GHz/128GB Space Gray MacBook Pro (MPXQ2LL/A): $1199.99 $100 off MSRP – 13″ 2.... Read more
    Clearance 2016 13-inch MacBook Airs available...
    B&H Photo has clearance 2016 13″ MacBook Airs available for up to $200 off original MSRP. Shipping is free, and B&H charges NY & NJ sales tax only: – 13″ 1.6GHz/128GB MacBook Air (MMGF2LL... Read more
    Clearance 21-inch and 27-inch iMacs available...
    B&H Photo has clearance 21″ and 27″ Apple iMacs available for up to $500 off original MSRP, each including free shipping plus NY & NJ sales tax only: – 27″ 3.3GHz iMac 5K: $1799 $500 off... Read more
    New iOS 11 Productivity Features Welcome But...
    The iOS community is in late summer holding mode awaiting the September arrival of the iPhone 8 and iOS 11. iOS 11 public betas have been available for months — number six was released this week —... Read more
    Samsung Electronics Launches New Portable SSD...
    Samsung Electronics America, Inc. has announced the launch of Samsung Portable SSD T5 – its newest portable solid state drive (PSSD) that raises the bar for the performance of external memory... Read more

    Jobs Board

    Development Operations and Site Reliability E...
    Development Operations and Site Reliability Engineer, Apple Payment Gateway Job Number: 57572631 Santa Clara Valley, California, United States Posted: Jul. 27, 2017 Read more
    Frameworks Engineering Manager, *Apple* Wat...
    Frameworks Engineering Manager, Apple Watch Job Number: 41632321 Santa Clara Valley, California, United States Posted: Jun. 15, 2017 Weekly Hours: 40.00 Job Summary Read more
    Map Quality Analyst Lead, *Apple* Maps Eval...
    …a team of subject matter experts measuring the quality of a range of Apple Maps algorithms, such as Map search, recommendations, and routing. Our group works with Read more
    Business Development Manager, *Apple* Pay -...
    Job Summary Apple Pay is seeking an experienced Business Development professional to join the Apple Pay team to develop partnerships and strategic alliances with Read more
    Information Systems Engineer, *Apple* Retai...
    Job Summary Do you have a passion for the technology and systems that make Apple amazing? Are you interested in joining IS&T Retail on what they do best? This is an Read more
    All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.