javax.microedition.lcdui
クラス Gauge

java.lang.Object
  javax.microedition.lcdui.Item
      javax.microedition.lcdui.Gauge

public class Gauge
extends Item

整数値に関する棒グラフなどのグラフィカルな表示を提供します。 オブジェクトが受け付ける値は、0 からアプリケーションによって設定された最大の値までの範囲の正数です。 アプリケーションが示す値はこの範囲に正規化されます。 デバイスが装備しているディスプレイに表現可能な視覚表現でアプリケーションが設定した値を表示します。 このため、複数の値が同一の視覚表現を示すことがあります。

例えば、1 セット 10 本の棒を使用して Gauge の近似値を表示するデバイス上で、0 〜 99 の範囲の Gauge オブジェクトを想像してみてください。 デバイスは 0 〜 9 の値を１本目の棒、10 〜 19 までの値を２本目の棒、20 〜 29 までの値を３本目の棒などで表現するでしょう。

Gauge は対話型であることも非対話型であることもあります。 アプリケーションは対話モードであるか否かに関わらず、いつでも Gauge の値を設定および取得することができます。 実装は、オブジェクトが対話モードか否かで視覚表現を変更するかもしれません。

対話モードでは、ユーザーが Gauge の値を変更することができます。 ユーザーは常に Gauge の値を 1 ずつ増減させることができ、さらにより大きな単位で増減させる手段を提供することもあります。 ユーザーは設定された範囲外に値を移動させることはできません。 想定される制御手順は、アプリケーションが初期値を設定し、次にユーザーが値を変更可能に設定する、ということです。 アプリケーションはユーザーが Gauge を操作している最中であっても値を変更することができます。

多くのケースでは、ユーザーが値を修正するための唯一の手段は、ボタン操作によって１単位で値を増減させることのみです。 このため、アプリケーションは少量の範囲の値を指定すべきです。

非対話モードでは、ユーザーは Gauge の値を変更することはできません。 非対話モードの Gauge の想定される用途は、処理に長時間かかるオペレーションにおいて、進捗状態を示す「プログレス・インジケータ」または「アクティビティ・インジケータ」としての役割です。 この場合、アプリケーションは定期的に setValue() メソッドを呼び出し、値をアップデートします。

非対話モードの限定あるいは非限定の範囲を持つことができます。 Gauge に限定された範囲があるなら、アプリケーションは包括的なゼロから最大値の間の整数値を設定するでしょう。 実装は上記で説明したように、この値のグラフ表示を提供します。

非限定の範囲を持つ非対話モードの Gauge は４つのモードのうち、１つの状態にあります： コンティニアス・アイドル（連続的なアイドル）、インクリメンタル・アイドル（進行的なアイドル）、コンティニアス・ランニング（連続的な実行）、インクリメンタル・アップデート（増加的な更新）。 これらの状態は、何らかのアクティビティ・レベルが発生していることをユーザーに示すことを意図しています。 インクリメンタル・アップデートは、アクティビティが既知の終点に向けて進捗していることをユーザーに示します。 コンティニアス・ランニングは、既知の終点がなく、またユーザーに報告すべき進捗がありません：コンティニアス・ランニングは、ただビジー状態であることを示します。 実装は適切にこれらを示すグラフィカルな表示を実現すべきです。 実装は非限定コンティニアスの Gauge と非限定インクリメンタルの Gauge では異なったグラフィック表現を使用するかもしれません。 このために、個々のアイドル状態が各モードのために存在しています。 例えば、実装はコンティニアス・ランニング状態では砂時計や回転する腕時計を表示するかもしれません。しかし、インクリメンタル・アップデート状態ではビーチ・ボールやキャンディ・ストライプ・バー（さかき注：棒状の飴に斜めに直線模様が入っているものを指している）のような、異なる状態には異なったアニメーションを表示しなければなりません。

コンティニアス・アイドルおよびインクリメンタル・アイドル状態では、Gauge はアクティビティがまったく発生していないことを示します。 インクリメンタル・アップデート状態では、Gauge はアクティビティを示しますが、アプリケーションの setValue() の呼び出しによる更新に限り、グラフ表示を更新すべきです。 コンティニアス・ランニング状態では、アプリケーションからの更新要求がなくとも Gauge は絶え間なく動くアニメーションを表示することによって、アクティビティを示します。

CONTINUOUS_IDLE、INCREMENTAL_IDLE、CONTINUOUS_RUNNING、および INCREMENTAL_UPDATING 値は、Gauge が非対話モードで非限定の範囲を持つように設定された場合に限り特別な意味を持ちます。 Gauge が対話モードであるか、または限定の範囲を持つように設定されているなら、それらは通常の値として扱います。

また、プログレス・インジケータとして Gauge を使用するアプリケーションは、一般に STOP コマンドを提供し、ユーザーが処理を停止できるようにすべきです。

アプリケーション開発者のための注記

上記のように、非対話モードの Gauge は長時間の実行中の間に、ユーザーにフィードバックを提供するために使用することがあります。 あらかじめ終点が判明していて、アプリケーションがオペレーションの進捗を知ることができるなら、アプリケーションは限定の範囲を持つ非対話モードの Gauge を用いるべきです。 例えば、サイズが 20 キロバイトであることが判明しているファイルをダウンロードするアプリケーションを想像してください。 アプリケーションは、Gauge の最大値を 20 とし、現在までにダウンロードしたキロバイト数を設定します。 その時々までに終了したタスクの量を示す Gauge をユーザーに提供することができます。

あるいは、アプリケーションが未知のサイズのファイルをダウンロードするなら、それは非限定の範囲を持つ非対話モードの Gauge を用いるべきです。 理想的には、アプリケーションはおそらく入力バッファが満たされるたびに定期的に setValue(INCREMENTAL_UPDATING) を呼び出すべきです。 これにより、進捗の進行速度を示す印をユーザーに提供することができます。

アプリケーションでオペレーションを実行しているものの、最終的に進捗を確認する手段が存在しないなら、それは非限定の範囲を持つ非対話モードの Gauge に CONTINUOUS_RUNNING あるいは CONTINUOUS_IDLE のいずれか適切な値を設定すべきです。 例えば、アプリケーションがネットワークサーバーに要求を行い、サーバーが応答するまで処理を停止して待つなら、CONTINUOUS_RUNNING を Gauge を状態として設定すべきです。そして、応答を受けた後に CONTINUOUS_IDLE を状態として設定すべきです。

導入されたバージョン:

MIDP 1.0

INDEFINITE

public static final int INDEFINITE

Gauge が非限定の範囲を持つことを示すために、最大値として使用する特別な値です。 この値はコンストラクタの maxValue パラメータ、setMaxValue() に渡すパラメータ、および getMaxValue() の戻り値として使用します。

INDEFINITE の値は -1 です。

導入されたバージョン:

MIDP 2.0

関連項目:

定数フィールド値

CONTINUOUS_IDLE

public static final int CONTINUOUS_IDLE

非限定の範囲を持つ非対話モードの Gauge のコンティニアス・アイドル（連続的なアイドル）状態を示す値です。 コンティニアス・アイドル状態では、進捗がまったく進んでいないことを示すためのグラフィックを Gauge に表示します。

この値は非限定の範囲を持つ非対話モードの Gauge でのみ意味を持ちます。 対話モードおよび限定の範囲を持つ Gauge では普通の値として扱います。

CONTINUOUS_IDLE の値は 0 です。

導入されたバージョン:

MIDP 2.0

関連項目:

定数フィールド値

INCREMENTAL_IDLE

public static final int INCREMENTAL_IDLE

非限定の範囲を持つ非対話モードの Gauge のインクリメンタル・アイドル（進行的なアイドル）状態を示す値です。 インクリメンタル・アイドル状態では、進捗がまったく進んでいないことを示すためのグラフィックを Gauge に表示します。

この値は非限定の範囲を持つ非対話モードの Gauge でのみ意味を持ちます。 対話モードおよび限定の範囲を持つ Gauge では普通の値として扱います。

INCREMENTAL_IDLE の値は 1 です。

導入されたバージョン:

MIDP 2.0

関連項目:

定数フィールド値

CONTINUOUS_RUNNING

public static final int CONTINUOUS_RUNNING

非限定の範囲を持つ非対話モードの Gauge のコンティニアス・ランニング（連続的な実行）状態を示す値です。 コンティニアス・ランニング状態では、進行中のタスクを示す Gauge を絶えずアップデートするアニメーションを表示します。 アプリケーションが一度コンティニアス・ランニング状態に設定した Gauge は、アプリケーションがさらに何らかの要求をすることなくアニメーションを続けるべきです。

この値は非限定の範囲を持つ非対話モードの Gauge でのみ意味を持ちます。 対話モードおよび限定の範囲を持つ Gauge では普通の値として扱います。

CONTINUOUS_RUNNING の値は 2 です。

導入されたバージョン:

MIDP 2.0

関連項目:

定数フィールド値

INCREMENTAL_UPDATING

public static final int INCREMENTAL_UPDATING

非限定の範囲を持つ非対話モードの Gauge のインクリメンタル・アップデート（増加的な更新）状態を示す値です。 インクリメンタル・アップデート状態では、Gauge は進行中のタスクが進んでいることをグラフィックで表示します（通常、アニメーション・シーケンスの１フレームを表示します）。 アプリケーションが setValue(INCREMENTAL_UPDATING) を呼び出したときに限り、アニメーション・シーケンスを次のフレームに更新すべきです。

この値は非限定の範囲を持つ非対話モードの Gauge でのみ意味を持ちます。 対話モードおよび限定の範囲を持つ Gauge では普通の値として扱います。

INCREMENTAL_UPDATING の値は 3 です。

導入されたバージョン:

MIDP 2.0

関連項目:

定数フィールド値

Gauge

public Gauge(String label,
             boolean interactive,
             int maxValue,
             int initialValue)

指定されたラベル、対話モード、最大値と初期値のオブジェクトを構築します。 対話モード（interactive が true）では、最大値は 0 以上でなければなりません。そうでなければ例外を throw します。 非対話モード（interactive が false） では、最大値は 0 以上か特別な値である INDEFINITE でなければなりません。そうでなければ例外を throw します。

最大値がゼロ以上ならば、Gauge は明確な範囲を持ちます。 この場合、初期値は範囲ゼロからの範囲に含まれなければなりません。 初期値がゼロ未満であるなら、値はゼロを設定します。 また初期値が maxValue よりも大きい場合、maxValue と同じ値として取り扱います。

interactive が false であり、最大値が INDEFINITE であるなら、非限定の範囲を持つ非対話モードの Gauge を作成します。 初期値は CONTINUOUS_IDLE、INCREMENTAL_IDLE、CONTINUOUS_RUNNING、または INCREMENTAL_UPDATING のいずれかの値でなければなりません。

パラメータ:

label - 設定するラベルを渡します。

interactive - ユーザーと対話可能なモードにする場合は true を、対話不可能なモードにする場合は false を渡します。

maxValue - Gauge の最大値または INDEFINITE を渡します。

initialValue - Gauge の初期値として 0 〜 maxValue までの範囲の値、あるいは maxValue が INDEFINITE ならば CONTINUOUS_IDLE、INCREMENTAL_IDLE、CONTINUOUS_RUNNING、または INCREMENTAL_UPDATING のいずれかの値を渡します。

例外:

IllegalArgumentException - 対話モードで最大値が負数の場合、非対話モードで最大値が INDEFINITE 以外の負数の場合、非対話モードかつ最大値が INDEFINITE でありながら初期値が CONTINUOUS_IDLE、INCREMENTAL_IDLE、CONTINUOUS_RUNNING、または INCREMENTAL_UPDATING のいずれかの値でない場合に throw します。

関連項目:

INDEFINITE, CONTINUOUS_IDLE, INCREMENTAL_IDLE, CONTINUOUS_RUNNING, INCREMENTAL_UPDATING

setValue

public void setValue(int value)

このオブジェクトに現在値を設定します。

Gauge が対話モードであるか、範囲が設定された非対話モードであるならば、以下の規則が適用されます。 値がゼロ未満であれば、ゼロを使用します。 現在値が最大値より大きければ、現在値には最大値を用います。

Gauge オブジェクトが非対話モードで範囲の指定のないゲージであるなら、値は CONTINUOUS_IDLE、INCREMENTAL_IDLE、CONTINUOUS_RUNNING または INCREMENTAL_UPDATING のいずれかでなければなりません。 他の値の場合には例外を throw します。

パラメータ:

value - 新しく設定する値を渡します。

例外:

IllegalArgumentException - 非対話モードで範囲の指定のないゲージに対して、CONTINUOUS_IDLE、INCREMENTAL_IDLE、CONTINUOUS_RUNNING または INCREMENTAL_UPDATING のいずれでもない値を指定した場合に throw します。

関連項目:

INDEFINITE, CONTINUOUS_IDLE, INCREMENTAL_IDLE, CONTINUOUS_RUNNING, INCREMENTAL_UPDATING, getValue()

getValue

public int getValue()

この Gauge オブジェクトに設定されている値を返します。

Gauge オブジェクトが非対話モードで範囲の指定のないゲージであるなら、CONTINUOUS_IDLE、INCREMENTAL_IDLE、CONTINUOUS_RUNNING または INCREMENTAL_UPDATING のいずれかの値を返します。 そうでなければ、ゼロからゲージの最大値の範囲に含まれる整数を返します。

戻り値:

現在この Gauge オブジェクトに設定されている値を返します。

関連項目:

INDEFINITE, CONTINUOUS_IDLE, INCREMENTAL_IDLE, CONTINUOUS_RUNNING, INCREMENTAL_UPDATING, setValue(int)

setMaxValue

public void setMaxValue(int maxValue)

この Gauge オブジェクトの最大値を設定します。

対話モードのゲージに対する新しい最大値は、ゼロ以上でなければなりません。そうでなければ例外を throw します。 非対話モードのゲージに対する新しい最大値は、ゼロ以上の値あるいは特別な値である INDEFINITE でなければなりません。そうでなければ例外を throw します。

新しい最大値がゼロ以上であるなら、明確な範囲をこのゲージに設定します。 明確な範囲が以前のゲージに設定されており、現在値が新しい最大値よりも大きいなら、現在値は新しい最大値と等しい値が設定されます。 明確な範囲が以前のゲージに設定されており、現在値が新しい最大値よりも小さいなら、現在値は変更しません。

新しい最大値がゼロ以上であり、以前のゲージに明確な範囲を持っていなければ、この新しい最大値は明確な範囲をゲージに提供します。 グラフ表示はそれにしたがって変化しなければなりません。そして、以前に設定されていた CONTINUOUS_IDLE、INCREMENTAL_IDLE、CONTINUOUS_RUNNING または INCREMENTAL_UPDATING のいずれかの値は無視され、現在値はゼロに設定します。

非対話モードのゲージであり、新しい最大値が INDEFINITE であるなら、これはゲージに範囲の指定がない状態に設定することを意味します。 以前のゲージに明確な範囲が設定されていたならば、グラフ表示はそれに合わせて変化しなければなりません。そして以前の値を破棄して、CONTINUOUS_IDLE を現在値に設定します。 以前のゲージに明確な範囲が設定されていなければ、INDEFINITE を最大値に設定しても効果はありません。

パラメータ:

maxValue - 設定する新しい最大値を渡します。

例外:

IllegalArgumentException - 新しい最大値が不正な場合に throw します。

関連項目:

INDEFINITE, getMaxValue()

getMaxValue

public int getMaxValue()

この Gauge オブジェクトの最大値を返します。

対話モードのゲージならば、最大値は正の整数です。 非対話モードのゲージならば、最大値は正の整数（ゲージには明確な範囲があることを示す）あるいは特別な値である INDEFINITE（ゲージには明確な範囲がないことを示す）のいずれかです。

戻り値:

設定されている最大値または INDEFINITE を返します。

関連項目:

INDEFINITE, setMaxValue(int)

isInteractive

public boolean isInteractive()

Gauge の値をユーザーが変更できるか否かを返します。

戻り値:

ユーザーが変更できる場合は true を、そうでなければ false を返します。