IDrawingCanvas

The IDrawingCanvas class is a control class that provides support for drawing graphic objects. The drawing canvas contains an IGraphicGroup to which you can add graphic objects. By default, a paint handler is attached to the drawing canvas. When paint events occur, the paint handler sets the clip region to the drawing canvas' update region and iterates through the IGraphicGroup, redrawing the graphic objects necessary to update the window. If you do not add graphic objects to the IGraphicGroup, the drawing canvas simply paints the window using the current background color.

If you want to use your own paint handler instead of the drawing canvas' default paint handler, construct the IDrawingCanvas object without the useDefaultPaintHandler style. The default paint handler will not be attached to the drawing canvas.

You have the option of setting the graphic context that the drawing canvas will use when drawing the graphic objects contained in the IGraphicGroup object. By changing graphic contexts, you can change the appearance of the graphic objects or the device on which they are rendered.

To add graphic objects to a drawing canvas, create an IGraphicGroup object and call setGraphicList. The drawing canvas iterates through the drawing canvas for its IGraphicGroup. You can easily change the objects drawn in the drawing canvas by changing the IGraphicGroup object.

NOTE: The behavior of IDrawingCanvas has changed subtly in this release. In the past, the drawing canvas would repaint anytime it was resized. In this release, if the drawing canvas is resized smaller, it does not repaint. If your application requires the drawing canvas to repaint in this case call the refresh member function. In all other resize cases, the drawing canvas paints as it did in prior releases.


IDrawingCanvas - Member Functions and Data by Group

Constructors & Destructor

You can construct and destruct objects of this class. You cannot copy or assign IDrawingCanvas objects because both the copy constructor and assignment operators are private functions.


[view class]
~IDrawingCanvas
public:
virtual ~IDrawingCanvas()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
IDrawingCanvas
public:
IDrawingCanvas( unsigned long windowIdentifier, IWindow* parent, IWindow* owner, const IRectangle& initial = IRectangle ( ), const Style& style = defaultStyle ( ) )
windowIdentifier
The window identifier of the drawing canvas you are constructing.

We recommend that you do the following:

  • For portability, use a value in the range 0 to 65535.
  • Give unique identifiers to all windows in the same frame window. Two windows are in the same frame window if the first frame window in each of its parent window chains is the same window.
  • Give the client window a window identifier of IC_FRAME_CLIENT_ID, which is defined in the file icconst.h.

Presentation Manager Notes Do not use FID_xxx values defined in pmwin.h, other than FID_CLIENT (which is equivalent to IC_FRAME_CLIENT_ID).
parent
The parent window of the drawing canvas you are constructing. You must specify a parent window. The parent window is primarily used for visible relationships.
owner
The owner window of the drawing canvas you are constructing. The owner window is primarily used for routing notification events and unprocessed messages. A window also inherits colors from its owner window.
Motif Notes The owner window is only used for routing unprocessed messages. There is no concept of an owner in Motif.
initial
The initial position and size of the drawing canvas you are constructing. The position is relative to the origin of the parent window. See ICoordinateSystem for additional information. Optional.
style
The window's characteristics. This value can be a combination of IDrawingCanvas::Style, ICanvas::Style and IWindow::Style objects. Optional.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Canvas Support

These members override the inherited canvas-protected functions to provide layout support.


[view class]
calcMinimumSize
protected:
virtual ISize calcMinimumSize() const

Returns the minimum screen size this control can occupy, based on the size and positions of its child windows and graphic objects.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Drawing Port

Use these members to set and query the IGrafPort object, which is the drawing port that the drawing canvas uses when painting the window.


[view class]
grafPort
public:
virtual IGrafPort* grafPort() const

Returns a pointer to the drawing port that the drawing canvas uses for paint events. By default, the drawing canvas uses the drawing port that is provided from the paint event.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setGrafPort
public:
virtual void setGrafPort(IGrafPort* grafPort)

Sets the drawing port that the drawing canvas uses when painting the window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Graphic Group

Use these members to set and query the IGraphicGroup object, which the drawing canvas draws when paint events occur.


[view class]
graphicGroup
public:
virtual IGraphicGroup* graphicGroup() const

Returns a pointer to the IGraphicGroup object set for the drawing canvas.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setGraphicGroup
public:
virtual void setGraphicGroup(IGraphicGroup* group)

Sets the IGraphicGroup object that the drawing canvas draws when paint events occur.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Styles

Use these style members to customize a window at the time you construct it. Most styles have equivalent member functions, which allow you to similarly modify a window after creating it. You can use these styles with the styles defined by the following nested classes:

Once you have constructed an IDrawingCanvas object, you can use IDrawingCanvas, ICanvas, and IWindow member functions to query and change individual styles.


[view class]
convertToGUIStyle
public:
virtual unsigned long convertToGUIStyle( const IBitFlag& style, bool extendedOnly = false ) const

Converts a style object into a value appropriate for the underlying system. The default action is to return the base GUI styles for the platform. Extended styles, those defined by the application and the Open Class Library, will be returned if you set extendedOnly to true.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
defaultStyle
public:
static Style defaultStyle()

Returns the current default style, which is the same as classDefaultStyle unless you have changed the style using setDefaultStyle.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setDefaultStyle
public:
static void setDefaultStyle(const Style& style)

Sets the default style for all subsequent drawing canvases.

This member function is not thread safe. In a multithreaded application, it should only be called when a conflict is not possible. A conflict can arise if you set the default style on one thread at the same time that it is being queried on another. In this situation, the query would take place while the style is in an unknown state.

When you create a window class and do not specifically specify window styles in the constructor, the Open Class Library queries the default style. Therefore, the only safe place to call this member function is when no other application threads that create windows are active.

Another way to avoid a conflict in a multithreaded application is to specifically specify window styles on window construction, rather than calling this member function.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
classDefaultStyle
public:
static const Style classDefaultStyle

Specifies the original default style for this class, which is IDrawingCanvas::useDefaultPaintHandler | IWindow::visible | IWindow::clipSiblings.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
useDefaultPaintHandler
public:
static const Style useDefaultPaintHandler

If this style is set, a default paint handler attaches to the drawing canvas. If this style is not set, you must handle window painting.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IDrawingCanvas - Inherited Member Functions and Data

Inherited Public Functions

ICanvas
IControl
INotifier
IWindow

Inherited Public Data

IWindow
INotifier
ICanvas

Inherited Protected Functions

IWindow
INotifier
ICanvas
IControl

Inherited Protected Data