NSProgress

Overview 概要

The NSProgress class provides a self-contained mechanism for progress reporting. It makes it easy for code that performs work to report the progress of that work, and for user interface code to observe that progress for presentation to the user. Specifically, you can use a progress object to show the user a progress bar and explanatory text that update as you do work. It also allows the user to cancel or pause work. NSProgressクラスは、プログレスリポート（進捗報告）のための自己充足機構を提供します。それは、作業を実行するコードに対してその作業の進捗を報告しやすく、そしてユーザインターフェイスコードに対してユーザに提示する進捗を監視しやすくします。とりわけ、あなたは進捗（プログレス）オブジェクトを使って、ユーザに進捗バーと注釈的テキストを示すことができます、それらはあなたが作業をするにつれて更新されます。それはまた、ユーザに作業を取り消しまたは一時停止を可能にもします。

Reporting Progress 進捗を報告する

Using the methods of this class, your code can report the progress it’s currently making toward completing a task, including progress in related subtasks. You can create instances of this class using the initWithParent:userInfo: instance method or the progressWithTotalUnitCount: class method. このクラスのメソッドを使って、あなたのコードは、あるタスクの完了に向かって現在なされている進捗を、関連する下位タスクの進捗を含めて報告できます。あなたは、このクラスのインスタンスをinitWithParent:userInfo:インスタンスメソッドまたはprogressWithTotalUnitCount:クラスメソッドを使って作成できます。

Progress objects have many properties that you can use to observe and report current progress. For instance, the totalUnitCount property represents the total number of units of work, and the completedUnitCount and fractionCompleted properties represent how much of that work is complete. The fractionCompleted property is useful for updating progress indicators or textual descriptors. To check whether progress is complete, test the finished property. 進捗オブジェクトは、多くのプロパティを持ちます、それらはあなたが現在の進捗を監視および報告するのに使用できるものです。例えば、totalUnitCountプロパティは仕事の単位それらの総数を表します、そしてcompletedUnitCountとfractionCompletedプロパティはどのくらいその仕事が完了するかを表します。fractionCompletedプロパティは、進捗インジケータまたはテキスト記述子を更新するのに役立ちます。進捗が完了するかどうか確認するには、finishedプロパティをテストしてください。

The following code shows a sample method that reports the progress of performing an operation on a piece of data. When creating the progress object, you set the value of its totalUnitCount property to a suitable batch size for the operation, and the completedUnitCount count is 0. Each time the loop executes and processes a batch of data, you increment the progress object’s completedUnitCount property appropriately. 以下のコードは、ある見本のメソッドを示します、それはある演算を一片のデータ上で実行することの進捗を報告するものです。進捗オブジェクトを作成する時、あなたはそれのtotalUnitCountプロパティの値をその演算に対するある適切な一括処理寸法（バッチサイズ）に設定します、そしてcompletedUnitCount計数は0です。ループの遂行と一括データが処理されるたびごとに、あなたは進捗オブジェクトのもつcompletedUnitCountプロパティを適切に漸増します。

- (void)startTaskWithData:(NSData *)data {
    NSUInteger batchSize = ... use a suitable batch size
    NSProgress *progress = [NSProgress progressWithTotalUnitCount:batchSize];
 
    for (NSUInteger index = 0; index < batchSize; index++) {
        // Check for cancellation.
        if ([progress isCancelled]) {
             // Tidy up as necessary.
             break;
        }
 
        // Do something with this batch of data.
 
        // Report progress (add 1 because the work is complete for the current index).
        [progress setCompletedUnitCount:(index + 1)];
    }
}

Each of the properties of a progress object, including totalUnitCount, completedUnitCount, and fractionCompleted, support key-value observing (KVO). This makes it extremely easy for a view or window controller object to observe the properties, and update UI elements, such as progress indicators, when the values change. It also means that there is a nonzero cost to updating the values of those properties, so avoid using a unit count that is too granular. If you’re iterating over a large dataset, for example, and each operation takes only a trivial amount of time, divide the work into batches so you can update the unit count once per batch rather than once per iteration. ある進捗オブジェクトのプロパティのそれぞれは、totalUnitCount、completedUnitCount、そしてfractionCompletedを含めて、キー値監視（KVO）をサポートします。これは、あるビューまたはウインドウのコントローラオブジェクトが、プロパティそれらを監視する、そして進捗インジケータのようなUI要素を値が変化する時に更新するのを非常に簡単にします。それはまた、皆無ではないコストがこれらプロパティの値を更新するために存在することを意味します、なので微粒すぎる単位計数の使用を避けてください。あなたがある大きなデータ群すべてにわたって反復している、例えば、そして各演算は取るに足らない量の時間しかかからないならば、その仕事をいくつかの一括処理に分割してください、それであなたは一括処理ごとに一度だけ単位計数を更新できます、反復ごとに一度でなく。

Reporting Progress for Multiple Operations 複数の演算に対する進捗を報告する

Sometimes, your code may need to report the overall progress of an operation that consists of several suboperations. To accomplish this, your code can report the progress of each suboperation by building up a tree of progress objects. 時々、あなたのコードは、幾つかの下位演算から構成されるある演算の全てをひっくるめた進捗を報告する必要があるかもしれません。これを成し遂げるために、あなたのコードは、各下位演算の進捗を報告することが、進捗オブジェクトそれらからなるある木構造（ツリー）を作り上げることによって可能です。

The NSProgress reporting mechanism supports a loosely coupled relationship between progress objects. Suboperations don’t need to know anything about the containing progress item — you can create new progress objects as suboperations of another progress instance. When you assign a progress instance, the system allocates a portion of the containing progress instance’s pending unit count. When the suboperation’s progress object completes, the containing progress object’s completedUnitCount property automatically increases by a predefined amount. NSProgress報告機構は、進捗オブジェクトそれらの間のゆるく結びつけられた関係をサポートします。下位演算は、包含（親）進捗項目について何も知る必要はありません — あなたは、新しい進捗オブジェクトを別の進捗インスタンスの下位演算として作成できます。あなたがある進捗インスタンスをアサイン（付与？）する時、システムは包含進捗インスタンスのもつ未解決の単位数の一部にアロケート（計上？）します。下位演算のもつ進捗オブジェクトが完了する時、包含進捗オブジェクトのもつcompletedUnitCountプロパティは、あるあらかじめ定義された量だけ自動的に漸増します。

You add suboperation progress objects to your tree implicitly or explicitly. あなたは、下位演算進捗オブジェクトそれらをあなたの木構造へと暗黙的にまたは明示的に加えます。

Adding a Progress Operation Implicitly 進捗演算を暗黙的に加える

Add a suboperation implicitly by setting a pending unit count for the containing progress object and creating a new NSProgress instance. When you create the new progress instance, the system sets it as a suboperation of the containing progress object, and assigns the pending unit count. 包含（親）進捗オブジェクトに対してある未解決の単位計数を設定することそして新しいNSProgressインスタンスを作成することによって、ある下位演算を暗黙的に加えてください。あなたが新しい進捗インスタンスを作成する時、システムはそれを包含進捗オブジェクトのある下位演算として設定します、そしてその未解決の単位数をアサイン（付与）します。

As an example, consider that you’re tracking the progress of code downloading and copying files on disk. You can use a single progress object to track the entire task, but it’s easier to manage each subtask using a separate progress object. You start by creating an overall progress object with a suitable total unit count, call becomeCurrentWithPendingUnitCount:, then create your suboperation progress objects before finally calling resignCurrent. 例として、あなたがディスク上でファイルをダウンロードおよびコピーしているコードの進捗を追跡していると考えてください。あなたは単一の進捗オブジェクトを使ってタスク全体を追跡できます、しかしそれぞれの下位タスクをある分離した進捗オブジェクトを使って管理する方がより簡単です。あなたは、全体としての進捗オブジェクトをある適切な総単位計数で作成することによって開始して、becomeCurrentWithPendingUnitCount:を呼び出して、それからあなたの下位演算進捗オブジェクトを作成してください、最終的にresignCurrentを呼び出す前にです。

The system divides the pending unit count that you specify in the first method equally among the suboperation progress objects you create between these two method calls. Each suboperation progress object maintains its own internal unit count. When the suboperation object’s completedUnitCount equals or exceeds its totalUnitCount, the system increases the containing progress object’s completedUnitCount by the assigned portion of the original pending unit count. システムは、あなたが最初のメソッドにおいて指定する未解決単位計数を、あなたがこれら２つのメソッド呼び出しの間に作成する下位演算進捗オブジェクトそれらの間に等しく分配します。それぞれの下位演算進捗オブジェクトは、それ自身の内部単位計数を管理します。下位演算オブジェクトのもつcompletedUnitCountがそれのtotalUnitCountに等しいか越える場合、システムは包含進捗オブジェクトのもつcompletedUnitCountを元の未解決単位計数の割り当て部分だけ漸増します。

In the following example, the overall progress object has 100 units. The two suboperation objects, therefore, get 50 pending units each, and keep track internally of 10 units of work each. When each suboperation completes its 10 units, the system increases the overall progress object’s completed unit count by 50. 以下の例において、全体としての進捗オブジェクトは100単位を持ちます。２つの下位演算オブジェクトは、それゆえに、50未解決単位をそれぞれ取得します、そして内部的に10単位の仕事の経過をそれぞれ追いかけます。それぞれの下位演算がそれの10単位を完了する時、システムは全体進捗オブジェクトのもつ完了単位計数を50だけ漸増します。

- (void)startLongOperation {
    self.overallProgress = [NSProgress progressWithTotalUnitCount:100];
 
    [self.overallProgress becomeCurrentWithPendingUnitCount:50];
    [self work1];
    [self.overallProgress resignCurrent];
 
    [self.overallProgress becomeCurrentWithPendingUnitCount:50];
    [self work2];
    [self.overallProgress resignCurrent];
}
 
- (void)work1 {
    NSProgress *firstTaskProgress = [NSProgress progressWithTotalUnitCount:10];
    // Perform first task.
}
 
- (void)work2 {
    NSProgress *secondTaskProgress = [NSProgress progressWithTotalUnitCount:10];
    // Perform second task.
}

If you don’t create any suboperation progress objects between the calls to becomeCurrentWithPendingUnitCount: and resignCurrent, the containing progress object automatically updates its completedUnitCount by adding the pending units. あなたがbecomeCurrentWithPendingUnitCount:とresignCurrentへの呼び出しの間にどんな下位演算進捗オブジェクトも作成しないならば、包含進捗オブジェクトは自動的にそれのcompletedUnitCountを、未解決単位それらの追加によって更新します。

Adding a Progress Operation Explicitly 進捗演算を明示的に加える

To add a progress operation explicitly, call addChild:withPendingUnitCount: on the containing progress object. The value for the pending unit count is the amount of the containing progress object’s totalUnitCount that the suboperation consumes, which conforms to the NSProgressReporting protocol. ある進捗演算（子）を加えるには、addChild:withPendingUnitCount:を包含進捗オブジェクト（親）上で呼び出してください。未解決単位計数に対する値は、包含進捗オブジェクトのもつtotalUnitCountのうち、その下位演算（子）が消費する分の合計です。

In the following example, the overall progress object has 10 units. The suboperation progress for the download gets eight units and tracks the download of a photo. The progress for the filter takes a lot less time and gets the remaining two units. When the download completes, the system updates the containing progress object’s completed unit count by eight. When the filter completes, the system updates it by the remaining two units. 以下の例において、全体としての進捗オブジェクトは10単位を持ちます。ダウンロードに対しての下位演算進捗は、８単位をとります、そしてある写真のダウンロードを追跡します。フィルタに対する進捗は、ずっと少ない時間しかかかりません、それで残りの２単位をとります。ダウンロードが完了する時、システムは包含進捗オブジェクトのもつ完了単位計数を８だけ更新します。フィルタが完了する時、システムはそれを残りの２単位によって更新します。

- (void)startLongOperation {
    self.overallProgress = [NSProgress progressWithTotalUnitCount:10];
 
    [self.overallProgress addChild:download.progress withPendingUnitCount:8];
    // Do the download.
 
    [self.overallProgress addChild:filter.progress withPendingUnitCount:2];
    // Perform the filter.
}