`JSpinner` - 単純なシーケンスコンテナ

このドキュメントでは、新しい Swing コンポーネントである JSpinner について説明します。

もっとも多く作成の要求があった Swing コンポーネントの 1 つに、スピナーがあります。これは、ユーザーが順序付けられた集合から数値またはオブジェクトを選択できるようにする単一行の入力フィールドです。スピナーには通常、選択可能な値を段階的に表示するための一組の小さな矢印型ボタンが提供され、上向きと下向きの矢印キーでも値を循環して表示できます。ユーザーがスピナーに直接 (有効な) 値を入力することもできます。コンボボックスは類似の機能を提供しますが、重要なデータを覆い隠してしまうドロップダウンリストを必要としないため、スピナーのほうが好まれる場合があります。

この変更に関連するバグ追跡レポート: 4290529.

スピナーのカタログ

スピナーは、最新の GUI で一般的なものです。次に、いくつかの一般的な Look & Feel と OpenWindows からの例を示します。


Windows	CDE/Motif	JLF	Mac Aqua	OpenWindows

これらのスピナーはすべて、非常に単純な動作を行います。スピナーにフォーカスがあるときに矢印ボタンをクリックすると、フィールドの値が変わります。キーボードの上向き矢印キーと下向き矢印キーでも同じ結果になります。アプリケーションによっては、スピナーの値が上限または下限に達すると、上向きまたは下向き矢印ボタンが無効になったり、その値が反対の極限値にリセットされたりします。

`JSpinner`, `SpinnerModel`, `SpinnerListModel`

JSpinner クラスは、3 つの子を管理する単純な Swing コンテナです。子とは、2 つの矢印ボタンと、スピナーの値を表示するためのエディタと呼ばれる 1 つのコンポーネントです。スピナーに表示される値は、SpinnerModel と呼ばれるオブジェクトのシーケンスから構成されるモデルによってカプセル化されます。

public interface SpinnerModel {
    Object getValue();
    void setValue(Object);
    Object getNextValue();
    Object getPreviousValue();
    void addChangeListener(ChangeListener x);
    void removeChangeListener(ChangeListener x);}

SpinnerModel インタフェースは、ListModel と似ており、両方とも値のシーケンスを表現しますが、重要な相違点がいくつかあります。

モデルは、一連の要素へのランダムなアクセスはサポートしない。現在、次、前という 3 つのシーケンス値にのみ同時にアクセスできる。
シーケンスな要素数を必ずしもバインドする必要がないので、size メソッドからシーケンスの長さは返されない。
モデルの値のプロパティーは読み取り/書き込み両用であり、読み取り専用の ListModels シーケンスの要素とは異なる。この違いが、JList と JSpinner の役割の違いを反映している。前者はリストからの 1 つ以上の項目の選択を単純化するために設計されたのに対し、後者は単一の値を直接入力するために設計された。

JSpinner とそのモデルとの関係は単純です。エディタコンポーネントは ChangeListener 経由でモデルを監視し、SpinnerModel.getValue() によって返されたオブジェクトを常に表示します。上向きおよび下向きの矢印ボタンは、それぞれ setValue(getNextValue()) または setValue(getPreviousValue()) を呼び出すことで値を更新します。シーケンスの最後または先頭に達したときに getNextValue および getPreviousValue メソッドは null を返すので、矢印ボタンのアクションでは、モデルの値を更新する前に null をチェックする必要があります。エディタがある種の書き込み可能なフィールドの場合は、モデルに定義された制約を尊重すること、または無効な値に対して setValue によってスローされた IllegalArgumentException を処理することが、エディタの役割になります。

SpinnerListModel では、java.util.List およびオブジェクト配列という、2 つの一般的な可変のシーケンス型がサポートされます。デフォルトのロケールでユーザーが曜日を選択できるようにする JSpinner を作成する例は、次のようになります。

    String[] days = new DateFormatSymbols().getWeekdays();
    SpinnerModel model = new SpinnerListModel(days);
    JSpinner spinner = new JSpinner(model);

スピナーの model プロパティーを初期化することに加えて、これらのコンストラクタが、SpinnerModel の value を表示するエディタコンポーネントを作成します。また、コンストラクタを使用して value を変更できます。デフォルトでは、このために protected JSpinner.createEditor メソッドが使用され、このメソッドが、モデルを表示するために構成された JFormattedTextField を作成します。

スピナーの現在値を検出または初期化するには、モデルの value プロパティーを使用するか、または、モデルに委譲されたばかりの、便利な JSpinner value プロパティーを使用することができます。たとえば、上の例で構成されたスピナーを使用すると、次の 2 つの文は同等です。

    String selectedDay = spinner.getModel().getValue().toString();
    String selectedDay = spinner.getValue().toString();

スピナーの値の設定は似ています。モデルがサポートしないオブジェクトに SpinnerModel の値を設定しようとすると、IllegalArgumentException がスローされます。

日付と数値は、スピナーのコンポーネントにもっとも一般的に適用される 2 つです。これらの型のスピナー化を単純にするために、SpinnerDateModel と SpinnerNumberModel の、2 つの SpinnerModel 実装クラスが追加されました。

`SpinnerDateModel`

スピナーのもっとも一般的な使用法の 1 つが、編集可能な日付をコンパクトに提示することです。次に、ユーザーが完全にローカライズされた日付を入力できる JSpinner の作成例を示します。

    SpinnerDateModel model = new SpinnerDateModel();
    JSpinner spinner = new JSpinner(model);
    Date value = model.getDate();

この例で、JSpinner コンストラクタは、日付を編集するように構成される JFormattedTextField エディタを作成し、ChangeListener を SpinnerDateModel に追加して、editor とモデルの同期を保ちます。

ここで、SpinnerDateModel API を示します。この API には、start、end、および stepSize の 3 つの新しい読み取り/書き込み両用プロパティーと、Date にキャストする value を返す読み取り専用の date プロパティーが追加されました。

public class SpinnerDateModel extends AbstractSpinnerModel {
    public SpinnerDateModel(Date value, Comparable start, Comparable end, int stepSize)
    public SpinnerDateModel()
    public void setStart(Comparable start)
    public Comparable getStart()
    public void setEnd(Comparable end)
    public Comparable getEnd()
    public Object getNextValue()
    public Object getPreviousValue() 
    public Date getDate()
    public Object getValue()
    public void setValue(Object value)}

上限または下限のないことを示すために、startDate プロパティーおよび endDate プロパティーを null にすることができます。引数を指定しない SpinnerDateModel コンストラクタの場合は、開始日と終了日の両方を null に初期化し、モデルの最初の日付は現在の日付です。

stepSize プロパティーの値は、Calendar 内のフィールドを指定する java.util.Calendar 定数のいずれかである必要があります。getNextValue メソッドと getPreviousValue メソッドは、この定数に基づいて日付を前後に変更します。たとえば、stepSize が Calendar.DAY_OF_WEEK の場合、nextValue は現在の value の 24 時間後の Date を生成し、previousValue は 24 時間前の Date を生成します。

stepSize の正当な値は次のとおりです。

Calendar.ERA
Calendar.YEAR
Calendar.MONTH
Calendar.WEEK_OF_YEAR
Calendar.WEEK_OF_MONTH
Calendar.DAY_OF_MONTH
Calendar.DAY_OF_YEAR
Calendar.DAY_OF_WEEK
Calendar.DAY_OF_WEEK_IN_MONTH
Calendar.AM_PM
Calendar.HOUR
Calendar.HOUR_OF_DAY
Calendar.MINUTE
Calendar.SECOND
Calendar.MILLISECOND

デフォルトの SpinnerDateModel editor は、テキストのカーソル位置に基づいて stepSize プロパティーを調節します。たとえば、カーソルがエディタの month サブフィールドに移動した場合は、incrementSize が Calendar.DAY_OF_MONTH に変更されます。

SpinnerNumberModel

スピナーはしばしば、気温から株価までのあらゆる数値を表す、編集可能な整数および実数を提示するために使用されます。SpinnerNumberModel では、Byte から Double までの基本的なすべての Java の Number 型を基本的にサポートします。

初期値を 500.0 にして、0.0 から 1000.0 の間で 1/8 の実数の倍数をユーザーが選択できるようにするスピナーを作成するには、次のようにコーディングします。

    SpinnerNumberModel model = new SpinnerNumberModel(500.0, 0.0, 1000.0, 0.625);
    JSpinner spinner = new JSpinner(model);
    double value = model.getNumber().doubleValue();

この例で、JSpinner コンストラクタは、実数を編集するように構成される JFormattedTextField エディタを作成し、ChangeListener を SpinnerNumberModel に追加して、editor とモデルの同期を保ちます。

ここで、SpinnerNumberModel API について簡単にまとめます。この API には、minimum、maximum、および stepSize の 3 つの新しい読み取り/書き込み両用プロパティーと、Number にキャストする value を返す読み取り専用の number プロパティーが追加されました。

public class SpinnerNumberModel extends AbstractSpinnerModel {
    public SpinnerNumberModel(Number value, Comparable minimum, Comparable maximum, Number stepSize)
    public SpinnerNumberModel(int value, int minimum, int maximum, int stepSize)
    public SpinnerNumberModel(double value, double minimum, double maximum, double stepSize)
    public SpinnerNumberModel()
    public void setMinimum(Comparable minimum)
    public Comparable getMinimum()
    public void setMaximum(Comparable maximum)
    public Comparable getMaximum()
    public void setStepSize(Number stepSize)
    public Number getStepSize()
    public Object getNextValue()
    public Object getPreviousValue()
    public Number getNumber()
    public Object getValue()
    public void setValue(Object value)}

SpinnerDateModel に関しては、minimum および maximum プロパティーが、それより大きな値または小さな値がないことを示すために、null になる可能性もあります。stepSize プロパティーには、nextValue または previousValue を計算するために value と加算または減算する値を指定します。

スピナー API のサマリー

スピナーのサポートにあたって、次の 6 つのクラスと 1 つのインタフェース (SpinnerModel) が javax.swing パッケージに追加されました。

また、SpinnerUI が javax.swing.plaf パッケージに、BasicSpinnerUI が javax.swing.plaf.basic パッケージに追加されました。

連絡先

JSpinner - 単純なシーケンスコンテナ