ISplitCanvas

The ISplitCanvas class provides a way to split a window into two or more window panes by creating and adding controls. The number of controls you add determines the number of panes in the split canvas.

You can separate the window panes using split bars (the default style). By dragging the split bars, a user can dynamically change the visible amount of each pane. The split canvas manages the position and size of its child windows, so that together with the split bars, they occupy the entire area of the canvas.

You can stack the controls vertically (the default) or horizontally.

Typically, you create a split canvas control with a frame window or another split canvas window as its parent and owner. Any window can serve this purpose. In addition, you might want to call IFrameWindow::setClient to make the split canvas control the client window of a frame window. Then you can add other controls, such as list boxes, push buttons, or even another split canvas by creating each control with the split canvas for its parent.
Note: You can make an IFrameWindow the child window of a split canvas only if it is the only child window of the canvas. However, it is better to add a multicell canvas between the split canvas and the IFrameWindow. Make the IFrameWindow the only child window of the multicell canvas by placing it in a single expandable row and column and make the multicell canvas a child window of the split canvas.

Do not change the Z-order of the child windows of a split canvas without refreshing the canvas. Doing so results in unpredictable behavior.

Controls are positioned in the window panes of a split canvas in the order you create them in, from left to right in a vertically split canvas and from top to bottom in a horizontally split canvas. Tabbing order is based on the order in which you create controls having the style IWindow::tabStop.

To specify what percentage of the split canvas a control occupies when the split canvas is initially displayed, use ISplitCanvas::setSplitWindowPercentage. The percentages you set determine the size of the window panes containing the controls, not the size of the controls themselves. Some testing might be necessary to determine the proper percentages to specify for each control to obtain the optimal initial appearance of the split canvas.
Note: If the split canvas has split bars and the user drags the split bars, the percentages you set will change. Your percentage values determine the initial appearance of the split canvas and the controls it contains. The minimum size to which a user can size a pane is the width of the split bar.

You can create a split canvas without split bars by using the style ISplitCanvas::noSplitBars. When you use this style, each pane maintains its size ratio to the other panes when users size the canvas. However, users cannot modify the percentage of the canvas occupied by a pane as they can when split bars are available.

When the sum of the controls' percentages is equal to 100, each window pane is given its requested percentage of the split canvas. However, when the sum of the controls' percentages is less than or greater than 100, the percentages are converted to ratios.

Controls that do not have a percentage are assigned a percentage by the class library proportional to the number of controls in the split canvas. For example, if your split canvas has three controls and you specify no percentages, each window pane gets one-third of the window.

If you set percentages for some or all of your controls, the window panes containing these controls are given a ratio determined by the percentages that you set. For example, suppose you have three controls, as in the preceding example, but this time you set the second control to 10 percent and the third control to 30 percent. The first pane gets one-third of the window since you did not specify a percentage. However, in this case, the second and third panes are given a ratio of 10:30 of the remaining space. The second pane gets 1/6 of the window (10/40 of the remaining space), and the third pane gets 1/2 of the window (30/40 of the remaining space).

If a user changes the size of a split canvas, its window panes are sized to fill the split canvas by default. Each pane maintains its size ratio to the other panes in the canvas when this occurs.

AIX Considerations

Motif does not support the enumeration SplitBarEdge. The value of the edge is always zero. The enumerator splitBarMiddle specifies the thickness of the split bar.


ISplitCanvas - Member Functions and Data by Group

Constructors & Destructor

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


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
ISplitCanvas
public:
ISplitCanvas( unsigned long windowIdentifier, IWindow* parent, IWindow* owner, const IRectangle& initialSize = 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.
initialSize
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 ISplitCanvas::Style, ICanvas::Style, and IWindow::Style objects. Optional.

Exception

IInvalidParameter style contains an invalid combination of styles. style cannot contain both the ISplitCanvas::horizontal and ISplitCanvas::vertical styles.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Child Window Sizing

Use these members to control the size of the child windows of the split canvas through percentages (ratios).


[view class]
setSplitWindowPercentage
public:
virtual ISplitCanvas& setSplitWindowPercentage( IWindow* window, unsigned long percentage )

Sets the percentage of the canvas occupied by the specified window.
Note: If the split canvas is already shown, this function does not update it immediately. You must call IWindow::refresh to update the appearance of the canvas.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
splitWindowPercentage
public:
unsigned long splitWindowPercentage(IWindow* window)

Returns the percentage of the width or height of the canvas currently occupied by the specified window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Colors

Use these members to set and query the color of the middle or edge of a split bar.


[view class]
resetSplitBarEdgeColor
public:
virtual ISplitCanvas& resetSplitBarEdgeColor()

Resets the color of the edges of the canvas' split bars, so the default edge color is used.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored


[view class]
resetSplitBarMiddleColor
public:
virtual ISplitCanvas& resetSplitBarMiddleColor()

Resets the color of the interior of the canvas' split bars, so that the default color is used.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored


[view class]
setSplitBarEdgeColor
public:
virtual ISplitCanvas& setSplitBarEdgeColor( const IColor& color )

Sets the color for the edges of the canvas' split bars.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored


[view class]
setSplitBarMiddleColor
public:
virtual ISplitCanvas& setSplitBarMiddleColor( const IColor& color )

Sets the color for the interior of the canvas' split bars.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Returns the color of the edges of the canvas' split bars.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored


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

Returns the color of the interior of the canvas' split bars.

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]
setLayoutDistorted
public:
virtual ISplitCanvas& setLayoutDistorted( unsigned long layoutAttributesOn, unsigned long layoutAttributesOff )

Treats the following as changes to the layout of its child windows:

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Computes the position and size of all child controls.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Notification Members

These members allow observers to process changes to the window.


[view class]
orientationId
public:
static INotificationId const orientationId

Notification identifier provided to observers when the orientation of the split canvas changes. ISplitCanvas provides the new split canvas orientation value in the INotificationEvent::eventData field of the INotificationEvent. as an Orientation enumeration.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Orientation

These members control the orientation of the canvas' split bars.


[view class]
orientation
public:
Orientation orientation() const

Returns an enumerator Orientation for the orientation of the canvas' split bars.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setOrientation
public:
virtual ISplitCanvas& setOrientation(Orientation value)

Sets the direction in which the canvas' split bars are drawn.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Split Bar Thickness

Use these members to customize the thickness of the split bar.


[view class]
setSplitBarThickness
public:
virtual ISplitCanvas& setSplitBarThickness( SplitBarArea area, unsigned long thickness )

Sets the thickness of the specified area of the split bar.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
splitBarThickness
public:
unsigned long splitBarThickness(SplitBarArea area)

Returns the thickness of the specified area of the split bar.

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 ISplitCanvas object, you can use ISplitCanvas, 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 split 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 ISplitCanvas::vertical | IWindow::visible.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
horizontal
public:
static const Style horizontal

Draws split bars horizontally, placing the panes top to bottom.
Note: You cannot specify this style with ISplitCanvas::vertical.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
noSplitBars
public:
static const Style noSplitBars

Specifies no split bars are used to separate panes.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
vertical
public:
static const Style vertical

Draws split bars vertically, placing the panes left to right. This style is the default.
Note: You cannot specify this style with ISplitCanvas::horizontal.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


ISplitCanvas - Enumerations


[view class]
Orientation
enum Orientation { horizontalSplit, 
                   verticalSplit }

Use these enumerators to specify the direction of the canvas's split bars:

horizontalSplit
Draws split bars horizontally, placing the panes top to bottom.
verticalSplit
Draws split bars vertically, placing the panes left to right.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
SplitBarArea
enum SplitBarArea { splitBarEdge, 
                    splitBarMiddle }

Use these enumerators to specify different areas of a split bar:

splitBarEdge
Specifies the top and bottom edges of a horizontal split bar or the left and right edges of a vertical split bar.
splitBarMiddle
Specifies the interior of a split bar.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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