View figure.
Unlike windows and canvases, transforms and shapes are not platform specific. The OpenDoc objects that represent them may encapsulate platform-specific structures, but they also often give added capabilities. This section discusses how you use transforms and shapes to position and clip embedded parts for drawing.
Both frames and facets employ transforms. It is useful to discuss them in terms of the coordinate spaces they define.
In OpenDoc, an object of the class ODTransform is a 3x3 matrix that is used to modify the locations of points in a systematic manner. OpenDoc transforms support the full range of two-dimensional transformations shown in Figure 27.
Figure 27. What a Transform Does
Not all graphics systems support all the features of OpenDoc transforms. Some graphics systems support only offset, or translation, of points; others support offset plus scaling; still others support all transformations. Depending on the graphics system your part editor uses, it may have to do extra work on its own to support features such as scaling or rotation. In such a case, you can create a subclass of ODTransform, if desired, that adds those features or even other, more sophisticated transformational capabilities.
A transform can be thought of as defining a coordinate space for the items that it is applied to. OpenDoc uses transforms to convert among two kinds of coordinate space: frame coordinate space and content coordinate space.
The frame coordinate space is the coordinate system defined by the specification of the frame shape. The frame shape is the basis for the layout and drawing of embedded parts. Suppose, for example, that a frame shape is defined as a rectangle with coordinates of (0, 0) and (100, 100). In a coordinate system with the origin at the lower left as in OS/2, the shape would appear as shown in Figure 28.
Figure 28. Frame Shape on OS/2 (In its Own Frame Coordinates)
On the Windows and AIX platforms, the origin is in the upper left with the Y+-axis pointing downward as shown in Figure 29.
Figure 29. Frame Shape on Windows and AIX (In its Own Frame Coordinates)
All shapes and geometric information passed back and forth between embedded parts and their containing parts are expressed in terms of the frame coordinate space.
Note that the shapes describing the facet associated with a frame are described in the same coordinate space as the frame; that is, they are in frame coordinates. Thus, in this example, if the facet corresponded exactly to the frame (which is common), it would have coordinates of (0, 0) and (100, 100).
The content coordinate space of a part is the coordinate system that defines locations in the part's content area. It is the local coordinate space of the part itself and typically has its origin in the lower-left corner of the part's content on the OS/2 platform, and the upper-left corner on the Windows and AIX platforms.
The internal transform of a part's display frame defines the scrolled position (as well as the scaling, rotational, and skew properties) of the part's contents within the frame. Applying the display frame's internal transform to a point in content coordinate space converts it to frame coordinate space. Conversely, applying the inverse of the internal transform to a point in frame coordinate space converts it to content coordinate space.
For example, on the OS/2 platform suppose that Figure 30 shows the entire contents of a part, and that a portion of it is to be displayed in a frame. If the part's display frame has the dimensions shown previously (in Figure 28), and if the frame's internal transform specifies an offset value of (50, 50), the frame will appear in relation to its part's content as shown in Figure 30. Only the portion of the part within the area of frame shape will be displayed when the part is drawn.
Figure 30. Frame Shape on OS/2 (In Content Coordinates of its Part)
Application of the internal transform, in this case, means that a point at (50, 50) in content coordinates (the lower-left corner of the display frame for the OS/2 platform, and the upper-left for the Windows and AIX platforms) is at (0, 0) in frame coordinates. Conversely, a point at (-50, -50) in frame coordinates is at (0, 0) in content coordinates.
Figure 31. Frame Shape on Windows and AIX (In Content Coordinates of its Part)
Transformations other than offsets are applied in the same manner; you can scale, rotate, or otherwise transform the contents of the part within its frame by applying the frame's internal transform.
Just as the internal transform of a frame defines the scrolled position of the content it displays, the external transform of that frame's facet defines the position of the frame within its containing part.
Applying the external transform of a frame's facet to a point in frame coordinate space converts it to the content coordinate space of the containing part. On the OS/2 platform for example, suppose that the facet and frame of the embedded part in Figure 30 have the same shape, and suppose further that the facet's external transform specifies an offset of (150, 10). In relation to the containing part's content area, the embedded part would appear as shown in Figure 32.
Figure 32. Frame Shape (In Content Coordinates of its Containing Part)
Figure 33 shows the frame shape on the Windows and AIX platforms.
Figure 33. Frame Shape on Windows and AIX (In Content Coordinates of its Containing Part)
In this case, applying the external transform causes a point at (0, 0) in embedded-frame coordinates (the lower-left corner of the embedded part's frame on the OS/2 platform and the upper-left corner on the Windows and AIX platforms) to be at (150, 10) in containing-part content coordinates.
(Conversely, applying the inverse of the embedded facet's external transform to a point in content coordinate space converts it to the embedded frame's coordinate space. Thus, in Figure 32, a point at (-150, -10) in embedded-frame coordinates is at (0,0) in the content coordinates of the containing part).
Transformations other than offsets are applied in the same manner; the embedded part and its frame can be scaled, rotated, or otherwise transformed within the containing part by applying the facet's external transform.
To convert from the content coordinates of an embedded part to the content coordinates of its containing part therefore, you need to apply two transforms: the internal transform of the embedded part's display frame, followed by the external transform of that frame's facet. For the example shown in this section, you can see by inspection that the point (50, 50) in the content coordinates of the embedded part (the origin of its display frame) becomes the point (150, 10) in the content coordinates of the containing part. You could also calculate that the point (0, 0) in the contents of the embedded part (its lower-left corner on the OS/2 platform, and the upper-left corner on Windows and AIX) converts, by application of both transforms, to the point (100, 10) in the contents of the containing part (outside of the embedded frame and, therefore, not drawn).
You are usually unconcerned with your embedded parts' location within the content area of its containing parts. However, you are always concerned with the location of your content frame on the canvas or in the window in which the parts are drawn.
When your part draws its contents, or when it draws adornments to its frame such as scroll bars, it is your part's responsibility to properly position what it draws on its canvas. In setting up the canvas' platform-specific drawing environment, you need to provide information that tells the canvas where, in terms of its own coordinate space, your drawing will take place. OpenDoc does not do that for you automatically. It does, however, provide methods that make it fairly simple.
If you were to start from your part's content coordinate space and traverse the embedding hierarchy upward, applying, in turn, your part's internal transform and external transform, and then applying each internal transform and external transform of each containing frame and facet, up to a facet with an attached canvas, you arrive at the canvas coordinate space or the window coordinate space in which your part is drawn.
Window coordinates correspond to the root facet window. When there are embedded parts in your containing part then the embedded parts have their own facet window. You need to subtract the parent facet window offset to find out the cursor location within the containing facet.
For drawing on the OS/2 platform, call the PlatformWindowCanvas method called GetPS to acquire presentation space. On the Windows platform, call GetDC to acquire device context. On the AIX platform, use the GetGC method to acquire the graphics context. Figure 34 shows a simple example of converting to canvas coordinates and window coordinates. The containing part and the embedded part are the same ones as shown in Figure 32, and the containing part is, in this case, the root part of the window. The internal transform of the root frame (the containing part's display frame) specifies an offset of (50, 50), and the external transform of the root facet is identity.
Figure 34. Frame Shape on OS/2 (In Canvas and Window Coordinates)
Figure 35 shows the frame shape for the Windows and AIX platforms.
Figure 35. Frame Shape on Windows and AIX (In Canvas and Window Coordinates)
Converting content coordinates to window coordinates means concatenating all the transforms up through the root frame's external transform. Assuming there is no offscreen canvas in Figure 34, the point (50,50) in content coordinates (the origin of the embedded part's frame, as shown in Figure 30) becomes the point (100, 10) in window or canvas coordinates. If there were an offscreen canvas attached to the embedded facet in Figure 34, the canvas coordinates for the origin of the embedded part's frame would be (0,0).
Normally, you do all your drawing in canvas coordinate space. That way, whether or not you are drawing to an offscreen canvas (which you might not control or even be aware of), your positioning will be correct. However, when you need to draw directly to the window to provide specific user feedback, as described in "Drawing Directly to the Window", you need to work in window coordinates.
By concatenating the appropriate internal and external transforms, OpenDoc calculates four different composite transforms that you can use for positioning before drawing:
For a description of how to use these transforms when setting up for drawing, see "Draw Method of Your Part Editor".
Hit-testing is, in a sense, the inverse of drawing; it involves a conversion from window coordinates to your part's content coordinates. In most circumstances, OpenDoc takes care of this for you. See "Hit-Testing" for more information.
On each platform, OpenDoc uses the platform's native coordinate system, called platform-normal coordinates, for stored information and for internal calculations. For example, on OS/2, coordinates are measured with the origin at the lower-left (of the screen, of a shape, or of a page, and so on), with increasing values to the right and upward. The Windows and AIX platforms use coordinates with an origin at the upper-left, with values increasing to the right and downward. Figure 36 shows how these two coordinate systems would apply to measurements on a text part's page.
Figure 36. Two Coordinate Systems for Measuring Position in a Part's Content
OpenDoc functions consistently on any platform, regardless of the platform's coordinate system, without need for coordinate conversion. However, some platforms allow for simultaneous existence of different coordinate systems. In such a case, a part editor that assumes a particular coordinate system will not function correctly with OpenDoc on a platform with a different coordinate system, unless it first accounts for the coordinate bias, or difference between its coordinate system and platform-normal coordinates.
Coordinate bias usually takes the form of an offset in the origin, a change in the polarity of one or more axes, and possibly a change in scale. A transformation matrix, called a bias transform, is applied to measurements in a part's coordinate system to change them into platform-normal values.
You do not have to calculate bias transforms yourself. When you create a canvas and define its graphics system, OpenDoc uses that information to calculate a bias transform if it is required. In constructing the bias transform, OpenDoc also needs to know your part's content extent (described next).
To convert locations in your part's content between coordinate systems whose origins are offset, the vertical extent of your content (in essence, the height of your part's page) represents the offset between the two coordinate origins. See Figure 36 for an example. This content extent is the offset needed in the bias transform that performs the conversion.
Because your part may be drawn at any time on a canvas that has a bias transform attached, you should always make the value of your content extent available. When a frame is added to your part, and whenever the content extent of your part changes (such as when you add a new page), you should call your display frame's ChangeContentExtent method so that the frame always stores the proper value. A caller constructing a bias transform can obtain the current content extent of your part by calling the GetContentExtent method of your part's frame.
The classes ODFrame and ODFacet include several methods, such as ChangeInternalTransform and ContainsPoint, that specify shapes or calculate positions on a canvas. Because these calculations necessarily assume a coordinate system, the methods include a parameter, biasCanvas, that allows you to specify a canvas whose attached bias transform is to be used to convert between your part editor's coordinates and platform-normal coordinates. Thus, after you set up your offscreen canvas for drawing in your own coordinate system, you can also use it to make sure that all point, frame, and facet geometry is properly converted for you.
The sections that follow cover some of the basic ways you can use transforms to position and modify the content of your part and embedded parts.
If your part's content area is greater than its frame area, only a portion of the content can be displayed in the frame. The user needs to be able to choose which portion of a part shows through its frame by moving the part's contents as a unit in relation to the frame position.
The standard OpenDoc method for supporting this ability involves the Show Frame Outline menu command, available in the View menu when the user opens your part's frame into its own part window. In this mode, the user can drag an outline of the frame, positioning it as desired in your part's content area. Another standard method involves a mode in which the user employs a hand-shaped cursor to drag the part within its frame. It is also possible to use page-up and page-down keys or other keyboard input to cause scrolling.
Providing scroll bars is another way to support scrolling. If your part is the root part of a document window or part window, scroll bars are the standard method. If your part is an embedded part displayed in a frame, scroll bars may or may not be appropriate, depending on the size of your frame and the nature of its contents.
Programmatically, changing the portion of a part displayed in a frame involves modifying the offset (translational setting) of the internal transform of the part's frame and then redrawing. If you do not have scroll bars within your frame, these are the basic steps:
Figure 37. Scrolling a Part by Modifying the Frame's Internal Transform
For more information on redrawing frames that include scroll bars or other adornments, see "Drawing with Scroll Bars". For more information on handling scroll bars, interpreting events in them, and redrawing frames that include scroll bars or other adornments, see "Scrolling".
If the graphics system used by your part editor supports all transformations, you can simply modify the internal transform of your display frame to achieve the kinds of special effects shown in Figure 27. By modifying the internal transform appropriately, you not only can position your part's content in its display frames, but you can also scale, rotate, skew, and apply perspective to it. The OS/2 GPI and Windows Win32 API supports all types of transforms except perspective (see Figure 27). The AIX X-Windows graphics system does not provide native support for transformations.
For example, you could change the scale of your part's content to support either higher precision in positioning or larger total content area than would otherwise be possible by including a scale factor in your display frames' internal transforms. Then, to leave embedded parts' displays unaffected by the scaling, you could apply the inverse scaling factor to the external transforms of all embedded facets.
Even if your graphics system (for instance, AIX X-Windows) does not support features such as rotation or skew, you can still "pre-transform" your images by first applying the internal transform to all drawing coordinates, before passing them to the drawing commands.
In general, your containing part can store information on the shapes and positions of embedded frames in any format that is convenient for you. When frames become visible, however, OpenDoc needs that positioning information to allow it to dispatch events correctly and to correctly place the drawn images of each embedded part.
Thus, when you create a facet for a visible frame embedded in your part, you assign it (when calling the CreateEmbeddedFacet method) an external transform whose offset reflects the position of the embedded frame in the coordinate system of your part content. If you later reposition that frame, you need to modify its facet's external transform, if the frame is visible. You can change a facet's external transform, as well as its clip shape, by calling its ChangeGeometry method.
You can use the external transform of a facet embedded in your part to achieve special display effects, regardless of the display intention of the embedded part. By modifying the external transform appropriately, you not only can position the frame within your part's displayed content but can also scale, rotate, skew, and apply perspective to it.
For example, you could make separate embedded frames appear to be the faces of a cube, giving each the proper skew or perspective necessary to achieve the effect, regardless of what is being drawn in each frame by its own part editor.
A shape object is an OpenDoc object that is an instance of the class ODShape. It is the specification of a two-dimensional shape in a given coordinate space. Different platforms and different graphics systems define shapes differently. Objects of the class ODShape are partly wrappers for system-specific shape structures, but they also have the ability to convert among several common shape structures.
OpenDoc uses shape objects for clipping purposes in drawing and hit-testing. There are four drawing-related shapes: the frame shape and used shape, attached to the frame object; and the clip shape and active shape, attached to the facet object.
The frame shape is discussed in many places in this book, including earlier in this chapter, in "Frame and Facet Hierarchies". The frame shape represents the fundamental contract between embedded part and containing part for display space. The other drawing-related shapes are variations on the frame shape, and all are defined in the same coordinate system as the frame shape.
A frame shape is commonly rectangular, as shown in Figure 38, but it can have any kind of outline, even irregular. An embedded part can request a nonrectangular frame shape if it has a special need for one; for example, a part that displays a clock face might request a round frame shape. It is the containing part's right to comply with or deny that request, and it is also the containing part's responsibility to draw that frame's selected appearance, including resize handles, if appropriate.
The frame shape is defined by the containing part and is stored in the frame object. Your part (the containing part) can set an embedded frame's frame shape by calling the frame's ChangeFrameShape method. Any caller may access the frame shape by calling the frame's AcquireFrameShape method.
By convention, your part should use the frame shape when drawing the selected frame border of an embedded part.
Cross-platform representation
The frame shape is stored persistently, and your part may subsequently be displayed under a different graphics system. Therefore, it is important that a frame shape have a platform-neutral (that is, polygonal) representation when it is stored.
An embedded part may need a nonrectangular shape to draw in, may need to change frame shape often, or may want to allow the containing part to be able to draw within portions of its frame. In these cases, the embedded part need not negotiate for an unusual frame shape or continually renegotiate its frame size. Instead it can define a used shape to tell its containing part which portions of its frame shape it is currently using. In Figure 39, for example, the embedded part retains a rectangular frame shape but defines a used shape that covers only the content elements it draws. The containing part can then use that information to, perhaps, wrap its content to the used portions of the embedded part. For example, Figure 13 shows a containing part (a text part) that wraps its text closely to the used shape of an embedded part (a bar-chart part whose frame shape is actually rectangular).
The used shape is defined by the embedded part, specified in frame coordinates, and stored in the frame object. Any caller may access the used shape by calling the frame's AcquireUsedShape method. If the embedded part has not stored a used shape in its frame, AcquireUsedShape returns the frame shape as a default.
It makes no sense for the used shape to extend beyond the edges of the frame shape, because the clip shape, described on "Clip Shape", is based on the frame shape and no drawing occurs outside of the clip shape.
Your part can set its display frame's used shape by calling the frame's ChangeUsedShape method. You can pass a null shape to ChangeUsedShape to make your used shape identical to your frame shape. If you do so, be sure to call ChangeUsedShape again whenever your frame shape changes. When you call ChangeUsedShape, OpenDoc then calls the UsedShapeChanged method of your containing part:
void UsedShapeChanged (in ODFrame embeddedFrame); |
If your part is the containing part in this situation and has wrapped its content to the embedded part's used shape, you can use this method to adjust your content to the new used shape.
A facet's active shape is the area within a frame in which the embedded part is willing to receive geometry-based (mouse) events. The active shape of a facet is often identical to either the frame shape or the used shape of its frame, as shown in Figure 40. The active area of a part is likely to coincide with the area it draws in; events within the frame shape but outside of the used shape are better sent to the containing part, which may have drawn in that area.
The active shape is defined by the embedded part, is specified in frame coordinates, and is stored in the facet object. Your embedded part can set the active shape of its display frame's facet by calling the facet's ChangeActiveShape method. Any caller may access the active shape by calling the facet's AcquireActiveShape method. If the embedded part has not stored an active shape in its facet, AcquireActiveShape returns a copy of the frame's shape.
The effective active shape (the active shape as the user perceives it) is the intersection of the active shape and the clip shape (described next). Events within the area of obscuring content or other frames that block the active shape are not passed to the embedded part.
OpenDoc uses the active shape when drawing the active frame border of an embedded part.
A facet's clip shape defines the portion of a frame that is actually to be drawn. The clip shape of a facet is commonly identical to the frame shape of its frame, except that it may be modified to account for obscuring content elements or overlapping frames in the containing part, as shown in Figure 41.
The clip shape is defined by the containing part, it is specified in frame coordinates, and it is stored in the facet object. Your part (the containing part) can set the clip shape of an embedded frame's facet by calling the facet's ChangeGeometry method. Any caller may access the clip shape by calling the facet's AcquireClipShape method.
This section describes how your part adjusts the clip shapes of its embedded frames' facets before drawing, to account for overlapping relationships among embedded facets and elements of intrinsic content.
Sibling frames are frames embedded at the same level within a containing frame. They may be frames in a frame group (described in "Creating Frame Groups"), or they may be unrelated frames belonging to different embedded parts. Because sibling frames can overlap each other and can overlap (or be overlapped by) intrinsic content of the containing part, it is the responsibility of the containing part to ensure that clipping occurs properly. Figure 42 shows examples of the overlapping relationships that can occur.
Figure 42. Overlapping Content Elements and Sibling Embedded Frames
If your part contains embedded frames, it must maintain a z-ordered (front-to-back) list of the embedded frames and content elements, so that you can reconstruct the overlapping relationships among them. You use that list to update the clip shapes of the facets of your embedded frames.
You control the z-ordering among sibling frames embedded in your part, and you can communicate that information to OpenDoc through the MoveBehind and MoveBefore methods of the containing facet of the sibling frames' facets. The facet positioning you achieve with MoveBehind and MoveBefore is reflected in the order in which you or OpenDoc (or any caller) encounters facets when you use a facet iterator (class ODFacetIterator) to access each of the sibling facets in turn (as, for example, when calculating a resulting clip shape).
If your part contains embedded frames, it performs two related tasks when managing its embedded facets' clip shapes.
In calculating the clip shapes for your embedded parts' facets, remember these points:
Your routine to recalculate embedded-facet clip shapes could take steps similar to these:
Likewise, for each element that is an embedded facet, do this:
The embedded part's drawing area is clipped by OpenDoc. The containing part is responsible for its embedded facets' clip shapes, but the embedded part has some responsibilities, to ensure that drawing occurs properly:
When a part's frame is active, OpenDoc draws the active frame border (shown in the following figure) around the frame. Neither the active part itself nor its containing part need to draw the border.
However, your active part may need to adjust the clipping of the border shape and also adjust the clipping of its own content to account for the border. Furthermore, your part may need to suppress the drawing of the active border in special instances, such as when creating split-frame views. This section discusses both tasks.
The active frame border occupies an area a few pixels wide in the content area of the active part's containing part, and it may overlap or be overlapped by other content elements (embedded frames or intrinsic content) of the containing part (see Figure 43). Therefore, it is up to the containing part to make sure that the active frame border is appropriately clipped by elements in front of the active frame, and that elements behind the active frame are appropriately clipped so that they do not draw themselves within the border area.
Figure 43. An Active Frame Border that Both Obscures and Is Obscured by Content
When a new frame acquires the selection focus, or when the active frame changes its frame shape, OpenDoc calculates a new active border shape. It then passes that shape to the active part's containing part, by calling the containing part's AdjustBorderShape method:
ODShape AdjustBorderShape(in ODFacet embeddedFacet,
in ODShape shape) ;
|
Your AdjustBorderShape method has two tasks: clip the active border shape to account for obscuring content, and clip any of your own content that is obscured by the border.
When the active frame embedded in your part becomes inactive and thus no longer has the active border around it, OpenDoc notifies your part of the change by calling your part's AdjustBorderShape method once more, this time passing a null value for the shape parameter. You can then remove the clipping you had previously applied to your obscured content.
Note:
If your part receives several consecutive calls to its AdjustBorderShape method, it means that your embedded (active) frame has several facets. Consider the active border shape to be the union of all the provided shapes.
In your AdjustBorderShape method, you can take steps such as the following. These steps assume that you maintain a field in your part that is a copy of the clipped active frame border, and that your embedded-frame clipping method (see "Managing Facet Clip Shapes") uses that active-border field to clip your content elements.
If your AdjustBorderShape method does nothing and simply passes back the shape it receives, it must increment the shape's reference count before returning it.
OpenDoc draws the active frame border (see, for example, Figure 11) around a frame of the currently active part. (It actually follows the active shape of the frame's facet, as described in "Active Shape".) When your part is the active part, OpenDoc automatically draws the active frame border around your part's display frame (the frame that has the selection focus).
Situations may occur in which you do not want the active frame border around your part's frame, even when it is active. For example, your part's frame may represent a single pane in a split window (see "Using Multiple Facets"). In this case, the entire window should be considered active, not just a single pane.
In such a case you can force OpenDoc to draw the active frame border around your display frame's containing frame instead of your display frame itself. You can call your display frame's SetSubframe method to assign it as a subframe of its containing frame. (A frame and a subframe must display the same part.)
You can test whether a frame is a subframe of its containing frame by calling its IsSubframe method.
View figure.
View figure.
View figure.
View figure.
View figure.
View figure.
View figure.
View figure.
View figure.
View figure.
View figure.
View figure.
View figure.
View figure.
View figure.
View figure.