IScrollBar

The IScrollBar class creates and manages scroll bar control windows.

OS/2 Considerations

The size limitation for a scroll bar is 32768.


IScrollBar - Member Functions and Data by Group

Constructors & Destructor

You can construct and destruct objects of this class.


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
IScrollBar


Overload 1
public:
IScrollBar(const IWindowHandle& handle)

Use this function to construct objects of this class using the handle of an existing scroll bar control.

handle
The window handle of an existing scroll bar control.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IScrollBar( unsigned long id, IWindow* parent, IWindow* owner, const IRange& scrollableItems, unsigned long visibleItemCount, unsigned long scrollBoxPosition = 1, const IRectangle& initial = IRectangle ( ), const Style& style = defaultStyle ( ) )

Use this function to construct objects of this class using the parent window, owner window, number of scrollable items, number of items displayed, initial position of the scroll box, optional size and location, and optional style parameters.

windowId
The scroll bar control ID.
parent
The parent window.
owner
The owner window.
scrollableItems
The range of all scrollable items.
visibleItemCount
The number of items to display.
scrollBoxPosition
The initial position of the scroll box within the scroll bar. The default is 1. Optional.
initial
A rectangle for the scroll box control. It specifies the initial position and size of the scroll box you construct. Optional.
style
The initial style for the control. The default is classDefaultStyle. Optional.

Exception

IInvalidParameter The parent window pointer specified was invalid. You must specify a valid IWindow pointer as the parent.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

OS/2 Considerations

The minimum range you can set is 0 and the maximum is 32767.


Overload 3
public:
IScrollBar(unsigned long id, IWindow* parent)

Use this function to construct objects of this class using the parent window.

windowId
The scroll bar control ID.
parent
The parent window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
public:
IScrollBar( unsigned long id, IWindow* parent, IWindow* owner, const IRectangle& initial = IRectangle ( ), const Style& style = defaultStyle ( ) )

Use this function to construct objects of this class using the parent window, owner window, optional size and location, and optional style parameters.

The characteristics of the scroll box from this constructor default to the following:

Range of items
100
Visible items
25
Position
1
windowId
The scroll bar control ID.
parent
The parent window.
owner
The owner window.
initial
A rectangle for the scroll box control. It specifies the initial position and size of the scroll box you construct. Optional.
style
The initial style for the control. The default is classDefaultStyle. Optional.

Exception

IInvalidParameter The parent window pointer specified was invalid. You must specify a valid IWindow pointer as the parent.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Colors

Use these members to query, set, and reset the colors of the scroll bar.


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

Returns the color of the shaft area.

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]
hiliteForegroundColor
public:
virtual IColor hiliteForegroundColor() const

Returns the color of the scroll box area.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Portability Considerations

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

Windows Considerations

Returns the default color of the scroll box area.


[view class]
resetForegroundColor
public:
virtual IScrollBar& resetForegroundColor()

Resets the color of the shaft area.

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]
resetHiliteForegroundColor
public:
virtual IScrollBar& resetHiliteForegroundColor()

Resets the color of the scroll box color area.

Supported Platforms

Windows OS/2 AIX
No Yes Yes

Portability Considerations

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


[view class]
setForegroundColor
public:
virtual IScrollBar& setForegroundColor(const IColor& color)

Sets the color of the shaft area.

color
Color object used to set the shaft area.

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]
setHiliteForegroundColor
public:
virtual IScrollBar& setHiliteForegroundColor( const IColor& color )

Sets the color of the scroll box area.

color
Color object used to set the scroll box area.

Supported Platforms

Windows OS/2 AIX
No Yes Yes

Portability Considerations

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


[view class]
setColor
protected:
virtual IScrollBar& setColor( unsigned long colorArea, const IColor& color )

Sets the colorArea to the indicated color.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Event-Handling Implementation

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


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

Determines whether this event can be passed on to the owner of this control.

Supported Platforms

Windows OS/2 AIX
Yes No Yes


Layout Support

Layout support members supply information used by the canvas classes to provide dialog-like behavior.


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

Returns the recommended minimum size of this scroll bar control.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Manipulation Operations

Use these members to change and query how the scroll bar operates.


[view class]
moveScrollBoxTo
public:
virtual IScrollBar& moveScrollBoxTo( unsigned long firstItem = 1 )

Moves the scroll box to the specified position.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
scrollableRange
public:
virtual IRange scrollableRange() const

Returns the range that the scroll bar represents.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
scrollBoxPosition
public:
virtual unsigned long scrollBoxPosition() const

Returns the current position of the scroll box.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
scrollBoxRange
public:
virtual IRange scrollBoxRange() const

Returns the range in which the scroll box can be positioned.

See class IRange for more information.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

In this environment, the scroll box (thumb) size is variable. The range returned by this function is adjusted to account for the scroll box size. This is done by subtracting the visible count (scroll box size) from the scrollable range.


[view class]
setScrollableRange
public:
virtual IScrollBar& setScrollableRange( const IRange& minMax )

Sets the range of all items the scroll bar can scroll to.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

OS/2 Considerations

The minimum range you can set is 0 and the maximum is 32767.


[view class]
setScrollBar
public:
virtual IScrollBar& setScrollBar( const IRange& scrollableRange, unsigned long visibleCount )

Sets the range of all items and the number of items that are displayed. This is functionally equivalent to calling both setScrollableRange and setVisibleCount.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

OS/2 Considerations

The minimum range you can set is 0 and the maximum is 32767.


[view class]
setVisibleCount
public:
virtual IScrollBar& setVisibleCount( unsigned long scrollableRangeUnits )

Defines the amount of the scrollable range that is displayed. Use this to determine the length of the scroll box and the default value of the page-scrolling increment.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
visibleCount
public:
virtual unsigned long visibleCount() const

Returns the amount of the scrollable range that is displayed. Use this to determine the length of the scroll box and the default value of the page-scrolling increment.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Notification Members

Use these members to identify and enable notifications sent to observer objects.


[view class]
enableNotification
public:
virtual IScrollBar& enableNotification(bool enable = true)

Enables the scroll bar control to send notifications to any observer objects.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
scrollBoxChangeId
public:
static INotificationId const scrollBoxChangeId

Notification identifier provided to observers when the scroll box of an IScrollBar window is moved to a new location. IScrollBar provides the new scroll box position in the INotificationEvent::eventData field of the INotificationEvent.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
scrollBoxTrackId
public:
static INotificationId const scrollBoxTrackId
p. Notification identifier provided to observers when the scroll box of an IScrollBar window is dragged with the mouse. IScrollBar provides the current scroll box position in the INotificationEvent::eventData field of the INotificationEvent.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Orientation

Use these members to query the orientation of the scroll bar.


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

If the scroll bar is horizontal, true is returned. Otherwise, false is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

If the scroll bar is vertical, true is returned. Otherwise, false is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Scroll Event Implementation

Scroll event implementation members perform processing needed to support IScrollEvent objects. IScrollEvent needs the previous position of the scroll bar to calculate how far the scroll bar has moved. In the AIX environment, this information is saved in and retrieved from the IScrollBar object.


[view class]
prevScrollBoxPosition
public:
virtual unsigned long prevScrollBoxPosition() const

Returns the previous position of the scroll box.

Supported Platforms

Windows OS/2 AIX
No No Yes

AIX Considerations

This function is intended for use by Open Class Library. The application developer should never have to call this function.


[view class]
setPrevScrollBoxPosition
public:
virtual IScrollBar& setPrevScrollBoxPosition( unsigned long value )

Sets the value of the previous scroll box position.

value
Number representing the control's previous position.

Supported Platforms

Windows OS/2 AIX
No No Yes

AIX Considerations

This function is intended for use by Open Class Library. The application developer should never have to call this function.


Scrolling Increment

Use these members to query and set the scrolling increments for the scroll bar. These values determine the scroll amounts stored in IScrollEvent objects.


[view class]
minScrollIncrement
public:
virtual unsigned long minScrollIncrement() const

Returns the amount of the scrollable range that is scrolled by selecting the scroll buttons.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
pageScrollIncrement
public:
virtual unsigned long pageScrollIncrement() const

Returns the amount of the scrollable range that is scrolled by selecting the scroll shaft.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setMinScrollIncrement
public:
virtual IScrollBar& setMinScrollIncrement( unsigned long scrollableRangeUnits = 1 )

Sets the amount of the scrollable range that is scrolled by selecting the scroll buttons.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setPageScrollIncrement
public:
virtual IScrollBar& setPageScrollIncrement( unsigned long scrollableRangeUnits = 0 )

Sets the amount that a page scrolls when a user selects the scroll shaft.

scrollableRangeUnits
The default is 0. Using this default sets the default page-scrolling increment to visible count minus the minimum scroll increment.

For example, if a window contains 20 lines of text, the visible count is 20. If the minimum scroll increment is one line, the default page scroll increment is 19 (20-1).

If the visible count and the minimum scroll increment are the same, this function uses the minimum scroll increment. Otherwise, the page does not scroll.

For example, if the visible count is 20 and the minimum scrolling increment is 20, the preceding formula sets the default page-scrolling increment to 0, which prevents the page from scrolling. The Open Class Library avoids this possibility by setting the default page-scrolling increment to the minimum scroll increment in these situations.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Styles

These style members provide a set of valid styles for this class. Use these members to query and set the scroll bar styles. You can use these styles with the styles in IWindow 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 presentation 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 scroll bars.

style
Use the styles provided by IScrollBar Styles to specify the default style.

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

Provides the original default style for this class, which is the following: IScrollBar::vertical | IWindow::visible.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
horizontal
public:
static const Style horizontal

Causes a horizontal scroll bar to be created. This style is ignored if it is used with vertical.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
vertical
public:
static const Style vertical

Causes a vertical scroll bar to be created. This style is used if both it and horizontal are specified.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


System Values

These static members return various system sizes. For these members, "length" refers to the size in the direction of a scroll bar's orientation (that is, in the X-direction for a horizontal scroll bar and in the Y-direction for a vertical scroll bar). "Width" refers to the size in the direction perpendicular to the scroll bar's orientation (that is, in the Y-direction for a horizontal scroll bar and in the X-direction for a vertical scroll bar).


[view class]
systemScrollBarWidth
public:
static unsigned long systemScrollBarWidth( bool verticalScrollBar = true )

Returns the system width of a vertical or horizontal scroll bar.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
systemScrollBoxLength
public:
static unsigned long systemScrollBoxLength( bool verticalScrollBar = true )

Returns the system length of a scroll box for a vertical or horizontal scroll bar.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
systemScrollButtonLength
public:
static unsigned long systemScrollButtonLength( bool verticalScrollBar = true )

Returns the system length of a scroll button for a vertical or horizontal scroll bar.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Window Painting

Use this member to determine the visiblility of a scroll bar window.


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

If the scroll bar is to be displayed, whether currently obscured or unobscured, true is returned. Otherwise, false is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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