PATH  Documentation > Mac OS X > Application Kit Reference: Java

Table of Contents

NSProgressIndicator


Inherits from:
NSView : NSResponder : NSObject
Package:
com.apple.yellow.application


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/ProgIndIndet.gif]

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 constructor. 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(true)];

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


Constructors
NSProgressIndicator
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


Constructors



NSProgressIndicator

public NSProgressIndicator()

Description forthcoming.

public NSProgressIndicator(NSRect frameRect)

Creates an NSProgressIndicator with frameRect as its frame rectangle. This method is the designated initializer for the NSProgressIndicator class. It calls the constructor method of its superclass, NSView, then performs initialization specific to the outline view.

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.




Instance Methods



animate

public void animate(Object 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

public double 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

public 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

public 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



isBezeled

public boolean isBezeled()

Returns true if the receiver's frame has a three-dimensional bezel.

See Also: setBezeled



isIndeterminate

public boolean isIndeterminate()

Returns true if the receiver 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

public 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

public double minValue()

Returns 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

public void setAnimationDelay(double 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

public void setBezeled(boolean flag)

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

See Also: isBezeled



setDoubleValue

public void setDoubleValue(double doubleValue)

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

See Also: doubleValue, incrementBy, setMaxValue, setMinValue



setIndeterminate

public void setIndeterminate(boolean flag)

Sets whether the receiver is indeterminate.

See Also: isIndeterminate



setMaxValue

public void setMaxValue(double newMaximum)

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

See Also: maxValue



setMinValue

public void setMinValue(double newMinimum)

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

See Also: minValue



setUsesThreadedAnimation

public void setUsesThreadedAnimation(boolean 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

public void stopAnimation(Object 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

public boolean usesThreadedAnimation()

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

See Also: setUsesThreadedAnimation




Table of Contents