Jun 96 Tips
Volume Number: 12
Issue Number: 6
Column Tag: Tips & Tidbits
Tips & Tidbits 
By Steve Sisak
Note: Source code files accompanying article are located on MacTech CD-ROM orsource code disks.
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?
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