ICanvas

An ICanvas window consists of a plain flat surface on which you can place other windows. The ICanvas class provides a minimal, base set of function such as dialog-like behavior for its child windows. While the ICanvas derived classes provide additional function such as sizing and positioning of child windows.

The ICanvas class support of dialog-like behavior for its child windows includes the following:

For much of this support to work, however, the canvas must be the owner window of its child windows.

Additionally, this class provides the above behavior for all derived classes.

You can use a canvas as the client window for a frame window, as a frame extension, or as the child window of another canvas. To specify the client window for an IFrameWindow, use IFrameWindow::setClient. To add a canvas as a frame extension, use IFrameWindow::addExtension.

Unlike other canvas classes, ICanvas does not alter the size or position of its child windows. Others, such as IMultiCellCanvas, ISetCanvas, ISplitCanvas, and IViewPort, provide special layout rules for sizing and positioning their child windows.
Note: To have a group box appear around the contents of a canvas or a class derived from ICanvas, use the function ICanvas::setBorderText, in place of creating an IGroupBox object.


ICanvas - Member Functions and Data by Group

Constructors & Destructor

ICanvas provides functions to help you implement the constructors of derived classes.


[view class]
initialize
protected:
ICanvas& initialize( unsigned long windowIdentifier, IWindow* parent, IWindow* owner, const IRectangle& initialRect, unsigned long style, unsigned long extendedStyle )

Creates an underlying system window and calls IWindow::startHandlingEventsFor. Call this function from a constructor of a class derived from ICanvas if the constructor calls the protected ICanvas constructor.

Exception

IAccessError Open Class Library was unable to register a canvas window class with the operating system.
IInvalidParameter You must specify a nonzero value for parent.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

OS/2 Considerations

The extendedStyle parameter is ignored.


Bidirectional Language Support

These members allow a window to support bidirectional languages, such as Arabic and Hebrew. These languages are written and read right-to-left, but text in these languages may also contain strings that are written and read left-to-right.


[view class]
setBidiSettings
protected:
virtual ICanvas& setBidiSettings( const IBidiSettings& bidiSettings, bool childInherit, bool refresh )

This function allows a canvas to provide special processing to support a change in its bidirectional characteristics. This function is called just before the bidirectional characteristics of the canvas change. This function is not called when you create a window.

If the window layout direction is changing, the canvas calls setLayoutDistorted to indicate that it needs to run its layout function to update the positions of its child windows.

bidiSettings
The new bidirectional settings for the canvas.
childInherit
This flag specifies if the child windows of the canvas will inherit the new bidirectional attributes.
refresh
This flag specifies if the canvas will paint after receiving the new directional attributes.

Supported Platforms

Windows OS/2 AIX
Yes Yes No

AIX Considerations

This function is not provided because you cannot change the bidirectional attributes of a window on that platform after you create it.


Border and Text

A canvas optionally draws a border inside its edges to help frame its contents. You can also specify border text that the canvas will place in the top line of the border.

To assist derived classes in supporting borders, ICanvas also provides functions for querying the area where it will draw the border.


[view class]
addBorder
public:
virtual ICanvas& addBorder()

Adds a border to the canvas. If you have previously assigned border text to the canvas using setBorderText, the canvas displays the text in addition to the border.

The canvas may change the size and position of its contents in order to display the border and border text.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
borderText
public:
IText borderText() const

Returns the border text assigned to the canvas.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
bottomRightLayoutOffset
public:
IPoint bottomRightLayoutOffset() const

Returns the offset to the point inside the bottom, right corner of the canvas where it can position its contents. If the canvas is displaying a border, this offset is inside the corner of the border; otherwise this offset is 0. Placing contents outside this offset may cause the border to be overwritten.

Classes derived from ICanvas can use this function to layout their contents within the border of the canvas.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
hasBorder
public:
virtual bool hasBorder() const

Returns true if the canvas is displaying a border. You can add a border to a canvas using any of the following:

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
removeBorder
public:
virtual ICanvas& removeBorder()

Removes the border and optional border text from the canvas. The canvas may reposition its contents to use the space that the border and text occupied. A later call to addBorder will show the border again with the previous border text.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setBorderText

Sets the text the canvas draws in the top line of the border.


Overload 1
public:
virtual ICanvas& setBorderText( const IText& borderText, bool showBorder = true )

This function uses text that can contain color and font information.

borderText
Identifies the text string to use as the border text. Specifying a zero-length string causes the canvas to draw a border without border text. A canvas cannot draw border text without a border.
showBorder
Specifies whether the canvas should display a border and the border text if it is not already displaying a border. If the canvas already displays a border, either from a previous call to addBorder or setBorderText, this value is ignored and the new border text is drawn. If the canvas is not already displaying a border and you specify a value of false, you must later call addBorder to show the border and border text.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual ICanvas& setBorderText( const IResourceId& borderText, bool showBorder = true )

This function loads the text from a resource library.

borderText
Identifies the text string to use as the border text. Specifying a zero-length string causes the canvas to draw a border with no border text. A canvas cannot draw border text without a border.
showBorder
Specifies whether the canvas should display a border and the border text if it is not already displaying a border. If the canvas already displays a border, either from a previous call to addBorder or setBorderText, this value is ignored and the new border text is drawn. If the canvas is not already displaying a border and you specify a value of false, you must later call addBorder to show the border and border text.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
topLeftLayoutOffset
public:
IPoint topLeftLayoutOffset() const

Returns the offset to the point inside the top, left corner of the canvas where it can position its contents. If the canvas is displaying a border, this offset is inside the corner of the border and below any border text; otherwise this offset is 0. Placing contents outside this offset may cause the border or border text to be overwritten.

Derived classes can use this function to layout their contents within the border of the canvas.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
rectangleInsideBorder
protected:
IRectangle rectangleInsideBorder( const ISize& sizeWithBorder ) const

Returns the portion of the canvas that would be within a border if the canvas had the specified size. If the canvas is not displaying a border, this function returns a rectangle constructed from the specified size. Otherwise the size is decremented by the amount of space required by the border and optional border text.

Classes derived from ICanvas can use this function to determine how they should size and position their contents to avoid overwriting the border of the canvas.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
sizeWithBorder
protected:
ISize sizeWithBorder(const ISize& sizeWithoutBorder) const

Returns the window size needed by the canvas to include a border around the specified area. If the canvas is not displaying a border, this function returns the specified size. Otherwise it returns the specified size incremented by the amount of space required by the border and optional border text.

Classes derived from ICanvas can use this function to calculate a minimum size that includes the border and border text of the canvas.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Colors

Use these members to query, set, and reset the color of a specified region of the window.


[view class]
backgroundColor
public:
virtual IColor backgroundColor() const

Returns the background color value of the window area. The default color is returned if no color has been set.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Portability Considerations

This member is overridden in this derived class for specific operating system behavior.


[view class]
borderColor
public:
virtual IColor borderColor() const

Returns the color of the border that the canvas draws. This function returns the default color if no color has been set.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
resetBorderColor
public:
virtual ICanvas& resetBorderColor()

Resets the color that the canvas uses to draw its border to the default color.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setBorderColor
public:
virtual ICanvas& setBorderColor(const IColor& borderColor)

Sets the color that the canvas uses to draw its border. The canvas uses a default color if no color has been set.

This function does not affect the colors used to create highlighting and shading for the border. This function also does not affect the color of the border text, which you can specify as part of the IText object that you pass to setBorderText.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Constructors

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

AIX Considerations

For Motif applications, you can also use the protected ICanvas constructor for derived classes that do not need the BulletinBoard widget that the above constructor creates.


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
ICanvas


Overload 1
public:
ICanvas( unsigned long windowIdentifier, IWindow* parent, IWindow* owner, const IRectangle& initial = IRectangle ( ), const Style& style = defaultStyle ( ) )

Use this constructor to create a canvas window.

windowIdentifier
The window identifier of the 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 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 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 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 ICanvas::Style and IWindow::Style objects. Optional.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
protected:
ICanvas()

Derived classes that create their own windows should call this ICanvas constructor. If you use this constructor, you can call ICanvas::initialize to create a canvas window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Dialog Behavior Support

Use these members to provide dialog-like keyboard support for the canvas classes.


[view class]
isTabStop
public:
virtual bool isTabStop() const

If the canvas can be tabbed to, true is returned. If any of the canvas's child windows can be tabbed to, the canvas can be tabbed to.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
matchForMnemonic
public:
virtual IWindowHandle matchForMnemonic( unsigned short character ) const

Returns the first child window using the specified character as a mnemonic.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Event-Handling Implementation

Event-handling implementation members perform processing needed to allow event handlers to properly receive and route events.


[view class]
passEventToOwner
protected:
virtual bool passEventToOwner(IEvent& event)

Determines whether an event can be passed to the owner window of this canvas.

Supported Platforms

Windows OS/2 AIX
Yes No Yes


Font Functions

Use these members to query and set the font of a specified region of the window.


[view class]
font
public:
virtual IFont font() const

Returns the font used by the canvas.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
resetFont
public:
virtual ICanvas& resetFont()

Resets the font of the canvas to the default font.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
setFont
public:
virtual ICanvas& setFont(const IFont& font)

Sets the font of the canvas to the indicated font. Child windows of the canvas that do not have their own assigned font will inherit this font.

The specified font also becomes the default font of the border text, which you can assign using the function setBorderText. However, if you specify a font as part of the IText object that you pass to setBorderText, that font takes precedence over a default font that you set through this function.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Layout Support

Layout members determine how this class sizes and positions its child windows or how this window will be laid out on another canvas.


[view class]
hasChildrenToLayout
public:
virtual bool hasChildrenToLayout() const

Indicates whether the canvas contains child windows that it manages.

This version returns true if the canvas contains any child windows; otherwise it returns false. Derived classes may provide class-specific behavior.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setLayoutDistorted
public:
virtual ICanvas& setLayoutDistorted( unsigned long layoutAttributesOn, unsigned long layoutAttributesOff )

Provides notification to a canvas that its layout of child windows needs to be updated. All windows maintain an internal state and use setLayoutDistorted to update that state and to communicate any changes to the parent window.

The canvas object uses these state changes to update the size and position of its child windows. The internal state of a window is the enumeration IWindow::Layout.

ICanvas::setLayoutDistorted adds the IWindow::layoutDistorted flag to its internal state if it receives a value of IWindow::childWindowCreated or IWindow::childWindowDestroyed and calls IWindow::setLayoutDistorted. If the IWindow::immediateUpdate flag is on, the canvas runs its layout routine.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
areChildrenReversed
protected:
bool areChildrenReversed() const

States whether the order in which child windows are returned by the class IWindow::ChildCursor matches the order in which the child windows were constructed.

This returns false only if the static function IWindow::setDefaultOrdering is called with the enumerator IWindow::onTopOfSiblings and the canvas has not run its layout routine.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[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.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
fixupChildren
protected:
virtual IWindowPosBuffer fixupChildren()

Generates a list of all child windows, determines if any can be tabbed to, and allows for reversing the order in which they are iterated.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
layout
protected:
virtual ICanvas& layout()

Derived classes use this function to size and position child windows.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
layoutSize
protected:
ISize layoutSize() const

Returns the size needed to show all child windows.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setLayoutSize
protected:
ICanvas& setLayoutSize(const ISize& size)

Sets the size needed to show all child windows.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Notification Members

ICanvas provides notifications that allow observers to process changes to the window.


[view class]
textId
public:
static INotificationId const textId

Notification identifier provided to observers when the border text of the canvas changes.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Styles

ICanvas defines objects of the nested class ICanvas::Style. You can use these styles with ICanvas::setDefaultStyle and with constructors of the ICanvas class. You can combine ICanvas::Style objects with the objects of the class IWindow::Style.

Use these members to customize a window at the time you create it. Once you have constructed an ICanvas object, you can use 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, are 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 default style. The default style is 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 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]
border
public:
static const Style border

Draws a border inside the edges of the canvas. If you call the function setBorderText, the text you specify will be placed in the top line of the border.

The canvas will position its contents inside the border and border text, if possible.

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 IWindow::visible.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


ICanvas - Inherited Member Functions and Data

Inherited Public Functions

IControl
INotifier
IWindow

Inherited Public Data

IWindow
INotifier

Inherited Protected Functions

IWindow
INotifier
IControl

Inherited Protected Data