Inside Macintosh: Cyberdog Programmer's Kit / Part 3 - Cyberdog Reference

Chapter 7 - Classes and Methods

CyberProgressBroadcaster

Superclasses

ODObject

Subclasses

none

An object of the CyberProgressBroadcaster class is used to represent the progress of a process that occurs asynchronously.

Description

When you initiate an asynchronous operation, such as opening a Cyberdog stream, you can create a corresponding CyberProgressBroadcaster object to represent the progress of the process. You use the progress broadcaster object together with a progress receiver (page 318) and a progress part (page 313) to monitor and display the progress and status of the asynchronous process.

A progress broadcaster has attributes that describe the current status and progress of the process. The broadcaster keeps track of the total amount of work to be performed by the process and the amount that has been performed so far. The progress mode of the process indicates whether the total amount of work to be performed is known and can be measured. A progress broadcaster has accessor methods that allow you to get and set its attributes.

The object initiating an asynchronous process attaches a progress broadcaster to a progress part that displays the progress of the process to the user. The progress part, in turn, attaches its progress receiver to the progress broadcaster. When the display part calls one of the broadcaster's accessor methods to set an attribute, the broadcaster caches the value and calls a corresponding method to set the value in each of its attached progress receivers. The progress receiver updates the display of the progress part.

In Cyberdog, this progress reporting mechanism is used in two situations.

• When a Cyberdog item is opened, if either a Cyberdog item's Open method or a Cyberdog display part's OpenCyberItem method is asynchronous, the method should display the progress of the asynchronous operation to the user. To do this, the asynchronous method should obtain an opener part and attach a broadcaster that represents the asynchronous operation to the obtained opener part.
• When a Cyberdog display part is embedded in a navigator, the display part should attach a broadcaster object to the navigator; the broadcaster represents the process of downloading the content referenced by the display part's Cyberdog item.

Typically, there is a one-to-one relationship between a progress broadcaster object and a progress receiver object. However, if necessary, you can attach multiple receivers to a broadcaster, or vice versa. For example, if you were downloading multiple images located on a web page, you might represent the downloading of each image as a separate broadcaster, and attach one progress receiver to all the broadcasters to monitor the progress of all the download operations.

You can use the CyberProgressBroadcaster class as is or subclass it to customize its behavior. The CyberProgressBroadcaster class is fully functional with the exception of the Abort method. The Abort method calls the callback function registered by the ICyberProgressBroadcaster method. You implement the Abort method's behavior with this function. This allows you to customize the behavior of the CyberProgressBroadcaster class's Abort method without creating a subclass.

For more information on using progress parts to display progress, see the description of the CyberProgressPartExtension class (page 313).

Methods

This section presents summary descriptions of the CyberProgressBroadcaster methods grouped according to purpose, followed by detailed descriptions.

Initialization and Cleanup

ICyberProgressBroadcaster

Initializes this progress broadcaster.

Aborting a Process

Abort

Terminates this progress broadcaster.

Attaching and Detaching Progress Receivers

AttachReceiver

Attaches a progress receiver to this progress broadcaster.

DetachReceiver

Detaches a progress receiver from this progress broadcaster.

Accessing Progress Receivers

CountReceivers

Retrieves the number of progress receivers attached to this progress broadcaster.

GetReceiver

Retrieves a progress receiver attached to this progress broadcaster.

Polling for Progress

GetAmountDone

Retrieves a value representing what portion of an asynchronous process has been completed.

GetAmountTotal

Retrieves a value representing the total amount of work to be completed by an asynchronous process.

GetErrorString

Retrieves the error string associated with an asynchronous process.

GetProgressMode

Retrieves the progress mode for an asynchronous process.

GetProgressPercent

Retrieves the percentage of an asynchronous process that has been completed.

GetStatusString

Retrieves the status string associated with an asynchronous process.

Broadcasting Progress

ResetProgress

Resets the status and progress attributes of this progress broadcaster to their default values.

SetAmountDone

Sets a value representing what portion of an asynchronous process has been completed.

SetAmountTotal

Sets a value representing the total amount of work to be completed by an asynchronous process.

SetErrorString

Sets the error string associated with an asynchronous process.

SetProgressMode

Sets the progress mode for an asynchronous process.

SetProgressPercent

Sets the percentage of an asynchronous process that has been completed.

SetStatusString

Sets the status string associated with an asynchronous process.

---

Methods

Abort

AttachReceiver

CountReceivers

DetachReceiver

GetAmountDone

GetAmountTotal

GetErrorString

GetProgressMode

GetProgressPercent

GetReceiver

GetStatusString

ICyberProgressBroadcaster

ResetProgress

SetAmountDone

SetAmountTotal

SetErrorString

SetProgressMode

SetProgressPercent

SetStatusString