Programming Reference
Class Definition File
| Canvas.idl
|
Class C++ Binding
| Canvas.xh
|
Class Hierarchy
|
SOMObject
ODObject
ODBaseCanvas
ODCanvas
|
Description
|
An object of the ODCanvas class is a wrapper for a
graphics-system-specific drawing structure that represents a
drawing environment.
The drawining environment is the environment for constructing an image.
A canvas object represents a drawing environment (the destination
for drawing calls) for any of the available graphics systems that
your part uses.
Your part uses the standard platform drawing calls for
your graphics system to render its content on a canvas.
A canvas can refer to anything that a graphics system
knows how to draw into; for example, a graphics port,
print job, offscreen pixel buffer, bit map, structured display
list, or stream of PostScript code.
A graphic-system-specific drawing structure may retain state
information, such as pen color, that influences how the drawing calls
are interpreted.
Your part creates a canvas object by calling the window-state
object's CreateCanvas method.
To create a canvas to attach to a particular facet, your part
can call that facet's CreateCanvas method.
Each canvas object includes one or more graphic-system-specific drawing
structures, which are not deleted when the canvas is released.
If you create a canvas, you must separately create the underlying
drawing structure, and you are responsible for deleting that drawing
structure when the canvas is released.
Canvas Characteristics
A canvas can be dynamic or static:
dynamic canvas
| A drawing canvas that is interactive.
Windows which can be scrolled or paged to display different portions
of a part's content are good examples of dynamic canvases.
| static canvas
| A drawing canvas that cannot be changed once it is rendered;
for instance, one that cannot be scrolled.
A printed image (or onscreen print preview) is an example of a
static canvas because the user cannot scroll elements on the page or
otherwise interact with it, once it is drawn.
|
Your part can displays parts differently based on this distinction.
For example, you might use scroll bars on the screen but not on
printed material.
You might also use different drawing calls for printing than for screen
display because printing varies from platform to platform.
A canvas definiiton is onscreen or offscreen:
onscreen canvas
| The main canvas of the window or print job.
| offscreen canvas
| This canvas is used to improve performance by allowing you to draw
a complex image to an offscreen cache, and then quickly transfer the
completed image to the onscreen canvas, with full freedom to alter or
distort the image in the process.
For instance, you can create an offscreen canvas to do double-buffering
or image manipulation, such as changing the tinting or translucency of
an image.
|
When a part creates a canvas, it specifies, for the lifetime of the canvas,
whether the canvas is dynamic or static and whether it is onscreen
or offscreen.
A canvas is further defined in terms of a transformation matrix and
its coordinate bias:
bias transform
| A transform matrix that describes the transform that is applied
to measurements in a canvas' coordinate space to change them
into standard platform-normal coordinates.
Bias transforms are used to negotiate between the containing part and
the embedded part.
The negotiation occurs when several canvases, each defined in its own
coordinate space, are combined into a single coordinate system.
Facets use bias transforms to convert geometry from one coordinate
space to the other, usually so that a part can use the geometry to
display on its canvas.
Each canvas is scaled, rotated, and translated by redefinition of
its coordinates in the bias canvas' coordinate space.
Thus, once 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 property converted for you.
| coordinate bias
| This is defined by the bias transform.
It is the difference between the canvas' coordinate space
and the standard platform-normal coordinate space.
The 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.
|
Offscreen Imaging
Canvases can be attached to individual facets.
If a particular facet in a window's facet hierarchy has an
attached canvas, it and all of its embedded facets (and their embedded
facets, and so on) draw to that canvas.
Each facet inherits its canvas from its containing facet; the
inherited canvas is called the parent canvas.
For most drawing, only a window's root facet needs a canvas.
If a particular part needs an offscreen canvas, however, it can
attach a canvas to one of its facets on a display frame.
The canvas has a reference to that facet and a reference to
the part that created the canvas and attached it to a facet, the
owning part.
The reference enables the canvas to notify the owning part that its
content has changed and that it needs to be updated.
The owning part is responsible for copying the image of the offscreen
canvas to its parent canvas during updates.
The owning part of a canvas does not need to be the same as the
facet's part.
For instance, a containing part may customize the drawing of an
embedded part by assigning the facet of the embedded part to an
offscreen canvas.
In this case, the containing part must make itself the owning part so
that it can control the drawing of the facet on the screen.
For added convenience, offscreen canvases maintain updating
information that mirrors their onscreen equivalents.
This lets embedded parts interact with their drawing environment in a
consistent manner, whether the parts are displayed in the window
canvas or in an offscreen canvas.
|
Methods
|
The methods defined by the ODCanvas class include:
|
Overridden Methods
|
There are no methods overridden by the ODCanvas class.
|
This method returns a reference to the bias transform associated
with this canvas.
Signature
ODTransform *AcquireBiasTransform ()
|
Parameters
None.
Returns
- rv (ODTransform *) - returns
-
A reference to the bias transform associated with this canvas or kODNULL
if no bias transform has previously been assigned to this canvas.
Remarks
If you call methods that modify the returned transform, you must then
call this canvas' SetBiasTransform method
to set its bias transform to the modified transform.
This method increments the reference count of the returned transform object.
When you have finished using that transform object, you should call
its Release method.
Related Methods
This method returns a reference to the part that owns this canvas.
Signature
Parameters
None.
Returns
- rv (ODPart *) - returns
-
A reference to the part that owns this canvas or kODNULL
if the part does not exist.
Remarks
This method increments the reference count of the returned part object.
When you have finished using that part object, you should call its
Release method.
Related Methods
This method returns a reference to the shape object defining the area
of this canvas that needs to be updated.
Signature
ODShape *AcquireUpdateShape ()
|
Parameters
None.
Returns
- rv (ODShape *) - returns
-
A reference to the shape object defining the area of this canvas that
needs to be updated.
Remarks
OpenDoc calls this method internally.
Your part modifies the update shape of a canvas by calling its facet's
Invalidate and Validate
methods.
This method increments the reference count of the returned shape object.
When the caller has finished using that shape object, it should call
the shape's Release method.
Related Methods
This method returns a reference to the facet associated with
this canvas.
Signature
Parameters
None.
Returns
- rv (ODFacet *) - returns
-
A reference to the facet associated with this canvas.
Related Methods
This method returns the drawing structure for the specified graphics
system for this canvas.
Signature
ODPlatformCanvas *GetPlatformCanvas (ODGraphicsSystem g)
|
Parameters
- g (ODGraphicsSystem) - input
-
The graphics system you want to use for this canvas.
Valid graphics systems are platform dependant:
- For OS/2, use kODPM.
- For Windows, use kODWin32, kODWin95, or kODWinNT.
- For AIX, use KODAIX.
Returns
- rv (ODPlatformCanvas *) - returns
-
A pointer to the graphics-system specific drawing structure
for this canvas or kODNULL if this canvas does not have and cannot
generate a drawing structure for the specified graphics system.
Valid values for this structure are graphics-system specific.
ODPlatformCanvas is a class that encapsulates
one or more graphics systems specific to the drawing context.
Remarks
You call this method to get the graphics-system-specific
drawing structure (for instance, a window or view port) when you
need to draw into a facet.
On each platform, this method returns a reference to a platform
canvas object that encapsulates a drawing context specific to
the platform and graphics library.
On OS/2, the platform canvas wraps one or more GPI presentation spaces.
On Windows, the platform canvas wraps a drawing context (DC).
On AIX, the platform canvas wraps an X-Windows graphic context (GC).
Your part calls this method when it needs to obtain a platform-specific
context in which to draw.
See ODPlatformCanvas for more information.
You must specify the graphics system because some implementations
allow you to set drawing structures for two or more graphics
systems simultaneously.
The specific graphics system supported is implementation dependent.
For more information on graphic-system-specific drawing structures,
see the Graphics Programming Interface Programming Guide.
Exception Handling
kODErrInvalidGraphicsSystem
| This implementation of OpenDoc does not support the specified
graphics system, that graphics system is not installed or available,
or this canvas has no drawing structure for that graphics system.
|
Related Methods
This method returns the print job for a specified graphics system
for this canvas.
Signature
ODPlatformPrintJob GetPlatformPrintJob (ODGraphicsSystem g)
|
Parameters
- g (ODGraphicsSystem) - input
-
The graphics system you want to use for this canvas.
Valid graphics systems are platform dependent:
- For OS/2, use kODPM.
- For Windows, use kODWin32, kODWin95, or kODWinNT.
- For AIX, use KODAIX.
Returns
- rv (ODPlatformPrintJob) - returns
-
The graphics-system-specific print job for this canvas.
You must cast the return value to a valid graphics-system type
before using it.
Remarks
If this canvas has a print job for the specified graphics system,
this method returns that print job.
Call this method when you create a static canvas to be used as a print
job.
A canvas can have only one print job for one graphics system even
when it has drawing structures for more than one graphics system.
Exception Handling
kODErrInvalidGraphicsSystem
| The implementation of OpenDoc does not support the specified
graphics system, that graphic system is not installed or available,
or this canvas does not have a print job for that graphics system.
|
Related Methods
This method indicates whether this canvas has or can generate
drawing structure for the specified graphics system.
Signature
ODBoolean HasPlatformCanvas (ODGraphicsSystem g)
|
Parameters
- g (ODGraphicsSystem) - input
-
The graphics system you want to check for this canvas.
Valid graphics systems are platform-dependent:
- For OS/2, use kODPM.
- For Windows, use kODWin32, kODWin95, or kODWinNT.
- For AIX, use KODAIX.
Returns
- rv (ODBoolean) - returns
-
A flag indicating whether this canvas has or can generate a
drawing structure for the specified graphics system.
This parameter can be set to one of the following values:
| kODTrue
| This canvas has or can generate a drawing structure for the
specified graphics system.
|
| kODFalse
| This canvas does not have and cannot generate a
graphics-system-specific drawing structure.
|
Related Methods
This method indicates whether this canvas has a print job for the
specified graphics system.
Signature
ODBoolean HasPlatformPrintJob (ODGraphicsSystem g)
|
Parameters
- g (ODGraphicsSystem) - input
-
The graphics system you want to check for this canvas.
Valid graphics systems are platform-dependent:
- For OS/2, use kODPM.
- For Windows, use kODWin32, kODWin95, or kODWinNT.
- For AIX, use KODAIX.
Returns
- rv (ODBoolean) - returns
-
A flag indicating whether this canvas has a print job for the specified
graphics system.
This parameter can be set to one of the following values:
| kODTrue
| This canvas has a print job for the specified graphics system.
|
| kODFalse
| This canvas does not have a print job for the specified graphics
system.
|
Related Methods
This method adds the specified area to the update shape for this
canvas, ensuring that the specified area for this canvas is updated.
Signature
void Invalidate (ODShape *shape)
|
Parameters
- shape (ODShape *) - input
-
A reference to the shape object defining the area to be added to the
update shape for this canvas.
Returns
None.
Remarks
OpenDoc calls this method to mark the area of a canvas that
needs updating.
Generally, your part calls the ODFacet::Invalidate
method to transform and clip the shape from the coordinate space of
the facet to the coordinate space of its canvas.
Exception Handling
kODErrIllegalNullImport
| The reference to ODShape was NULL.
|
Related Methods
This method indicates whether this canvas is dynamic.
Signature
Parameters
None.
Returns
- rv (ODBoolean) - returns
-
A flag indicating whether the canvas is dynamic.
This parameter can be set to one of the following values:
| kODTrue
| This canvas is dynamic.
|
| kODFalse
| This canvas is static.
|
Remarks
The dynamic or static characteristic of a canvas is set when the
canvas is created and cannot be changed.
This method indicates whether this canvas is offscreen.
Signature
Parameters
None.
Returns
- rv (ODBoolean) - returns
-
A flag indicating whether the canvas is offscreen.
This parameter can be set to one of the following values:
| kODTrue
| This canvas is offscreen.
|
| kODFalse
| This canvas is onscreen.
|
Remarks
The onscreen or offscreen characteristic of a canvas is set when the
canvas is created and cannot be changed.
This method sets the update shape for this canvas to the empty shape.
Signature
Parameters
None.
Returns
None.
Remarks
OpenDoc calls this method while processing update events
and after all the invalidated canvases have been updated.
Related Methods
This method assigns the specified bias transform to this canvas.
Signature
void SetBiasTransform (ODTransform *x)
|
Parameters
- x (ODTransform *) - input
-
A reference to the bias transform object to be assigned to this canvas.
Returns
None.
Remarks
This bias transform is calculated by concatenating the internal
transform of this canvas' owning frame with the internal transform
of the root frame.
Use this method to add a vertical flip and offset between
frames of graphics systems whose coordinate spaces have different
handedness, for example, Mac OS-, Windows-, or X-Windows-based frames
on an OS/2 system.
After this method executes successfully, any preexisting bias
transform is released and this canvas owns the new transform.
You can call the AcquireBiasTransform method of this canvas to obtain
a reference to the resulting bias transform.
You should release the transform object
immediately after passing it as a parameter to this method.
Related Methods
This method assigns the specified facet to this canvas.
Signature
void SetFacet (ODFacet *facet)
|
Parameters
- facet (ODFacet *) - input
-
A reference to the facet to be assigned to this canvas.
Returns
None.
Remarks
OpenDoc calls this method when the canvas is added to the facet.
Related Methods
This method assigns the specified owning part to this canvas.
Signature
void SetOwner (ODPart *owner)
|
Parameters
- owner (ODPart *) - input
-
A reference to the owning part to be assigned to this canvas.
Returns
None.
Remarks
Call this method after your part creates a custom canvas.
Related Methods
This method assigns the drawing structure for the specified graphics system
to this canvas.
Signature
void SetPlatformCanvas (ODGraphicsSystem g,
ODPlatformCanvas *c)
|
Parameters
- g (ODGraphicsSystem) - input
-
The graphics system whose drawing structure is to be set.
Valid graphics systems are platform-dependent:
- For OS/2, use kODPM.
- For Windows, use kODWin32, kODWin95, or kODWinNT.
- For AIX, use KODAIX.
- c (ODPlatformCanvas *) - input
-
The graphics-system specific drawing structure to be assigned to this
canvas or kODNULL to remove the drawing structure from a graphics
system.
Valid values for this parameter are graphics-system-dependent.
ODPlatformCanvas is a class that encapsulates drawing context specific
to a platform and graphics library.
On OS/2, the platform canvas wraps one or more GPI presentation spaces.
On Windows, the platform canvas wraps a drawing context (DC).
On AIX, the platform canvas wraps an X-Windows graphics context (GC).
See ODPlatformCanvas for more information.
Returns
None.
Remarks
You can assign any graphics-system-specific drawing
structure that a part might use.
On some platforms, a canvas can have drawing structures
for two or more graphics systems simultaneously.
Exception Handling
kODErrInvalidGraphicsSystem
| The implementation of OpenDoc does not support the specified
graphics system or that graphics system is not installed or available.
|
Related Methods
This method assigns the print job for the specified graphics system
to this canvas.
Signature
void SetPlatformPrintJob (ODGraphicsSystem g,
ODPlatformPrintJob j)
|
Parameters
- g (ODGraphicsSystem) - input
-
The graphics system whose print job is to be set.
Valid graphics systems are platform-dependent:
- For OS/2, use kODPM.
- For Windows, use kODWin32, kODWin95, or kODWinNT.
- For AIX, use KODAIX.
- j (ODPlatformPrintJob) - input
-
The graphics-system-specific print job to be assigned to this canvas
or kODNULL to clear the print job.
Valid values for this parameter are graphics-system dependent.
For generality, an ODPlatformPrintJob typed as a (void*).
You can create a pointer to a platform specific type and cast it to an
ODPlatformPrintJob when calling this method.
On OS/2, an ODPlatformPrintJob can be a pointer to an instance of a
PRINTDEST structure.
On Windows, it can be a pointer to a PRINTDLG structure.
On OS/2, if you pass a pointer to a PRINTDEST structure, you must not
modify or free the memory in this structure until after the print job
spools and the platform print job is cleared by calling the
SetPlatformPrintJob method with this parameter set to kODNULL.
Returns
None.
Remarks
Call this method when you create a static canvas for a print job.
Related Methods
This method subtracts the specified area from the update shape for
this canvas.
Signature
void Validate (ODShape *shape)
|
Parameters
- shape (ODShape *) - input
-
A reference to the shape object defining the area to be subtracted from
the update shape for this canvas.
Returns
None.
Remarks
OpenDoc calls this method mark an area of a canvas that
no longer needs updating.
Generally, your part calls the ODFacet::Validate
method to transform and clip
the shape from the coordinate space of the facet to the coordinate
space of its canvas.
Related Methods
[ Top | Previous | Next | Contents | Index | Documentation Homepage ]