repo_zf1/documentation/manual/ja/module_specs/Zend_ProgressBar.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 15103 -->
<sect1 id="zend.progressbar.introduction" xmlns:xi="http://www.w3.org/2001/XInclude">
    <title>Zend_ProgressBar</title>

    <sect2 id="zend.progressbar.whatisit">
        <title>導入</title>
        <para>
            <classname>Zend_ProgressBar</classname> は、
            さまざまな環境上でプログレスバーの作成や更新を行うコンポーネントです。
            単一のバックエンドが、複数のアダプタの中のいずれかを用いて進捗状況を出力します。
            更新のたびに現在値とオプションのメッセージを受け取り、
            進捗率や残り時間などを計算してアダプタを呼び出します。
        </para>
    </sect2>

    <sect2 id="zend.progressbar.basic">
        <title><classname>Zend_Progressbar</classname> の基本的な使用法</title>
        <para>
            <classname>Zend_ProgressBar</classname> の使い方はきわめて簡単です。
            単純に <classname>Zend_Progressbar</classname> の新しいインスタンスを作成し、
            最小値と最大値を指定した上でデータ出力用のアダプタを選択するだけです。
            何かのファイルの処理を行いたい場合は、たとえば次のようになります。
        </para>

        <programlisting role="php"><![CDATA[
$progressBar = new Zend_ProgressBar($adapter, 0, $fileSize);

while (!feof($fp)) {
    // なにかの処理

    $progressBar->update($currentByteCount);
}

$progressBar->finish();
]]>
        </programlisting>

        <para>
            まず第一段階として、<classname>Zend_ProgressBar</classname>
            のインスタンスを作成してアダプタを指定し、
            最小値を 0、最大値をファイルのサイズに指定します。
            ループ内でファイルが処理されるたびに、
            現在のバイト数でプログレスバーを更新します。
            ループを抜けた後で、プログレスバーを処理完了状態に設定します。
        </para>
        <para>
            <classname>Zend_ProgressBar</classname> の <code>update()</code>
            メソッドを引数なしでコールすることもできます。
            その場合は、単に残り時間を再計算してアダプタに通知します。
            これは、データが何も更新されていないけれども
            プログレスバーを更新したいという場合に有用です。
        </para>
    </sect2>

    <sect2 id="zend.progressbar.persistent">
        <title>進捗の永続化</title>
        <para>
            複数のリクエストにまたがってプログレスバーを持続させたい場合は、
            コンストラクタの 4 番目の引数でセッション名前空間名を指定します。
            そうすると、プログレスバーのコンストラクタ内ではアダプタへの通知が行われず
            <code>update()</code> あるいは <code>finish()</code>
            をコールしたときにのみ通知が行われるようになります。
            また、現在の値や状況表示用テキスト、
            そして残り時間計算用の開始時刻などは次のリクエストにも引き継がれるようになります。
        </para>
    </sect2>

    <sect2 id="zend.progressbar.adapters">
        <title>標準のアダプタ</title>
        <para>
            <classname>Zend_ProgressBar</classname> には次の 3 つのアダプタが同梱されています。

            <itemizedlist mark="opencircle">
                <listitem><para><xref linkend="zend.progressbar.adapter.console" /></para></listitem>
                <listitem><para><xref linkend="zend.progressbar.adapter.jspush" /></para></listitem>
                <listitem><para><xref linkend="zend.progressbar.adapter.jspull" /></para></listitem>
            </itemizedlist>
        </para>
        <xi:include href="Zend_ProgressBar_Adapter_Console.xml" />
        <xi:include href="Zend_ProgressBar_Adapter_JsPush.xml" />
        <xi:include href="Zend_ProgressBar_Adapter_JsPull.xml" />
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->