IViewPort

The IViewPort class provides scrolling support for another window. The window being scrolled is termed the view window. Typically, the view window does not readily support resizing. Because of this, you must support scrolling so users can scroll the view window to see clipped information.

View window candidates include the following classes:


Note: If you are using an IMultiCellCanvas with expandable rows or columns as the view window, specify the IViewPort::expandableViewWindow style when you construct the view port.

You specify the view window by making it a child window of the view port. A view port supports multiple view windows. Only one view window is visible in the view rectangle at a time. Hidden view windows can be made visible in the view rectangle using IViewPort::setViewWindow. As a hidden view window is made visible, the prior view window is always hidden.

The IViewPort object optionally includes horizontal and vertical scroll bars. You can specify scroll bars that are the following:

Logical sizes specified through IViewPort::setViewWindowSize are limited to 0x3FFF0000. If you do not call setViewWindowSize, the size of a view window is limited to 32 K. If the view window has no size and does not use a logical size, IViewPort sizes the view window to its minimum size. If you use the IViewPort::expandableViewWindow style and no logical size, IViewPort can grow the view window larger than its minimum size.

Portability Considerations

In AIX the Open Class Library does not support the style combination of one scroll bar displayed as needed and the other scroll bar always displayed. If this combination of styles is used, both scroll bars are always displayed. Motif supports all other combinations for displaying the view port scroll bars.
Note: Previous versions of this class created each scroll bar with a 1-based range. The scroll bar ranges are now 0-based so that the interface is consistent with IViewPort::scrollViewHorizontallyTo and IViewPort::scrollViewVerticallyTo.

AIX Considerations

By default the last child window of the view port will be the view window displayed in the view rectangle. Any child window of the view port can be designated the view window using IViewPort::setViewWindow.

Use the view port protected function handleForChildCreation to get the window handle of the parent to use for creating a view window.

When the view port contains scroll bars, the underlying widgets manage the size of the scroll bars' scroll boxes, and updates their positions as your view window is scrolled.

OS/2 Considerations

By default the first child window of the view port will be the view window displayed in the view rectangle. Any child window of the view port can be designated the view window using IViewPort::setViewWindow.

The view port changes the parent window of the view window to a scrollable rectangular window to properly clip the child window. The window identifier (ID) of the scrollable rectangular window is IC_VIEWPORT_VIEWRECTANGLE. If you enable the view window for direct manipulation, the direct manipulation events are dispatched to the scrollable rectangular window.

When the view port contains scroll bars, the view port manages the size of the scroll bars' scroll boxes, and updates their positions as it scrolls your view window.

Windows Considerations

By default the first child window of the view port will be the view window displayed in the view rectangle. Any child window of the view port can be designated the view window using IViewPort::setViewWindow.

The view port changes the parent window of the view window to a scrollable rectangular window to properly clip the child window. The window identifier (ID) of the scrollable rectangular window is IC_VIEWPORT_VIEWRECTANGLE. If you enable the view window for direct manipulation, the direct manipulation events are dispatched to the scrollable rectangular window.

When the view port contains scroll bars, the view port manages the size of the scroll bars' scroll boxes, and updates their positions as it scrolls your view window.


IViewPort - Member Functions and Data by Group

Constructors & Destructor

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


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
IViewPort
public:
IViewPort( unsigned long windowIdentifier, IWindow* parent, IWindow* owner, const IRectangle& initialSize = IRectangle ( ), const Style& style = defaultStyle ( ) )
windowIdentifier
The window identifier of the view port 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).

The OS/2 and Windows versions of the IViewPort class reserve the following window identifiers for child windows that it creates:

IC_VIEWPORT_VERTSCROLLBAR
Vertical scroll bar.
IC_VIEWPORT_HORZSCROLLBAR
Horizontal scroll bar.
IC_VIEWPORT_VIEWRECTANGLE
Scroll rectangle window. The window within which the application window is scrolled. IViewPort changes the parent of the view window to this window.
parent
The parent window of the view port you are constructing. You must specify a parent window. The parent window is primarily used for visible relationships.
owner
The owner window of the view port 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 view port you are constructing. The position is relative to the origin of the parent window. See ICoordinateSystem for additional information. Optional.
style
The view port's characteristics. This value can be a combination of IViewPort::Style, ICanvas::Style, and IWindow::Style objects. Optional.

Exception

IInvalidParameter style contains an invalid combination of styles. style cannot contain more than one horizontal scroll bar style (IViewPort::alwaysHorizontalScrollBar, IViewPort::asNeededHorizontalScrollBar, and IViewPort::noHorizontalScrollBar), or more than one vertical scroll bar style (IViewPort::alwaysVerticalScrollBar, IViewPort::asNeededVerticalScrollBar, and IViewPort::noVerticalScrollBar).

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Child Creation

Override these functions to provide information necessary for creating child windows.


[view class]
handleForChildCreation
protected:
virtual IWindowHandle handleForChildCreation() const

Returns the handle that should be used when creating children of the IViewPort.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Child Scroll Bars

Use these members to access the scroll bar windows created by the IViewPort window.


[view class]
horizontalScrollBar
public:
IScrollBar* horizontalScrollBar() const

Returns the address of the horizontal scroll bar.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
verticalScrollBar
public:
IScrollBar* verticalScrollBar() const

Returns the address of the vertical scroll bar.

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 view port is managing the scrolling (or sizing and positioning) of any child windows.

This version 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 IViewPort& setLayoutDistorted( unsigned long layoutAttributeOn, unsigned long layoutAttributeOff )

Processes a size change as a layout change.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Returns the recommended minimum size for this IViewPort object. The size is based on the minimum size of the vertical and horizontal scroll bars.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Positions the scroll bars, scroll rectangle window, and view window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Notification Members

These members allow observers to process changes to the window.


[view class]
viewWindowSizeId
public:
static INotificationId const viewWindowSizeId

Notification identifier provided to observers when the logical size of the view port's view window changes. IViewPort provides a pointer to an ISize object for the new size in the eventData field of the INotificationEvent.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Styles

Use these 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 IViewPort object, you can use IViewPort, 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 change 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 view ports.

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]
alwaysHorizontalScrollBar
public:
static const Style alwaysHorizontalScrollBar

Specifies that the view port never removes the horizontal scroll bar.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
alwaysVerticalScrollBar
public:
static const Style alwaysVerticalScrollBar

Specifies that the view port never removes the vertical scroll bar.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
asNeededHorizontalScrollBar
public:
static const Style asNeededHorizontalScrollBar

Specifies that the view port removes the horizontal scroll bar when the entire width of the view window is visible and there is no data to scroll horizontally.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
asNeededVerticalScrollBar
public:
static const Style asNeededVerticalScrollBar

Specifies that the view port removes the vertical scroll bar when the entire height of the view window is visible and there is no data to scroll vertically.

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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
expandableViewWindow
public:
static const Style expandableViewWindow

Specifies that the view port will size its view window to completely fill the view port by sizing the view window to the larger of the following:

When the view port sizes the view window to its minimum size, it allows the user to scroll the view window if it is not completely visible.

Use this style when using an IMultiCellCanvas with expandable rows or columns as the view window.
Note: Setting a logical view window size through the function IViewPort::setViewWindowSize causes this style to be ignored.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
noHorizontalScrollBar
public:
static const Style noHorizontalScrollBar

Specifies that the view port never shows the horizontal scroll bar.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
noVerticalScrollBar
public:
static const Style noVerticalScrollBar

Specifies that the view port never shows the vertical scroll bar.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
noViewWindowFill
public:
static const Style noViewWindowFill

Specifies that the view port does not paint the portion of the view rectangle occupied by the view window.
Note: If you know that the view window paints its entire rectangle, specify this style to optimize overall painting.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


View Window

Use these members to change the appearance of the view window in the view port.


[view class]
scrollViewHorizontallyTo
public:
virtual IViewPort& scrollViewHorizontallyTo( unsigned long leftOffset )

Scrolls the view window horizontally. The value you specify is the offset in pels from the left edge of the view window to the point you want to see at the left edge of the view rectangle. Specify the value 0 to line up the left edge of the view window with the left edge of the view rectangle.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
scrollViewVerticallyTo
public:
virtual IViewPort& scrollViewVerticallyTo( unsigned long topOffset )

Scrolls the view window vertically. The value you specify is the offset in pels from the top edge of the view window to the point you want to see at the top edge of the view rectangle. Specify the value 0 to line up the top edge of the view window with the top edge of the view rectangle.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setViewWindow
public:
virtual IViewPort& setViewWindow( const IWindowHandle& viewWindow )

Changes the view window that displays in the view rectangle. The specified view window must be a child window of the view port. The prior view window is hidden.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setViewWindowSize
public:
virtual IViewPort& setViewWindowSize(const ISize& size)

Changes the logical size of the window being scrolled. The logical size does not have to match the real size of the window.

If you call this function, you will manage the appearance of the view window. IViewPort processes the position and size of the scroll boxes of its scroll bars, but you are responsible for changing the position or repainting the view window to give the appearance of scrolling.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
viewWindow
public:
virtual IWindowHandle viewWindow()

Returns the handle of the window bounded by the view port.

Exception

IInvalidRequest The view port has found more than one view window. A view port can have only one child window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

Use the view port protected function handleForChildCreation to get the window handle of the parent to use for creating a view window.

OS/2 Considerations

The parent of the view window is changed to the scrollable rectangular window so that the view window is properly clipped.

Windows Considerations

The parent of the view window is changed to the scrollable rectangular window so that the view window is properly clipped.


[view class]
viewWindowDrawRectangle
public:
virtual IRectangle viewWindowDrawRectangle() const

Returns the area of the view window that is currently visible in the view port.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
viewWindowSize
public:
virtual ISize viewWindowSize() const

Returns the logical size of the window being scrolled. If you have not called IViewPort::setViewWindowSize to set a logical size, the real size of the view window is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
positionViewWindow
protected:
virtual IViewPort& positionViewWindow( const IWindowHandle& viewWindow, const IRectangle& viewRectangle )

Positions the view window within the view rectangle.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setTopLeftViewPoint
protected:
virtual IViewPort& setTopLeftViewPoint( const IPoint& topLeft )

Sets the view window coordinate, in origin lower-left coordinates, that displays in the upper-left corner of the view rectangle.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setupScrollBars
protected:
virtual IViewPort& setupScrollBars()

Sizes, shows, or hides scroll bars for the view port window, as appropriate. This function also positions and sizes the scroll rectangle window that bounds the view window. IViewPort calls this function before calling positionViewWindow.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
topLeftViewPoint
protected:
IPoint topLeftViewPoint() const

Returns the view window coordinate that displays in the upper-left corner of the view rectangle in origin lower-left coordinates.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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