IProgressIndicator

The IProgressIndicator class is a read-only version of the slider control. ISlider describes the slider control.

Handlers derived from the following classes handle events for IProgressIndicator objects:

Typically, a progress indicator with the following components displays the percentage of a task completed by filling in the indicator shaft as the task progresses.


1 - Slider shaft
A track for the slider arm to move along.
2 - Tick mark
A mark that indicates an incremental value in the slider's scale.
3 - Tick text
A label that indicates the value of the tick mark.
4 - Slider arm
The slider arm shows the level of progress by its position on the slider shaft. The user cannot move the arm of the progress indicator. The arm is barely visible. You can only change the slider arm's position through your code.

If the ribbonStrip style is enabled, the progress indicator's shaft fills with color as the arm is moved.

By default, the Open Class Library creates a horizontal progress indicator and centers it in the window with its ticks and text above it. The arm starts from the left edge and the shaft fills with color as the arm moves to the right. You can also construct a progress indicator with the following characteristics:

Portability Considerations

There are restrictions for specifying the color of controls based on the platform and which style of control you use.

Windows Considerations

Native progress indicators (that is, progress indicators constructed without the pmCompatible style) do not display a visible slider arm. You must use the ribbonStrip style to indicate the arm position for native progress indicators.


IProgressIndicator - Member Functions and Data by Group

Constructors & Destructor

You can construct and destruct objects of this class.

In addition, the Open Class Library provides a protected constructor used by the ISlider class during construction.


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
IProgressIndicator


Overload 1
public:
IProgressIndicator(const IWindowHandle& handle)

You can construct objects of this class by specifying a window handle.

handle
The window handle of the progress indicator control.

Supported Platforms

Windows OS/2 AIX
Yes Yes No

AIX Considerations

The constructors wrapping an existing progress indicator are not available in the AIX environment.

Windows Considerations

You can use this constructor to wrapper a native Windows trackbar. Open Class Library does not check whether the control being wrappered is read-only. The trackbar being wrappered should have the TBS_NOTHUMB style in order to ensure that the object constructed will wrapper a read-only control.

IProgressIndicator objects constructed from native Windows trackbars will set the initial number of ticks to two and the tick spacing to zero. Call setTicks after wrappering the control to initialize the scale(s).


Overload 2
public:
IProgressIndicator( unsigned long windowId, IWindow* parent, IWindow* owner, const IRectangle& initial, unsigned long scale1NumberOfTicks, unsigned long scale1TickSpacing, unsigned long scale2NumberOfTicks, unsigned long scale2TickSpacing = 0, const Style& style = defaultStyle ( ) )

You can construct objects of this class by specifying the number of ticks and spacing for both scale 1 and scale 2.
Note: Various repaint problems can occur when the progress indicator control is resized using IWindow::sizeTo or IWindow::moveSizeTo. The problems occur when the width of the window is less than the width of the entire progress indicator. This might happen when you attempt to show the control with a nonzero rectangle that is too small for the tick spacing you specified. If you use the default tick spacing, the progress indicator is able to resize itself for the new rectangle's size.

windowId
A unique ID for the progress indicator control.
parent
The parent window.
owner
The owner window.
initial
A rectangle for the progress indicator control. It specifies the initial position and size of the progress indicator you are constructing. The default is the rectangle constructed by the default IRectangle constructor.
Note: When using pmCompatible style, initial must be at least 10 pixels in breadth.

scale1NumberOfTicks
The number of ticks to place on scale 1 of the progress indicator.
scale1TickSpacing
The number of pixels between ticks on scale 1.
scale2NumberOfTicks
The number of ticks to place on scale 2 of the progress indicator.
scale2TickSpacing
The number of pixels between ticks on scale 2. Optional.
style
The style of the control. 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


Overload 3
public:
IProgressIndicator(unsigned long windowId, IWindow* parent)

You can construct objects of this class by specifying a parent window and the ID of a progress indicator control.

windowId
A unique ID for the progress indicator control.
parent
The parent window.

Supported Platforms

Windows OS/2 AIX
Yes Yes No

Windows Considerations

You can use this constructor to wrapper a native Windows trackbar. Open Class Library does not check whether the control being wrappered is read-only. The trackbar being wrappered should have the TBS_NOTHUMB style in order to ensure that the object constructed will wrapper a read-only control.

IProgressIndicator objects constructed from native Windows trackbars will set the initial number of ticks to two and the tick spacing to zero. Call setTicks after wrappering the control to initialize the scale(s).


Overload 4
public:
IProgressIndicator( unsigned long windowId, IWindow* parent, IWindow* owner, const IRectangle& initial, unsigned long numberOfTicks, unsigned long tickSpacing = 0, const Style& style = defaultStyle ( ) )

You can construct objects of this class by using this primary constructor.

windowId
A unique ID for the progress indicator control.
parent
The parent window.
owner
The owner window.
initial
A rectangle for the progress indicator control. It specifies the initial position and size of the progress indicator you are constructing. The default is the rectangle constructed by the default IRectangle constructor.
Note: When using pmCompatible style, initial must be at least 10 pixels in breadth.

numberOfTicks
The number of ticks to place on the primary scale of the progress indicator.
tickSpacing
The number of pixels between ticks. The default is 0. The default causes the progress indicator to evenly space the ticks on the shaft. Otherwise, the length of the slider shaft is based on the tickSpacing and the numberOfTicks you specify. Optional.

The tick spacing can also be changed dynamically by using the setTicks member function.

style
The style of the control. 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


Overload 5
protected:
IProgressIndicator()

Used by derived classes to construct objects of this class. This is the default constructor and accepts no parameters.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Alignment

Use these members to query the alignment of the progress indicator object. The alignment can only be set in the constructor of the progress indicator object.


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

Returns the current alignment of this progress indicator object. The returned value is an enumerator provided by Alignment.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

If the progress indicator is oriented vertically, true is returned. If it is oriented horizontally, false is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Arm Operations

Use these members to set and query attributes of the progress indicator arm.


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

Returns the offset, in pixels, of the arm from the home position.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Returns the number of pixels over which the arm can move.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Returns the position of the arm as a tick number. Ticks are numbered starting at 0.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
moveArmToPixel
public:
virtual IProgressIndicator& moveArmToPixel( unsigned long armOffset )

Moves the arm to a pixel offset relative to the home position.

armOffset
Number of pixels to offset the arm.

Exception

IInvalidParameter The arm offset is invalid.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
moveArmToTick
public:
virtual IProgressIndicator& moveArmToTick( unsigned long tickNumber )

Moves the arm to a specified tick relative to the home position. Ticks are numbered starting at 0.

If the progress indicator window has no size and you specified tick spacing on the constructor, using this function can cause an exception.

tickNumber
Number of ticks to offset the arm.

Exception

IInvalidParameter The tick index is invalid.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Colors

Use these members to query, set, and reset the colors of the progress indicator.


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

Returns the background color value of the progress indicator area. If you have not set the color for the area, the default color is returned.

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

Returns the foreground color value of the progress indicator area. If you have not set the color for the area, the default color is returned.

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

Sets the background color to the specified color.

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

Sets the color for the ticks and label text to the specified color.

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

Sets only the color for label text for native Windows progress indicators (that is, progress indicators constructed without the pmCompatible style).


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

Sets the colorArea to the indicated color.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Drawing

Use these members to query and change the handleDrawItem style of the progress indicator object. The handleDrawItem style specifies that events will be created during progress indicator drawing. You can process these events to implement your own drawing by deriving a handler from ISliderDrawHandler and attaching your handler to the progress indicator object.


[view class]
disableDrawItem
public:
virtual IProgressIndicator& disableDrawItem()

Sets the handleDrawItem style to off.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

AIX Considerations

The AIX release does not support the handleDrawItem style. Therefore, this member function has no effect in AIX.

Windows Considerations

Native Windows progress indicators (that is, progress indicators constructed without the pmCompatible style) do not support the handleDrawItem style. Therefore, this member function will have no effect for native progress indicators.


[view class]
enableDrawItem
public:
virtual IProgressIndicator& enableDrawItem( bool enableDrawItem = true )

Enables or disables the handleDrawItem style for the progress indicator.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

AIX Considerations

The AIX release does not support the handleDrawItem style. Therefore, this member function has no effect in AIX.

Windows Considerations

Native Windows progress indicators (that is, progress indicators constructed without the pmCompatible style) do not support the handleDrawItem style. Therefore, this member function will have no effect for native progress indicators.


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

If the handleDrawItem style is set, true is returned. Otherwise, false is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

The AIX release does not support the handleDrawItem style. Therefore, this member function has no effect in AIX.

Windows Considerations

Native Windows progress indicators (that is, progress indicators constructed without the pmCompatible style) do not support the handleDrawItem style. Therefore, this member function will always return false for native progress indicators.


Home Position

Use these members to query and modify the home position of the progress indicator object. The home position specifies from which side the progress indicator's tick marks are indexed. The home position is also used to indicate from which side of the progress indicator a ribbon strip, if specified, is attached.


[view class]
homePosition
public:
HomePosition homePosition() const

Returns the current home position for this progress indicator object. The returned value is an enumerator provided by HomePosition.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setHomePosition
public:
virtual IProgressIndicator& setHomePosition( HomePosition home = homeBottomLeft )

Sets the home position of the progress indicator.

home
Enumerator value for the home position. Use the enumeration HomePosition to specify the home position.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Implementation

These members provide utilities used to implement this class.


[view class]
initialize

Several of the IProgressIndicator and ISlider constructors use one of the overloads of this function to create or wrapper the control.


Overload 1
protected:
void initialize(IWindowHandle handle)

Wrappers a Windows trackbar control.

handle
A trackbar window handle.

Supported Platforms

Windows OS/2 AIX
Yes No No


Overload 2
protected:
void initialize( unsigned long windowId, IWindowHandle parent, IWindowHandle owner, unsigned long style, const IRectangle& initial, void* sliderData )

Creates a progress indicator or slider control.

windowId
A unique ID for the progress indicator control.
parent
The parent window.
owner
The owner window.
style
Specifies the progress indicator or slider style.
initial
A rectangle defining the size and placement of the control window.
sliderData
Specifies the number of ticks and tick spacing for each scale.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Layout Support

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


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

Indicates that changes have occurred in the window causing the layout of the window in a canvas to be updated.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

Returns an ISize indicating the minimum size of the progress indicator. ICanvas and its derived classes use this function.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Notification Members

Use these members to identify notifications sent to observer objects.


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

Enables the progress indicator to send notifications to any observer objects.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
armChangeId
public:
static INotificationId const armChangeId

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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
scaleId
public:
static INotificationId const scaleId

Notification identifier provided to observers when the scale style of an IProgressIndicator window changes. IProgressIndicator provides the new scale value in the INotificationEvent::eventData field of the INotificationEvent. This value is one of the predefined Scale enum values.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Primary Scale

Use these members to query and modify the primary scale of the progress indicator object. The primary scale specifies from which scale the progress indicator is positioned.

Windows Considerations

The native Windows progress indicator (that is, a progress indicator constructed without the pmCompatible style) supports two scales; however, only the primary scale is visible.


[view class]
primaryScale
public:
Scale primaryScale() const

Returns the current primary scale of this progress indicator object. The returned value is an enumerator provided by Scale.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setPrimaryScale
public:
virtual IProgressIndicator& setPrimaryScale( Scale primaryScale = scale1 )

Sets the primary scale of the progress indicator.

primaryScale
Use the enumeration Scale to specify which scale to set.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Ribbon Strip

Use these members to query and change the ribbonStrip style of the progress indicator object. The ribbonStrip style specifies that the progress indicator's shaft fills with color between the arm and home position when the arm is moved.


[view class]
disableRibbonStrip
public:
virtual IProgressIndicator& disableRibbonStrip()

Sets the ribbonStrip style to off.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
enableRibbonStrip
public:
virtual IProgressIndicator& enableRibbonStrip( bool enableRibbonStrip = true )

Enables or disables the ribbonStrip style for the progress indicator.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

If the ribbonStrip style is set, true is returned. Otherwise, false is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Shaft Operations

Use these members to set and query attributes of the progress indicator's shaft.


[view class]
setShaftBreadth
public:
virtual IProgressIndicator& setShaftBreadth( unsigned long breadth )

Sets the shaft width in pixels for vertical progress indicators. Sets the shaft height in pixels for horizontal progress indicators.

breadth
Number of pixels.

Exception

IInvalidParameter The breadth is invalid.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

Native Windows progress indicators (that is, progress indicators constructed without the pmCompatible style) do not support shaft sizing. Therefore, this member function has no effect for native Windows progress indicators.


[view class]
setShaftPosition
public:
virtual IProgressIndicator& setShaftPosition( const IPoint& position )

Sets the position, in pixels, of the origin point of the shaft. The position of the shaft is relative to the origin of the progress indicator window.

Exception

IInvalidParameter The position is invalid.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

AIX Considerations

The AIX release ignores this function.

Windows Considerations

Native Windows progress indicators (that is, progress indicators constructed without the pmCompatible style) do not support shaft positioning. Therefore, this member function has no effect for native Windows progress indicators.


[view class]
shaftPosition
public:
virtual IPoint shaftPosition() const

Returns the origin point of the shaft relative to the origin corner of the progress indicator window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

Native Windows progress indicators (that is, progress indicators constructed without the pmCompatible style) do not support shaft positioning. Therefore, this member function returns a default IPoint object for native Windows progress indicators.


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

Returns the size of the shaft in pixels.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

Native Windows progress indicators (that is, progress indicators constructed without the pmCompatible style) do not support shaft sizing. Therefore, this member function returns a default ISize object for native Windows progress indicators.


Snap Support

Use these members to query and change the snapToTickMark style of the progress indicator object. The snapToTickMark style specifies that the progress indicator's arm snaps to the nearest tick when moved between two ticks.


[view class]
disableSnapToTick
public:
virtual IProgressIndicator& disableSnapToTick()

Sets the snapToTickMark style to off.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
enableSnapToTick
public:
virtual IProgressIndicator& enableSnapToTick( bool enableSnapToTick = true )

Enables or disables the snapToTickMark style for the progress indicator.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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

If the snapToTickMark style is set, true is returned. Otherwise, false is returned.

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 progress indicator 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]
isPMCompatible
public:
bool isPMCompatible() const

Use this member to query whether the progress indicator was constructed with the pmCompatible style.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored


[view class]
setDefaultStyle
public:
static void setDefaultStyle(const Style& style)

Sets the default style for all subsequent progress indicators.

style
Use the styles provided by IProgressIndicator 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]
alignBottom
public:
static const Style alignBottom

Sets the progress indicator to be at the bottom of the window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
alignCentered
public:
static const Style alignCentered

Sets the progress indicator to be at the center of the window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
alignLeft
public:
static const Style alignLeft

Sets the progress indicator to be at the left side of the window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
alignRight
public:
static const Style alignRight

Sets the progress indicator to be at the right side of the window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
alignTop
public:
static const Style alignTop

Sets the progress indicator to be at the top of the window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
border3D
public:
static const Style border3D

Adds an etched 3D border to the control.

Supported Platforms

Windows OS/2 AIX
Yes Ignored Ignored


[view class]
classDefaultStyle
public:
static const Style classDefaultStyle

Provides the original default style for this class, which is the following: IWindow::visible | IProgressIndicator::horizontal | IProgressIndicator::alignCentered | IProgressIndicator::homeLeft | IProgressIndicator::ribbonStrip | IProgressIndicator::primaryScale1.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
handleDrawItem
public:
static const Style handleDrawItem

An event is dispatched to the control whenever the shaft, ribbon strip, arm, and background are to be drawn.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

AIX Considerations

AIX does not support the handleDrawItem style.

Windows Considerations

Native progress indicators (that is, progress indicators constructed without the pmCompatible style) do not support the handleDrawItem style.


[view class]
homeBottom
public:
static const Style homeBottom

Specifies that the progress indicator's arm and scale start at the bottom.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
homeLeft
public:
static const Style homeLeft

Specifies that the progress indicator's arm and scale start at the left.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
homeRight
public:
static const Style homeRight

Specifies that the progress indicator's arm and scale start at the right.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
homeTop
public:
static const Style homeTop

Specifies that the progress indicator's arm and scale start at the top.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
horizontal
public:
static const Style horizontal

Specifies that the progress indicator is built horizontally.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
pmCompatible
public:
static const Style pmCompatible

Specifies that the progress indicator is compatible with the PM version of this control in both appearance and behavior.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored


[view class]
primaryScale1
public:
static const Style primaryScale1

Specifies that scale 1 is used for positioning the arm and is located above or to the right of the progress indicator.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
primaryScale2
public:
static const Style primaryScale2

Specifies that scale 2 is used for positioning the arm and is located below or to the left of the progress indicator.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
ribbonStrip
public:
static const Style ribbonStrip

Specifies that the progress indicator's shaft fills with color between the arm and home position when the arm is moved. This style is used to improve the visual clarity of the current value.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
snapToTickMark
public:
static const Style snapToTickMark

Specifies that the progress indicator's arm snaps to the nearest tick when moved between two ticks.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
vertical
public:
static const Style vertical

Specifies that the progress indicator is built vertically.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Tick Operations

Use these members to set and query attributes of tick marks.


[view class]
numberOfTicks
public:
unsigned long numberOfTicks(Scale scale) const

Returns the number of ticks for the specified scale.

Exception

IAccessError The operating system's request to query the progress indicator's control data has failed.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setTickLength

Sets the length of one or all ticks on the progress indicator scale.
Note: Because ticks are created with 0 length, they are not visible initially.

tickNumber
A 0-based tick number that is relative to the home position.
length
Length, in pixels, of the tick.


Overload 1
public:
virtual IProgressIndicator& setTickLength( unsigned long tickNumber, unsigned long length )

Exception

IInvalidParameter Either the tick index or the tick length is invalid.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

The XmSeparator widget used for a tick mark is not managed until it has a nonzero length. Due to a Motif restriction, you cannot use a length of 1. If you specify a length of 1, this function uses a length of 2.

Windows Considerations

The first and last ticks in a native Windows progress indicator (that is, a progress indicator constructed without the pmCompatible style) are always visible. Therefore, this member function has no effect for the first and last ticks. All other ticks are made visible by setting a non-zero tick length for the tick, and they are removed by setting the tick length to zero.


Overload 2
public:
virtual IProgressIndicator& setTickLength( unsigned long length )

Exception

IInvalidParameter The tick length is invalid.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations

The XmSeparator widget used for a tick mark is not managed until it has a nonzero length. Due to a Motif restriction, you cannot use a length of 1. If you specify a length of 1, this function uses a length of 2.

Windows Considerations

The first and last ticks in a native Windows progress indicator (that is, a progress indicator constructed without the pmCompatible style) are always visible. Therefore, this member function has no effect for the first and last ticks. All other ticks are made visible by setting a non-zero tick length and they are removed by setting the tick length to zero.


[view class]
setTicks

Sets the following for one (or both) of the scales:


Overload 1
public:
virtual IProgressIndicator& setTicks( unsigned long scale1NumberOfTicks, unsigned long scale2NumberOfTicks, unsigned long scale1TickSpacing = 0, unsigned long scale2TickSpacing = 0 )

Sets the scale information for both scale1 and scale2.

scale1NumberOfTicks
The number of ticks to place on scale 1 of the progress indicator.
scale2NumberOfTicks
The number of ticks to place on scale 2 of the progress indicator.
scale1TickSpacing
The number of pixels between ticks on scale 1.
scale2TickSpacing
The number of pixels between ticks on scale 2.

Exception

IAccessError The operating system's request to set the progress indicator's control data has failed.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual IProgressIndicator& setTicks( Scale scale, unsigned long numberOfTicks, unsigned long tickSpacing = 0 )

Sets the scale information for either scale 1 or scale 2.

scale
Identifier of which scale should be set to the values that follow. This value is one of the predefined Scale enum values.
numberOfTicks
The number of ticks to place on the scale of the progress indicator.
tickSpacing
The number of pixels between ticks on the scale.

Exception

IAccessError The operating system's request to set the progress indicator's control data has failed.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setTickText

Sets the text associated with the tick at the specified index. A tick need not be visible to have text associated with it.


Overload 1
public:
virtual IProgressIndicator& setTickText( unsigned long tickNumber, const IResourceId& text )

Set the tick text from a string resource.

tickNumber
A 0-based tick number relative to the home position.
text
The resource id of the text you want to label the tick with.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual IProgressIndicator& setTickText( unsigned long tickNumber, const char* text )

Set the tick text from a character string.

tickNumber
A 0-based tick number relative to the home position.
text
The character string you want to label the tick with.

Exception

IInvalidParameter Either the tick index or the tick text is invalid.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
tickLength
public:
unsigned long tickLength(unsigned long tickNumber) const

Returns the length, in pixels, of the tick at the specified index.

tickNumber
A 0-based tick number relative to the home position.

Exception

IInvalidParameter The tick index is invalid.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

The first and last ticks in a native Windows progress indicator (that is, a progress indicator constructed without the pmCompatible style) are always visible. The length returned for these ticks is 1. The tick length for all other ticks is either 1 if the tick is visible or 0 if the tick is not visible.


[view class]
tickPosition
public:
IPoint tickPosition(unsigned long tickNumber) const

Returns the pixel position of the tick at the specified index. Ticks are numbered starting with 0. The position returned is the end of the tick mark closest to the slider shaft.

tickNumber
A 0-based tick number relative to the home position.

Exception

IInvalidParameter The tick index is invalid.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations

This member function is not supported for native Windows progress indicators (that is, progress indicators constructed without the pmCompatible style). A default IPoint object is returned for native Windows progress indicators.


[view class]
tickSpacing
public:
unsigned long tickSpacing(Scale scale) const

Returns the number of pixels between ticks for the specified scale.

scale
Use the enumeration Scale to specify for which scale the tick spacing is set.

Exception

IAccessError The operating system's request to query the progress indicator's control data has failed.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
tickText
public:
IString tickText(unsigned long tickNumber) const

Returns the text associated with the tick at the specified index. Ticks are numbered starting with 0.

tickNumber
A 0-based tick number relative to the home position.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IProgressIndicator - Enumerations


[view class]
Alignment
enum Alignment { topRight, 
                 bottomLeft, 
                 centered }

Use these enumerators to specify where to place the progress indicator:

topRight
Aligns a vertical progress indicator to the right of the control window. A horizontal progress indicator is aligned to the top.
bottomLeft
Aligns a vertical progress indicator to the left of the control window. A horizontal progress indicator is aligned to the bottom.
centered
Centers the progress indicator.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
HomePosition
enum HomePosition { homeTopRight, 
                    homeBottomLeft }

Use these enumerators to specify the home position of the progress indicator:

homeBottomLeft
The home position is at the bottom for a vertical progress indicator and at the left for a horizontal progress indicator.
homeTopRight
The home position is at the top for a vertical progress indicator and at the right for a horizontal progress indicator.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
Scale
enum Scale { scale1, 
             scale2 }

Use these enumerators to specify which scale you are referring to:

scale1
Scale 1 is above a horizontal progress indicator or to the right of a vertical progress indicator.
scale2
Scale 2 is below a horizontal progress indicator or to the left of a vertical progress indicator.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


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