спецификации, руководства, описания, API

`JSpinner` - Простой Контейнер Последовательности

Этот документ описывает новый компонент Swing, JSpinner.

Один из обычно требуемых новых компонентов Swing является прядильщиком - однострочное поле ввода, которое позволяет пользователю выбирать число или объектное значение от упорядоченного набора. Прядильщики обычно обеспечивают пару крошечных кнопок стрелки для того, чтобы ступить через возможные значения,/клавиши со стрелкой вниз также цикл через значения. Пользователя можно также разрешить типу a (юридическое) значение непосредственно в прядильщика. Хотя поля комбинированного списка обеспечивают подобную функциональность, прядильщики иногда предпочитаются, потому что они не требуют выпадающего списка, который может затенить важные данные.

Отчет bugtraq, который соответствует этому изменению: 4290529.

Короткий Каталог Прядильщиков

Прядильщики распространены в современных GUI. Вот некоторые примеры от некоторого популярного взгляда и чувств и от OpenWindows:


Windows	CDE/Motif	JLF	Мак Акуа	OpenWindows

Все прядильщики поставляют очень простое поведение: щелчок по кнопкам стрелки изменяет полевое значение и, когда у прядильщика есть фокус, клавиатура вверх и вниз по клавишам со стрелками делают то же самое. В некоторых приложениях отключаются прядильщики или кнопка стрелки вниз, когда верхний или более низкий предел прядильщика был достигнут в других случаях, прядильщик только сбрасывает его значение к противоположному экстремальному значению.

`JSpinner`, `SpinnerModel`, `SpinnerListModel`

JSpinner class является простым контейнером Swing, который управляет тремя дочерними элементами: две кнопки стрелки и единственный компонент, названный редактором, который выводит на экран значение прядильщика. Значение, выведенное на экран прядильщиком, инкапсулируется моделью последовательности объектов, названных a SpinnerModel.

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

SpinnerModel интерфейс подобен ListModel - они оба представляют последовательность значения - однако есть некоторые важные различия:

Модель не поддерживает произвольный доступ к элементам последовательности. Только три значения последовательности доступны за один раз: ток, следующий и предыдущий.
Число элементов последовательности не обязательно ограничивается, таким образом, нет никакого возврата длины последовательности size метод.
Свойство значения модели является чтением-записью, в отличие от элементов a ListModels последовательность, которые только для чтения. Это различие отражает различные роли JList и JSpinner. Прежний был разработан, чтобы упростить выбор того или большего количества элементов от списка и последнего для того, чтобы ввести единственное значение непосредственно.

Отношение между JSpinner и его модель проста. Компонент редактора контролирует модель с a ChangeListener и всегда выводит на экран объект, возвращенный SpinnerModel.getValue(). Вверх и вниз по кнопкам стрелки обновляют значение, вызывая setValue(getNextValue()) или setValue(getPreviousValue()) соответственно. getNextValue и getPreviousValue возврат методов null когда конец или начало последовательности был достигнут, таким образом, действия кнопки стрелки должны проверить на null прежде, чем обновить значение моделей. Если редактор является перезаписываемым полем некоторого вида, это ответственно за то, что соблюдало ограничения, определенные моделью или обработало IllegalArgumentException брошенный setValue для недопустимых значений.

SpinnerListModel оказывает поддержку для двух общих изменчивых типов последовательности: java.util.List, и массив объектов. Например создать a JSpinner это позволяет пользователю выбирать день недели в локали значения по умолчанию, которую можно было записать:

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

В дополнение к инициализации model свойство прядильщика, эти конструкторы создают компонент редактора, который выводит на экран SpinnerModel's value и может использоваться, чтобы изменить это. Защищенный JSpinner.createEditor метод используется для этого и, по умолчанию, он создает a JFormattedTextField это было сконфигурировано, чтобы вывести на экран модель.

Чтобы найти или инициализировать текущую стоимость прядильщиков, можно или использовать модели value свойство или использование удобство JSpinner value свойство, которое только делегирует к модели. Например, используя прядильщика, сконфигурированного в примере выше, следующие два оператора эквивалентны:

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

Установка значения прядильщика подобна. Попытки установить SpinnerModel оцените объекту, что модель не поддерживает причину IllegalArgumentException быть брошенным.

Даты и числа являются двумя из наиболее распространенных приложений для компонента прядильщика. Упростить вращение этих типов, два дополнительный SpinnerModel классы реализации обеспечиваются: SpinnerDateModel и SpinnerNumberModel.

`SpinnerDateModel`

Один из наиболее популярных способов использования прядильщика должен сжато представить доступную для редактирования дату. Вот простой пример создания a JSpinner это позволяет пользователю входить (полностью локализованный) дата:

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

В этом примере, JSpinner конструктор создал a JFormattedTextField редактор это конфигурируется для того, чтобы отредактировать даты и это добавило a ChangeListener к SpinnerDateModel сохранить editor и модель в синхронизации.

Вот SpinnerDateModel API. Мы добавили три новых свойства чтения/записи: start, end, и stepSize и только для чтения date свойство, которое возвращает бросок значения моделей a 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 свойство должно быть одним из java.util.Calendar константы, которые определяют поле в пределах a Calendar. getNextValue и getPreviousValue методы изменяют дату вперед или назад этим количеством. Например, если stepSize Calendar.DAY_OF_WEEK, тогда nextValue производит a Date это спустя 24 часа после тока value, и previousValue производит a Date это 24 часами ранее.

Юридические значения для 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 свойство, основанное на текстовой позиции курсора. Например, если курсор перемещается в подполе месяца редактора тогда incrementSize был бы изменен на Calendar.DAY_OF_MONTH.

SpinnerNumberModel

Прядильщики часто используются, чтобы представить доступные для редактирования целые числа и вещественные числа, которые представляют все от температуры до курсов акций. SpinnerNumberModel оказывает основную поддержку для всего основного Java Number типы, от Byte к Double.

Чтобы создать прядильщика, который позволяет пользователю выбирать реальное кратное число 1/8 между 0.0 и 1000.0 с начальным значением 500.0, можно было записать:

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

В этом примере, JSpinner конструктор создал a JFormattedTextField редактор это конфигурируется для того, чтобы отредактировать вещественные числа и это добавило a ChangeListener к SpinnerNumberModel сохранить editor и модель в синхронизации.

Вот сводка SpinnerNumberModel API. Мы добавили три новых свойства чтения/записи: minimum, maximum, и stepSize и только для чтения number свойство, которое возвращает модели value бросок к a 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 свойство только определяет, сколько добавить или вычесть из value вычислить nextValue или previousValue.

Сводка API Прядильщика

Поддержка прядильщиков, добавленных шесть классов и один интерфейс (SpinnerModel) к javax.swing пакет:

Дополнительно, SpinnerUI был добавлен к javax.swing.plaf пакет и BasicSpinnerUI к javax.swing.plaf.basic пакет:

Свяжитесь с Нами

JSpinner - Простой Контейнер Последовательности