A bundle is a collection of attributes that contain imaging information for the rendering device. For instance, paint attributes describe color and pattern. A TGrafBundle collects together the attributes needed to render a 2-D graphic object. The MGraphic class associates a TGrafBundle with a geometry. A descendant of MGraphic can adopt a TGrafBundle, reserving the bundle for its exclusive use until it orphans it. An MGraphic has only one bundle, and only one MGraphic can have the same bundle. However, a TGrafBundle is not always encapsulated in an MGraphic--TGrafPort uses a bundle directly to render a geometry.
The standard attributes contained in a bundle include fill attributes, frame attributes, and the image sampling attribute. The fill attributes include the fill paint (which determines the color and pattern applied to a geometry's interior) and the transfer mode (which helps determine the actual color of the paint when the object is drawn). The frame attributes describe properties of the object's border; these include paint and transfer mode, as well as the styles of pen, starting cap, ending cap, and joint. The final standard attribute is the image sampling attribute, used for rendering the pixels of an image. These standard attributes are described by corresponding classes--TPaint, TTransferMode, TPen, TCap, TJoint, and TImageSamplingControl.
Each bundle has a drawing operation that determines how the graphic is rendered. The drawing operation is either kFill, which fills the graphic's geometry without framing it; kFrame, which draws the border around the geometry without filling its interior; or kFillAndFrame, which draws both the fill and the frame. In the case of geometries that cannot be filled (such as a line or polyline), the geometry is not drawn if kFill is not set.
The TGrafBundle can adopt two TPaint objects. One determines the color and pattern for the fill, and the other determines the color and pattern for the frame. The eventual color of the fill or frame also depends on the transfer mode. The transfer mode specifies how the initial color of the fill or frame is altered when the object is drawn. For example, it can interact with the color that already exists at the location where the object is to be drawn, or it can be turned into a grayscale value. TGrafBundle has member functions for specifying the transfer mode of the fill and the frame.
In addition to the standard attributes, several other less frequently used attributes (derived from TGrafAttribute) are available.
You can also add arbitrary attributes by creating your own TGrafAttribute derived classes (although the rendering device might not be able to do anything with these attributes). Both of these types of nonstandard attributes--those supplied by the Graphics subsystem and those that you create--are referred to as extended attributes.
An extended attribute must be given a name; a good practice is to simply use the name of the attribute's class. A bundle only holds one attribute with a particular name. If a new attribute is added to a bundle that already contains another attribute of the same name, the new attribute replaces the old attribute.
TGrafBundle, derived from TAttributeState, supplies member functions to retrieve, adopt, and orphan all of its standard attributes. To iterate through the extended attributes, use a TGrafBundleIterator object, which you access with TGrafBundle::CreateGrafBundleIterator.
Returns the transfer mode for the fill. The transfer mode specifies how the initial color of the fill is altered when the object is drawn. For example, it can interact with the color that already exists at the location where the object is to be drawn, or it can be turned into a grayscale value.
Calling Context:
Call this function directly.
Parameters:
Takes no parameters.
Return Value:
A constant pointer to the fill transfer mode.
Exceptions:
Throws no exceptions, passes all exceptions through.
Returns the transfer mode for the frame. The transfer mode specifies how the initial color of the frame is altered when the object is drawn. For example, it can interact with the color that already exists at the location where the object is to be drawn, or it can be turned into a grayscale value.
Calling Context:
Call this function directly.
Parameters:
Takes no parameters.
Return Value:
A constant pointer to the frame transfer mode (NIL if no frame paint or pen has yet been specified).
Exceptions:
Throws no exceptions, passes all exceptions through.
Returns the transfer mode for an image. The transfer mode specifies how the initial color of a pixel is altered when the image is drawn (if an image is used to paint this graphic). For example, the pixel's color can interact with the color that already exists at the location where the pixel is to be drawn, or it can be turned into a grayscale value.
Calling Context:
Call this function directly.
Parameters:
Takes no parameters.
Return Value:
A constant pointer to the image transfer mode.
Exceptions:
Throws no exceptions, passes all exceptions through.
Allows for the adoption of a dither hint object. If a primary dither hint is already associated with this graphics bundle, the old dither hint is deleted and replaced by the new hint.
Calling Context:
Call this function directly.
Parameters:
TDitherHint * ditherHint -The dither hint to be adopted.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Assumes ownership of the specified extended attribute. (To add a standard attribute, call the standard Adopt function provided for that attribute.) This extended attribute object is an instance of a TGrafAttribute derived class, whose meaning and use you determine. Note that if you intend to use this extended attribute for rendering, you also need to modify the rendering pipeline by creating a new TGrafDevice derived class.
Calling Context:
Call this function directly.
Parameters:
TGrafAttribute * adoptedAttribute -The extended attribute to be added.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
If there is already an attribute with the same name, it is deleted. Call OrphanGrafAttribute first if you want to keep the object.
Relinquishes knowledge and ownership of the extended attribute that has the specified name. (To remove a standard attribute, call the standard Orphan function provided for that attribute.)
Calling Context:
Call this function directly.
Parameters:
const TToken & attributeName -The name of the attribute.
Return Value:
A pointer to the orphaned TImageSamplingControl. It is the caller's responsibility to subsequently delete the orphaned object.
Exceptions:
Throws no exceptions, passes all exceptions through.
This causes the graphics bundle to orphan its primary dither hint. This is the object used to suggest what form of dithering to use (if the display platform is capable of performing it).
Calling Context:
Call this function directly.
Parameters:
Takes no parameters.
Return Value:
Returns a pointer to the newly-orphaned TDitherHint. If there is no dither hint defined, a NIL pointer is returned.
Exceptions:
Throws no exceptions, passes all exceptions through.
Computes the bounds of a graphic, taking the TGrafBundle's attributes into consideration. Frame attributes such as pen, joint, and cap styles can cause a graphic to be larger than the bounding rectangle of the geometry that the graphic contains. This function examines any attributes that can affect the bounds, and computes the loose fit bounds, based on the geometrical bounds passed in. TGrafAttribute derived classes should implement CanAdjustBounds and AdjustBounds so that the TGrafBundle object knows how to take those attributes into consideration. Despite its name, this function does not alter anything itself; it merely computes and returns a rectangle to be used elsewhere.
Calling Context:
Normally, this function is called by the Graphics system. However, you can call it directly.
Parameters:
const TGRect & currentBounds -The rectangle that bounds the graphic of interest. This should represent the graphic's bounds before adjusting. If an incorrect rectangle is passed in, the resultant rectangle is also incorrect. However, an arbitrary rectangle can be passed in--for example, you can determine a theoretical bounds when no graphic exists yet.
Return Value:
The loose fit bounds.
Exceptions:
Throws no exceptions, passes all exceptions through.
Creates an iterator that can access the bundle's extended attributes, but not the standard attributes. (Each standard attribute is accessible through a corresponding Get function.) If you know the names of the extended attributes, you can retrieve them directly with GetGrafAttribute. The iterator accesses them all without providing names.
Calling Context:
Called by the Graphics system, or directly.
Parameters:
Takes no parameters.
Return Value:
A pointer to the new iterator object. The caller is responsible for subsequently deleting the iterator.
Exceptions:
Throws no exceptions, passes all exceptions through.
Click the icon to mail questions or corrections about this material to Taligent personnel.