Programming Reference: ODCanvas

# Programming Reference

## ODCanvas

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:

- AcquireBiasTransform
- AcquireOwner
- AcquireUpdateShape
- GetFacet
- GetPlatformCanvas
- GetPlatformPrintJob
- HasPlatformCanvas
- HasPlatformPrintJob
- Invalidate
- IsDynamic
- IsOffscreen
- ResetUpdateShape
- SetBiasTransform
- SetFacet
- SetOwner
- SetPlatformCanvas
- SetPlatformPrintJob
- Validate

Overridden Methods | There are no methods overridden by the ODCanvas class.

### AcquireBiasTransform

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

- ODCanvas::SetBiasTransform

### AcquireOwner

This method returns a reference to the part that owns this canvas.

Signature

    ODPart *AcquireOwner ()

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

- ODCanvas::SetOwner

### AcquireUpdateShape

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

- ODCanvas::Invalidate
- ODCanvas::ResetUpdateShape
- ODCanvas::Validate
- ODFacet::Invalidate
- ODFacet::Validate

### GetFacet

This method returns a reference to the facet associated with this canvas.

Signature

    ODFacet *GetFacet ()

Parameters

None.

Returns

rv (ODFacet *) - returns

  A reference to the facet associated with this canvas.

Related Methods

- ODCanvas::SetFacet

### GetPlatformCanvas

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

- ODCanvas::HasPlatformCanvas
- ODCanvas::SetPlatformCanvas

### GetPlatformPrintJob

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

- ODCanvas::HasPlatformPrintJob
- ODCanvas::SetPlatformPrintJob

### HasPlatformCanvas

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

- ODCanvas::GetPlatformCanvas
- ODCanvas::SetPlatformCanvas

### HasPlatformPrintJob

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

- ODCanvas::GetPlatformPrintJob
- ODCanvas::SetPlatformPrintJob

### Invalidate

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

- ODCanvas::Validate
- ODFacet::Invalidate
- ODFrame::Invalidate

### IsDynamic

This method indicates whether this canvas is dynamic.

Signature

    ODBoolean IsDynamic ()

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.

### IsOffscreen

This method indicates whether this canvas is offscreen.

Signature

    ODBoolean IsOffscreen ()

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.

### ResetUpdateShape

This method sets the update shape for this canvas to the empty shape.

Signature

    void ResetUpdateShape ()

Parameters

None.

Returns

None.

Remarks

OpenDoc calls this method while processing update events and after all the invalidated canvases have been updated.

Related Methods

- ODCanvas::AcquireUpdateShape

### SetBiasTransform

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

- ODCanvas::AcquireBiasTransform

### SetFacet

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

- ODCanvas::GetFacet

### SetOwner

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

- ODCanvas::AcquireOwner

### SetPlatformCanvas

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

- ODCanvas::GetPlatformCanvas
- ODCanvas::HasPlatformCanvas

### SetPlatformPrintJob

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

- ODCanvas::GetPlatformPrintJob
- ODCanvas::HasPlatformPrintJob

### Validate

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

- ODCanvas::Invalidate
- ODFacet::Validate
- ODFrame::Validate

[ Top | Previous | Next | Contents | Index | Documentation Homepage ]