ISetCanvas

The ISetCanvas class provides a window that organizes the windows it contains in row or column decks.

Deck is the direction-independent term for a line of child windows in a set canvas window. A horizontal deck is equivalent to a row and a vertical deck is equivalent to a column. An ISetCanvas object can hold more than one deck of child windows, but the decks must be either all horizontal or all vertical.

This class best arranges fixed-size child windows of similar size, such as a row of push buttons or a group of radio buttons. ISetCanvas divides these child windows evenly among multiple decks by number rather than by size. ISetCanvas also sizes and positions its child windows based on their minimum sizes instead of the size of the canvas. ISetCanvas uses IWindow::minimumSize and IWindow::calcMinimumSize to size the windows.

This class provides you with a number of alignment and packing options for positioning differently sized child windows.


ISetCanvas - Member Functions and Data by Group

Constructors & Destructor

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


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
ISetCanvas


Overload 1
public:
ISetCanvas( unsigned long windowIdentifier, IWindow* parent, IWindow* owner, const IRectangle& initial = IRectangle ( ), const Style& style = defaultStyle ( ) )
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 ISetCanvas::Style, ICanvas::Style, and IWindow::Style objects. Optional.

Exception

IInvalidParameter style contains an invalid combination of styles. style cannot contain more than one deck orientation style (ISetCanvas::horizontalDecks and ISetCanvas::verticalDecks), more than one pack style (ISetCanvas::packTight, ISetCanvas::packEven, and ISetCanvas::packExpanded), more than one horizontal alignment style (ISetCanvas::leftAlign, ISetCanvas::centerAlign, and ISetCanvas::rightAlign), or more than one vertical alignment style (ISetCanvas::topAlign, ISetCanvas::centerVerticalAlign, and ISetCanvas::bottomAlign).

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
protected:
ISetCanvas()

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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Processes the style values, then calls ICanvas::initialize to create an underlying system window. Call this function from a constructor of a class derived from ISetCanvas if the constructor calls the protected ISetCanvas constructor.

Exception

IInvalidParameter style contains an invalid combination of styles. style cannot contain more than one deck orientation style (ISetCanvas::horizontalDecks and ISetCanvas::verticalDecks), more than one pack style (ISetCanvas::packTight, ISetCanvas::packEven, and ISetCanvas::packExpanded), more than one horizontal alignment style (ISetCanvas::leftAlign, ISetCanvas::centerAlign, and ISetCanvas::rightAlign), or more than one vertical alignment style (ISetCanvas::topAlign, ISetCanvas::centerVerticalAlign, and ISetCanvas::bottomAlign).

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Adding and Removing Child Windows

You can explicitly add and remove child windows to and from the set whose size and position the set canvas manages. As a result, the canvas can have child windows whose size and position it does not modify.

These functions can be used to add and remove child windows to and from canvases with or without the style, ISetCanvas::explicitAddsNeeded. The style explicitAddsNeeded is used to determine which child windows are to be managed during the canvas layout. When ISetCanvas::explicitAddsNeeded is not set, all child windows, except those that have been removed or replaced, will be managed during the canvas layout. When ISetCanvas::explicitAddsNeeded is set, only child windows that have been added will be managed during the canvas layout. See function isInLayout for more details.


[view class]
add
public:
virtual ISetCanvas& add(IWindow* child)

Adds the specified child window to the set canvas, causing the canvas to manage the size and position of the window. You do not need to call this function if you did not create the canvas using the style ISetCanvas::explicitAddsNeeded.

This function also makes the child window visible. It does not change the sibling order of the child window, which determines where the set canvas positions it relative to its sibling windows.

Exception

IInvalidParameter The set canvas must be the parent window of child.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
areExplicitAddsNeeded
public:
bool areExplicitAddsNeeded() const

Returns if the canvas was created with the style ISetCanvas::explicitAddsNeeded. If true, you must call the ISetCanvas::add or ISetCanvas::replaceChildWith functions for the set canvas to manage the size and positions of its child windows.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
isInLayout
public:
virtual bool isInLayout(IWindow* child) const

Identifies if the set canvas manages the size and position of the specified child window. Otherwise you are responsible for sizing and positioning the child window.

This function returns true if either of the following is true:

This function returns false for a child window if:

Exception

IInvalidParameter The set canvas must be the parent window of child.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
remove
public:
virtual ISetCanvas& remove(IWindow* child)

Removes the specified child window from the set canvas, causing the canvas to no longer manage the size and position of the window.

To remove the child window from view and minimize the user's ability to interact with the removed window, this function also does the following:


Note: The behavior of this function is the same for canvases with and without the ISetCanvas::explicitAddsNeeded style.

Exception

IInvalidParameter The set canvas must be the parent window of child.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Portability Considerations

This function attempts to prevent the user from moving the input focus to the child window using the Tab key, arrow keys, and mnemonics, while not changing how the user can navigate between the remaining child windows using the keyboard. To fully prevent the user from accessing the child window with the arrow keys on the OS/2 and Windows operating systems, you are responsible for ensuring that the first child window in the sibling order has the group style.


[view class]
replaceChildWith
public:
virtual ISetCanvas& replaceChildWith( IWindow* existingChild, IWindow* newChild )

Replaces one child window in the set canvas with another. This function removes the existing child window from the canvas (see ISetCanvas::remove for the changes made to the child window). Before the existing window is removed, the canvas applies the following changes to the new child window:


Note: The behavior of this function is the same for canvases with and without the ISetCanvas::explicitAddsNeeded style.

Exception

IInvalidParameter The set canvas must be the parent window of existingChild and newChild.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Decks

Use these members to set and query whether child windows should be laid out horizontally in rows or vertically in columns.


[view class]
deckCount
public:
unsigned long deckCount() const

Returns the maximum number of decks used by the canvas.

You can set the maximum number of decks by calling ISetCanvas::setDeckCount. If you do not call setDeckCount, this function returns 1 and the set canvas lays out its child windows into a single deck.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
deckOrientation
public:
DeckOrientation deckOrientation() const

Returns an enumerator for deck direction. The returned value is an enumerator provided by DeckOrientation.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setDeckCount
public:
virtual ISetCanvas& setDeckCount(unsigned long decks)

Sets the maximum number of decks used by the canvas. This function has no effect if the ISetCanvas::decksByGroup style is being used.

Exception

IInvalidParameter decks must be nonzero.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setDeckOrientation
public:
virtual ISetCanvas& setDeckOrientation( DeckOrientation value )

Sets the direction of the decks.

Exception

IInvalidParameter You specified an uninitialized ISetCanvas::DeckOrientation value.

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 is managing the size and position of any child windows.

This function returns true if any of the following is true:

Otherwise it returns false.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Treats the following as changing the layout of its child windows:

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Positions and sizes child windows.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Notification Members

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


[view class]
deckOrientationId
public:
static INotificationId const deckOrientationId

Notification identifier provided to observers when the deck orientation of the set canvas changes. ISetCanvas provides the new deck orientation value in the INotificationEvent::eventData field of the INotificationEvent. This value is one of the predefined DeckOrientation enumeration values.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Spacing of Child Windows

Use these members to specify the spacing added around and between child windows.


[view class]
alignDecksByGroup
public:
ISetCanvas& alignDecksByGroup( bool alignDecksByGroup = true )

Turns the style ISetCanvas::decksByGroup on or off.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
alignment
public:
Alignment alignment() const

Returns the enumerator for deck alignment. The returned value is an enumerator provided by Alignment.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
groupPad
public:
unsigned long groupPad() const

Returns the pad width or height, which is the space before a child window in a deck with a style of IWindow::group.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
hasDecksAlignedByGroup
public:
bool hasDecksAlignedByGroup() const

Returns the current value of the ISetCanvas::decksByGroup style.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
margin
public:
ISize margin() const

Returns the margin width and height, which is the space between the edge of the canvas and the outermost child windows.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
packType
public:
PackType packType() const

Returns an enumerator for child window spacing in decks. The returned value is an enumerator provided by PackType.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
pad
public:
ISize pad() const

Returns the pad width and height, which is the space between child windows in a deck and between multiple decks.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setAlignment
public:
virtual ISetCanvas& setAlignment(Alignment value)

Sets how child windows are aligned in decks.
Note: If the canvas uses a pack type of expanded, this function has no effect.

Exception

IInvalidParameter You specified an uninitialized ISetCanvas::Alignment value.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setGroupPad
public:
virtual ISetCanvas& setGroupPad(unsigned long groupPad)

Sets the pad width or height to use for controls with a style of IWindow::group. The default value is zero.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setMargin
public:
virtual ISetCanvas& setMargin(const ISize& margin)

Sets the margin width and height, which is the space between the edge of the canvas and the outermost child windows.

Exception

IInvalidParameter The height and width of margin cannot be less than 0.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setPackType
public:
virtual ISetCanvas& setPackType(PackType value)

Sets how child windows are spaced in decks.

Exception

IInvalidParameter You specified an uninitialized ISetCanvas::PackType value.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setPad
public:
virtual ISetCanvas& setPad(const ISize& pad)

Sets the pad width and height, which is the space between child windows in a deck and between multiple decks.

Exception

IInvalidParameter The height and width of pad cannot be less than -1.

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 ISetCanvas object, you can use ISetCanvas, 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 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 set 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]
bottomAlign
public:
static const Style bottomAlign

Aligns child windows at the bottom edge of a horizontal deck or the bottom edge of a row between evenly packed vertical decks.
Note: If you use this style with both packTight and verticalDecks, it is ignored. If you use this style with packExpanded, it is ignored. You cannot specify this style with topAlign or centerVerticalAlign.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
centerAlign
public:
static const Style centerAlign

Centers child windows horizontally within a vertical deck or within a column between evenly packed horizontal decks.
Note: If you use this style with both packTight and horizontalDecks, it is ignored. If you use this style with packExpanded, it is ignored. You cannot specify this style with leftAlign or rightAlign.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
centerVerticalAlign
public:
static const Style centerVerticalAlign

Centers child windows vertically within a horizontal deck or within a row between evenly packed vertical decks.
Note: If you use this style with both packTight and verticalDecks, it is ignored. If you use this style with packExpanded, it is ignored. You cannot specify this style with topAlign or bottomAlign.

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 ISetCanvas::horizontalDecks | ISetCanvas::packTight | ISetCanvas::leftAlign | ISetCanvas::topAlign | IWindow::visible.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
decksByGroup
public:
static const Style decksByGroup

Causes the number of decks in the set canvas to be determined by the number of child windows with the group style (IWindow::isGroup returns true). Each child window with the group style starts a new deck. If you specify this style, calls to setDeckCount are ignored.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
explicitAddsNeeded
public:
static const Style explicitAddsNeeded

Specifies that the set canvas manages the size and position of a child window only if you add that child window to the canvas using the ISetCanvas::add or ISetCanvas::replaceChildWith function.

Not using this style causes the set canvas to treat all child windows as added, unless you explicitly remove a child window using ISetCanvas::remove or ISetCanvas::replaceChildWith.

Whether you use this style or not, you can remove and replace child windows, and you can add back removed child windows. See the function isInLayout for more details on when ISetCanvas manages the size and position of a child window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
horizontalDecks
public:
static const Style horizontalDecks

Organizes child windows in rows. Multiple rows are arranged from top to bottom.
Note: You cannot specify this style with ISetCanvas::verticalDecks.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
leftAlign
public:
static const Style leftAlign

Aligns child windows at the left edge of a vertical deck or the left edge of a column between evenly packed horizontal decks.
Note: If you use this style with both packTight and horizontalDecks, it is ignored. If you use this style with packExpanded, it is ignored. You cannot specify this style with rightAlign or centerAlign.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
packEven
public:
static const Style packEven

Sizes child windows to their minimum size and spaces them such that corresponding windows in each deck are aligned. This gives the child windows the appearance of being arranged in both rows and columns. As a result, child windows within a deck can be separated by more than the pad amount.
Note: If the set canvas has only one deck, this style has no effect. You cannot specify this style with packTight or packExpanded.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
packExpanded
public:
static const Style packExpanded

Sizes child windows in a way similar to that of packEven, except the child windows are enlarged rather than spaced by more than the pad amount. All smaller child windows are enlarged to the same size as the largest child window.
Note: You cannot specify this style with packTight or packEven.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
packTight
public:
static const Style packTight

Sizes child windows to their minimum size and separates them within a deck by the pad amount only.
Note: You cannot specify this style with packEven or packExpanded.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
rightAlign
public:
static const Style rightAlign

Aligns child windows at the right edge of a vertical deck or the right edge of a column between evenly packed horizontal decks.
Note: If you use this style with both packTight and horizontalDecks, it is ignored. If you use this style with packExpanded, it is ignored. You cannot specify this style with leftAlign or centerAlign.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
topAlign
public:
static const Style topAlign

Aligns child windows at the top edge of a horizontal deck or a row between evenly packed vertical decks.
Note: If you use this style with both packTight and verticalDecks, it is ignored. If you use this style with packExpanded, it is ignored. You cannot specify this style with bottomAlign or centerVerticalAlign.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
verticalDecks
public:
static const Style verticalDecks

Organizes child windows in columns. Multiple columns are arranged from left to right.
Note: You cannot specify this style with ISetCanvas::horizontalDecks.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Text

Use these members to support drawing a border and border text around the contents of the canvas.


[view class]
expandForText
protected:
virtual ISetCanvas& expandForText()

Determines how much larger the canvas must be to include a border and the current border text.

This protected function should be called from the calcMinimumSize function to account for the size of the border and border text. The layout size is adjusted by the calculated border and border text size.

Exception

IAccessError The call to determine the size required to display the text of the set canvas failed.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


ISetCanvas - Enumerations


[view class]
Alignment
enum Alignment { topLeft, 
                 topCenter, 
                 topRight, 
                 centerLeft, 
                 centerCenter, 
                 centerRight, 
                 bottomLeft, 
                 bottomCenter, 
                 bottomRight }

Use the following enumerators to specify the alignment of child windows in a deck.

topLeft
Aligns the child windows in the canvas to the top and left edge in the deck:
topCenter
Aligns the child windows in the canvas to the top edge, centered horizontally in the deck.
topRight
Aligns the child windows in the canvas to the top and right edge in the deck.
centerLeft
Aligns the child windows in the canvas to the left edge, centered vertically in the deck.
centerCenter
Aligns the child windows in the canvas to the center of the deck.
centerRight
Aligns the child windows in the canvas to the right edge, centered vertically in the deck.
bottomLeft
Aligns the child windows in the canvas to the bottom and left edge in the deck.
bottomCenter
Aligns the child windows in the canvas to the bottom edge, centered vertically in the deck.
bottomRight
Aligns the child windows in the canvas to the bottom and right edge in the deck.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
DeckOrientation
enum DeckOrientation { horizontal, 
                       vertical }

Use the following enumerators to specify the direction in which to orient the deck of child windows:

horizontal
Arranges the child windows in the canvas horizontally in rows from left to right. Decks of rows are arranged from top to bottom.
vertical
Arranges the child windows in the canvas vertically in columns from top to bottom. Decks of columns are arranged from left to right.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
PackType
enum PackType { tight, 
                even, 
                expanded }

Use these enumerators to specify the spacing between child windows in decks.

tight
Sizes the child windows to their minimum size and separates them within a deck by the pad amount only.
even
Sizes child windows to their minimum size and spaces them so that corresponding windows in each deck are aligned. This gives the appearance of their being arranged in both rows and columns. As a result, child windows within a deck can be separated by more than the pad amount. This option has no effect if the set canvas has only one deck.
expanded
Similar to the enumerator even, except the child windows are expanded, rather than spaced by more than the pad amount. Child windows are expanded to the same size as the largest child window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


ISetCanvas - 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