Developer Documentation
PATH  Mac OS X Documentation > Application Kit Reference: Objective-C


[Previous] [Class List] [Next]

NSProgressIndicator


Inherits from: NSView : NSResponder : NSObject
Conforms to: NSCoding
(NSResponder)
NSObject (NSObject)
Declared in: AppKit/NSProgressIndicator.h




Class Description


An application displays a progress indicator to show that a lengthy task is under way. Some progress indicators do nothing more than spin to show that the application is busy, while others show the percentage of the task that has been completed. NSProgressIndicator provides both types of display:

[image: Art/ProgIndicator.tiff]

NSProgressIndicator is a subclass of NSView. To display a progress indicator, your application creates a window and adds the progress indicator as a subview of the window's content view or any subview. You can create a progress indicator programmatically with its constructorand initialize it with the initWithFrame: method. However, you normally use Interface Builder to create and initialize a progress indicator and to install it in an application view.

For an indeterminate progress indicator, you invoke startAnimation: to start the animation (the spinning of the barber pole) and stopAnimation: when the task is complete. By default, the delay between animation steps is one twelfth of a second (5.0/60.0). You can change the animation delay by invoking setAnimationDelay:. Setting the delay to a double value larger than the default value will slow the animation, while setting the delay to a smaller value will speed it up.

Instead of invoking startAnimation: and stopAnimation:, you can control an indeterminate progress indicator directly by sending the animate: message. Each time you invoke animate:, the animation advances by one step. You can speed up or slow down the animation by varying how often you invoke animate:. Like other views, a progress indicator redisplays itself on each pass through the event loop, if needed. To ensure immediate redrawing, however, you can invoke the displayIfNeeded method (inherited from NSView) each time you invoke animate:.

By default, a progress indicator is indeterminate. Your can specify a determinate progress indicator when you set up the view with Interface Builder, or you can use code like the following to change the default value programmatically:

[myProgressIndicatorView setIndeterminate:FALSE];

For a determinate progress indicator, you invoke the incrementBy: method to advance the progress bar. By default, a determinate progress indicator goes from 0.0 to 100.0. You can increment by any amount, but if you vary the increment too widely, progress may appear uneven or jerky. You typically choose an increment value that evenly divides 100.0. For example, you might invoke incrementBy: 50 times, incrementing by 2.0 each time, to draw the complete progress bar. To modify the default range of 0.0 to 100.0, you can invoke setMinValue: to modify the minimum value and setMaxValue: to modify the maximum value.

After each invocation of incrementBy:, you can invoke the displayIfNeeded method to ensure immediate redrawing.

You can display progress indicators of different sizes by varying the frame size. However, the default size is designed to provide the best results. By default, a progress indicator is drawn with a bezeled frame, but you can use the setBezeled: method to modify the bezeled-frame setting.

A progress indicator is drawn with colors based on the user's current color scheme. When the user changes the color scheme, the color of the progress indicator changes automatically to match the new scheme.


Method Types


Creating an instance
- initWithFrame:
Animating the progress indicator
- animate:
- animationDelay
- setAnimationDelay:
- setUsesThreadedAnimation:
- startAnimation:
- stopAnimation:
- usesThreadedAnimation
Advancing the progress bar
- incrementBy:
- setDoubleValue:
- doubleValue
- setMinValue:
- minValue
- setMaxValue:
- maxValue
Setting the appearance
- setBezeled:
- isBezeled
- setIndeterminate:
- isIndeterminate


Instance Methods



animate:

- (void)animate:(id)sender

Advances the progress animation of an indeterminate progress animator by one step. Your application uses this method to control animation directly (as opposed to invoking startAnimation: and stopAnimation: for automatic animation). The more often you invoke animate:, the faster the animation progresses. Determinate progress indicators do not use the same animation method; therefore, this method does nothing for a determinate progress indicator.

The animate: method only invalidates the progress indicator so it will be redrawn the next time through the event loop. To ensure immediate redrawing, invoke the displayIfNeeded method.

See Also: - animationDelay, - setAnimationDelay:



animationDelay

- (NSTimeInterval)animationDelay

Returns the delay, in seconds, between animation steps for an indeterminate progress indicator. By default, the animation delay is set to one twelfth of a second (5.0/60.0). A determinate progress indicator does not use the animation delay value.

See Also: - animate:



doubleValue

- (double)doubleValue

Returns a value that indicates the current extent of the progress bar of a determinate progress indicator. For example, a determinate progress indicator goes from 0.0 to 100.0 by default. If the progress bar has advanced half way across the view, the value returned by doubleValue would be 50.0. An indeterminate progress indicator does not use this value.

See Also: - incrementBy:, - setDoubleValue:



incrementBy:

- (void)incrementBy:(double)delta

Advances the progress bar of a determinate progress indicator by delta. For example, if you want to advance a progress bar from 0.0 to 100.0 in twenty steps, you would invoke incrementBy: twenty times with a delta value of 5.0.

See Also: - doubleValue



initWithFrame:

- (id)initWithFrame:(NSRect)frameRect

Initializes a newly allocated NSProgressIndicator with frameRect as its frame rectangle. This method is the designated initializer for the NSProgressIndicator class. It calls the initWithFrame: method of its superclass, NSView, then performs initialization specific to the outline view. It returns self.

It's usually more convenient to use Interface Builder, which allows you to create an NSProgressIndicator and embed it in the superview of your choice.



isBezeled

- (BOOL)isBezeled

Returns YES if the NSProgressIndicator's frame has a three-dimensional bezel.

See Also: - setBezeled:



isIndeterminate

- (BOOL)isIndeterminate

Returns YES if the NSProgressIndicator is indeterminate. An indeterminate progress indicator displays a "barber pole" that spins until the task is complete. A determinate progress indicator draws a three-dimensional bar from left to right as the task progresses.

See Also: - setIndeterminate:



maxValue

- (double)maxValue

Returns the maximum value for the progress bar of a determinate progress indicator. By default, a determinate progress indicator goes from 0.0 to 100.0, so the value returned would be 100.0. An indeterminate progress indicator does not use this value.

See Also: - minValue, - setMaxValue:



minValue

- (double)minValue

Eeturns the minimum value for the progress bar of a determinate progress indicator. By default, a determinate progress indicator goes from 0.0 to 100.0, so the value returned would be 0.0. An indeterminate progress indicator does not use this value.

See Also: - maxValue, - setMinValue:



setAnimationDelay:

- (void)setAnimationDelay:(NSTimeInterval)delay

Sets the delay, in seconds, between animation steps for an indeterminate progress indicator. By default, the animation delay is set to one twelfth of a second (5.0/60.0). Setting the delay to a double value larger than 5.0/60.0 will slow the animation, while setting the delay to a smaller value will speed it up. A determinate progress indicator does not use the animation delay value.

setBezeled:

- (void)setBezeled:(BOOL)flag

Sets whether the NSProgressIndicator's frame has a three-dimensional bezel.

See Also: - isBezeled



setDoubleValue:

- (void)setDoubleValue:(double)doubleValue

Sets the value that indicates the current extent of the progress bar. An indeterminate progress indicator does not use this value.

See Also: - doubleValue, - incrementBy:, - setMaxValue:, - setMinValue:



setIndeterminate:

- (void)setIndeterminate:(BOOL)flag

Sets whether the NSProgressIndicator is indeterminate.

See Also: - isIndeterminate



setMaxValue:

- (void)setMaxValue:(double)newMaximum

Specifies the maximum value for the progress bar. An indeterminate progress indicator does not use this value.

See Also: - maxValue



setMinValue:

- (void)setMinValue:(double)newMinimum

Specifies the minimum value for the progress bar. An indeterminate progress indicator does not use this value.

See Also: - minValue



setUsesThreadedAnimation:

- (void)setUsesThreadedAnimation:(BOOL)flag

Sets whether the receiver implements animation of the progress indicator in a separate thread. If the application becomes multithreaded as a result of an invocation of this method, the application's performance could become noticeably slower.

See Also: - usesThreadedAnimation



startAnimation:

public void startAnimation(Object sender)

Starts the animation of an indeterminate progress indicator, which causes the barber pole to start spinning. Does nothing for a determinate progress indicator.

See Also: - animationDelay, - stopAnimation:



stopAnimation:

- (void)stopAnimation:(id)sender

Stops the animation of an indeterminate progress indicator, which causes the barber pole to stop spinning. Does nothing for a determinate progress indicator.

See Also: - animationDelay, - startAnimation:



usesThreadedAnimation

- (BOOL)usesThreadedAnimation

Returns whether the receiver implements the animation of the progress indicator in a separate thread.

See Also: - setUsesThreadedAnimation:




[Previous] [Next]