Tips & Tidbits

By Steve Sisak

OpenDoc Frames and Facets

A major difficulty confronting every first time OpenDoc programmer is the difference between Frames and Facets. Both seem to refer to the “portion of a window” concept expressed in PowerPlant as a “pane” and in other frameworks as a “view”. In common frameworks, the pane hierarchy is both an embedding hierarchy and a visual hierarchy. In OpenDoc, the embedding hierarchy (frame) is separated from the visual hierarchy (facet) to allow for more flexibility in imaging.

In order to understand the separate roles for frame and facets, I have found it useful to create my own subtitles:

Frame - a contract for embedding

Facet - a region of a GrafPort

Think of ODFrame, first and foremost, as a relationship between two parts; a frame is a contract between a container and its embedded content. An embedded part is connected to its containing document only through its frames - if all the frames are closed, the part is no longer in the document. The embedding hierarchy alternates between parts and frames: parts have embedded frames, which have parts, which have embedded frames, and so on.

The ODFrame contract covers three primary areas: the shape of the embedded content, the view type (icon, thumbnail, or normal imaging), and the presentation format (particular to the kind of content, e.g. a chart, table, or graph). The container and embedded content mutually agree on these areas during a process called “frame negotiation”.

Either party can initiate frame negotiation. For example, a browser might want to show both an icon and a normal image for a particular embedded part. This container would create two embedding contracts, each with different shapes, view types, and presentations. On the other hand, a game controller might want to negotiate an irregular pod-shaped frame for its alien-like control panels. It would have to ask its containing part to approve this shape.

Frames, however, are an abstract contract. They are not portions of a window. In particular, frames have no GrafPort, no offset location, and no front-to-back ordering. To fulfill the abstraction, the container must make one or more facets for each frame that it wants to display. By making a facet, the container makes the frame visible and allows the user to interact with it.

Think of a facet as a region of a GrafPort. A facet has a coordinate transformation to locate itself in the GrafPort, and a clip region to make sure it does not exceed its bounds. A facet has a z-ordering, and can be highlighted or selected. Facets (and not frames) form the visual hierarchy. Importantly, facets cannot be negotiated. The container has sole control over assigning facets to its embedded frames, though it must respect the negotiated frame shape when it does so.

In most cases, the container creates only one facet per frame. Multiple facets occur in situations where a container has a split-screen view, and the same frame is imaged in multiple locations, with different clip regions. Another common use of facets is in page layout, where a frame might be split between the bottom of one page and the top of the succeeding page. To create the gap between pages, the container assigns upper and lower facets to the frame. But note that if a frame has multiple facets, they must all be in the same GrafPort. If you want to image the same content in two different windows, you must create a second frame (contract) for the second window.

If you think about it, the distinction between frames and facets makes logical sense. Consider a database container that stores thousands of embedded parts. After a search, the database displays 3 or 4 of those embedded parts. In this scenario, only the search results need facets (regions of a GrafPort) for display. But the database needs frames (the contract governing embedding) for all of the thousands of parts. It would likely want to remember the shape, view type, and presentation of each of these parts, so that when it needs to display them, it can show them just as they appeared the last time. Frames represent the persistent contract between the database and its embedded items. Facets represent the visual regions of the currently displayed parts.

For programmers with experience in other frameworks, the most important thing to remember is that a frame is not a portion of a window. It is simply a negotiated contract governing the shape, view, and presentation for an embedded content. This shape, view, and presentation becomes visible only when the container fulfills this contract by creating a facet for the part, thus specifying its GrafPort, origin, and clip shape.

Jeremy Roschelle

Yanking Ingenuity

These days, installing RAM in some of the new Power Macintosh computers is not as easy as it was with the Macintosh II series. So, here’s a tip for you Power Macintosh 8500 owners...

If you need to get access to your motherboard to install RAM, VRAM, or more Cache RAM, you’re going to have to first remove the deep-seated processor card before the motherboard can be removed from the chassis. This card is really difficult to remove because it is in there tight, and there just isn’t a lot of finger space to allow you to get a good grip on the card. After a couple roughed-up knuckles and sore finger tips, I found the following sane approach to solving this headache:

Take two small nylon cable ties (any color will do) and loosely loop them through the sturdy holes in the upper corners of the processor card. Then, you can easily insert your fingers through the two cable tie loops and apply enough equal pressure to carefully remove the processor card.

The good news is you can leave those cable ties in there in case you need future access to the motherboard (unless of course you have some other need for the holes).

Disclaimer: this tip has been thoroughly tested on several Power Macintosh 8500 computers and is bug-free. It is possible that some of the other models could also benefit from this tip.

Mark D. Gerl

[On a related note - the processor daughter card in PowerMac 9500 has a tendency to wander out of its socket if you move the machine around. This is fatal to the processor card. The repair person who fixed mine suggests opening the machine and re-seating the card if you move it to a different office, etc. - sgs ]

Immediate Drag Manager Feedback

The Drag Manager allows a feeback region to be dragged by the mouse. This region is created and passed into the TrackDrag trap:

 TrackDrag(
            DragReference         theDragRef,
            const EventRecord*    theEvent,
            RgnHandle             theRegion);

The Drag Manager doesn’t actually draw this region until the mouse has actually moved. Sometimes it is helpful if this region is drawn immediately. What to do?

Just futz with the where field of theEvent by a few pixels.

        theEvent->where.h += 3;   // the 3 comes from DnD HIG, p. 7
        theEvent->where.v += 3;
        err = TrackDrag(theDragRef, theEvent, theRegion);

...and a comment on the XOR Anti-Tip

One of the problems with the XOR swap (MacTech Magazine 11.10 [October 1995] 96) is that it doesn’t work if the source and destination are the same variables, as could happen with complicated, deeply nested macros.

Chris Sears