Класс Cell<T>

public class Cell<T> extends Labeled

API ячейки используется для виртуализированных элементов управления, таких как ListView, TreeView и TableView. Ячейка — это Labeled Control и используется для отрисовки одной "строки" внутри ListView, TreeView или TableView. Ячейки также используются для каждой отдельной "ячейки" внутри TableView (т.е. каждого пересечения строки/столбца). Более подробную информацию см. в JavaDoc для каждого элемента управления отдельно.

Каждая ячейка связана с одним элементом данных (представленным свойством item). Ячейка отвечает за отображение этого элемента и, при необходимости, за редактирование элемента. Элемент в ячейке может быть представлен текстом или каким-либо другим элементом управления, например, CheckBox, ChoiceBox или любым другим Node, например, HBox, GridPane или даже Rectangle.

Поскольку TreeView, ListView, TableView и другие подобные элементы управления могут потенциально использоваться для отображения огромного количества данных, создание фактической ячейки для каждого элемента в элементе управления нецелесообразно. Мы представляем очень большие наборы данных, используя лишь очень немного ячеек. Каждая ячейка "переиспользуется". Именно это мы подразумеваем, когда говорим, что эти элементы управления виртуализированы.

Поскольку Cell является Control, он по сути является "моделью". Его Skin отвечает за определение внешнего вида и макета, а Behavior — за обработку всех событий ввода и использование этой информации для изменения состояния Control. Кроме того, ячейка стилизуется из CSS, как и любой другой Control. Однако для большинства случаев использования ячейки реализовывать Skin необязательно. Это связано с тем, что можно установить фабрику ячеек — это подробно описано ниже.

Поскольку наиболее распространенным случаем использования ячеек является отображение текста пользователю, этот случай специально оптимизирован внутри ячейки. Это делается путем расширения Cell от Labeled. Это означает, что подклассы Cell должны только установить свойство text, а не создавать отдельный Label и устанавливать его в ячейку. Однако в ситуациях, когда требуется что-то большее, чем просто текст, можно разместить любой Node в свойстве ячейки graphic. Несмотря на термин, графикой может быть любой узел, и он будет полностью интерактивным. Например, ListCell можно настроить с Button в качестве графики. Текст кнопки можно затем связать со свойством ячейки item. Таким образом, всякий раз, когда изменяется элемент в ячейке, текст кнопки автоматически обновляется.

Cell устанавливает focusTraversable в false.

Фабрики ячеек

По умолчанию представление ячейки item зависит от того, как рендерить различным виртуализированным контейнерам. Например, по умолчанию ListView преобразует элемент в строку и вызовет Labeled.setText(java.lang.String) с этим значением. Если вы хотите специализировать ячейку, используемую для ListView (например), то необходимо предоставить реализацию обратного вызова cellFactory, определенного в ListView. Аналогичный API существует для большинства элементов управления, использующих ячейки (например, TreeView, TableView, TableColumn и ListView.

Фабрика ячеек вызывается платформой всякий раз, когда она определяет, что требуется создать новую ячейку. Например, предположим, что ваш ListView содержит 10 миллионов элементов. Создание всех 10 миллионов ячеек было бы чрезмерно затратно. Поэтому вместо этого реализация ListView skin может создать только достаточно ячеек, чтобы заполнить визуальное пространство. Если размер ListView увеличится, система определит, что ей нужно создать дополнительные ячейки. В этом случае она вызовет обратный вызов cellFactory (если он предоставлен), чтобы создать реализацию Cell, которая должна быть использована. Если фабрика ячеек не предоставлена, будет использоваться встроенная реализация по умолчанию.

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

 public class MoneyFormatCell extends ListCell<Number> {

     public MoneyFormatCell() {    }

     @Override protected void updateItem(Number item, boolean empty) {
         // calling super here is very important - don't skip this!
         super.updateItem(item, empty);

         // format the number as if it were a monetary value using the
         // formatting relevant to the current locale. This would format
         // 43.68 as "$43.68", and -23.67 as "-$23.67"
         setText(item == null ? "" : NumberFormat.getCurrencyInstance().format(item));

         // change the text fill based on whether it is positive (green)
         // or negative (red). If the cell is selected, the text will
         // always be white (so that it can be read against the blue
         // background), and if the value is zero, we'll make it black.
         if (item != null) {
             double value = item.doubleValue();
             setTextFill(isSelected() ? Color.WHITE :
                 value == 0 ? Color.BLACK :
                 value < 0 ? Color.RED : Color.GREEN);
         }
     }
 }

Этот класс можно затем использовать внутри ListView следующим образом:

 ObservableList<Number> money = ...;
 final ListView<Number> listView = new ListView<Number>(money);
 listView.setCellFactory(new Callback<ListView<Number>, ListCell<Number>>() {
     @Override public ListCell<Number> call(ListView<Number> list) {
         return new MoneyFormatCell();
     }
 });

В этом примере создается анонимный внутренний класс, который просто возвращает экземпляры MoneyFormatCell всякий раз, когда он вызывается. Класс MoneyFormatCell расширяет ListCell, переопределяя метод updateItem. Этот метод вызывается всякий раз, когда изменяется элемент в ячейке, например, когда пользователь прокручивает ListView или изменяется содержимое базовой модели данных (и ячейка используется для представления другого элемента в ListView). Из-за этого нет необходимости управлять связями — просто реагируйте на изменения элементов, когда происходит этот метод. В приведенном выше примере всякий раз, когда изменяется элемент, мы обновляем свойство текста ячейки и также изменяем заполнение текста, чтобы убедиться, что мы получаем правильные визуальные эффекты. Кроме того, если ячейка "пустая" (то есть она используется для заполнения пространства в ListView, но не имеет связанных с ней данных), то мы просто используем пустую строку.

Обратите внимание, что существуют дополнительные методы с префиксом "update", которые могут представлять интерес, поэтому обязательно внимательно прочитайте документацию API для ячейки и подклассов ячейки.

Конечно, мы также можем использовать API связывания вместо переопределения методов "update". Ниже приведен очень тривиальный пример того, как это можно реализовать.

 public class BoundLabelCell extends ListCell<String> {

     public BoundLabelCell() {
         textProperty().bind(itemProperty());
     }
 }
 

Основные цели проектирования

• Высокая эффективность во времени и памяти для больших наборов данных
• Простота создания и использования библиотек для пользовательских ячеек
• Простота настройки внешнего вида ячеек
• Простота настройки форматирования отображения (12,34 как $12,34 или 1234% и т. д.)
• Простота расширения для пользовательских визуальных эффектов
• Простота создания "панелей" данных для визуализации
• Простота анимации размера ячейки или других свойств

Основные варианты использования

Ниже приведены несколько ключевых вариантов использования, используемых для разработки API ячеек, вместе с примерами кода, демонстрирующими, как эти варианты использования реализуются с помощью этого API. Это отнюдь не окончательный список поддерживаемых возможностей или функций, а скорее руководство по использованию API ячеек. Приведенные ниже примеры сосредоточены на ListView, но та же философия применима к TreeCells или другим типам ячеек.

Изменение цветов ячейки

Это должно быть чрезвычайно просто в JavaFX. Каждая ячейка может быть стилизована непосредственно из CSS. Например, если вы хотите изменить фоновый цвет каждой ячейки в ListView на БЕЛЫЙ, вы можете сделать следующее в CSS:

 .list-cell {
   -fx-padding: 3 3 3 3;
   -fx-background-color: white;
 }

Если вы хотите установить цвет выбранных ячеек ListView в синий, вы можете добавить это в свой CSS-файл:

 .list-cell:selected {
   -fx-background-color: blue;
 }

Большинство реализаций Cell расширяют IndexedCell вместо Cell. IndexedCell добавляет два других псевдокласса состояния: "odd" и "even". С помощью этого вы можете получить чередование строк, выполнив что-то вроде этого в файле CSS:

 .list-cell:odd {
   -fx-background-color: grey;
 }

Каждый из этих примеров не требует изменений кода. Просто обновите свой CSS-файл, чтобы изменить цвета. Вы также можете использовать псевдоклассы "hover" и другие псевдоклассы в CSS так же, как и с другими элементами управления.

Другой подход к первому примеру выше (форматирование списка чисел) заключался бы в использовании стилей классов. Предположим, у вас есть ObservableList чисел для отображения в ListView и вы хотите сделать цвет всех отрицательных значений красным, а всех положительных или нулевых значений черным. Один из способов достижения этого — использование пользовательской cellFactory, которая изменяет styleClass ячейки в зависимости от того, является ли значение отрицательным или положительным. Это так же просто, как добавление кода для проверки, является ли число в ячейке отрицательным, и добавление styleClass "negative". Если число не отрицательно, строка "negative" должна быть удалена. Этот подход позволяет определять цвета из CSS, что позволяет легко настраивать их. Затем в файле CSS будет что-то вроде следующего:

 .list-cell {
   -fx-text-fill: black;
 }

 .list-cell .negative {
   -fx-text-fill: red;
 }

Редактирование

Большинство виртуализированных элементов управления, которые используют архитектуру ячеек (например, ListView, TreeView, TableView и TreeTableView) поддерживают возможность редактирования значений непосредственно в ячейке. Подробнее о специфике элементов управления см. в разделе "редактирование" в документации по классам для указанных выше элементов управления. Остальная часть этого раздела будет посвящена некоторым нюансам редактирования с помощью ячеек.

Общие этапы редактирования следующие (в качестве примера используется элемент управления ListView, но аналогичный API существует для всех упомянутых выше элементов управления, и процесс в целом одинаков):

1. Пользователь запрашивает режим редактирования ячейки (через команды клавиатуры или мыши), или разработчик запрашивает, чтобы ячейка перешла в режим редактирования (вызвав метод, такой как метод ListView edit). Примечание: Если пользователь дважды щелкает или выполняет соответствующую команду клавиатуры для начала редактирования, то он фактически вызывает соответствующий метод редактирования для элемента управления (т.е. метод входа для редактирования, инициированного пользователем, и инициированного разработчиком, одинаковый).
2. Каждая ячейка в видимой области элемента управления уведомляется о том, что текущий editing cell изменился, и проверяет, является ли это она сама. В этот момент может произойти одно из трех событий:
   1. Если индекс редактирования совпадает с индексом ячейки, на этой ячейке будет вызван метод startEdit(). Некоторые указания:
      1. Рекомендуется, чтобы подклассы Cell переопределяли метод startEdit() для обновления визуального представления ячейки при входе в состояние редактирования. Однако важно, чтобы подклассы, переопределяющие метод startEdit(), продолжали вызывать super.startEdit(), чтобы родительские классы могли обновлять дополнительное состояние, необходимое для успешного редактирования.
      2. В методе startEdit() — идеальное время для изменения визуального представления ячейки. Например (и обратите внимание, что этот пример более подробно рассмотрен в документации UI-элемента управления для ListView и т.д.), можно установить свойство Labeled.graphicProperty() ячейки в поле TextField и установить свойство Labeled.textProperty() в значение null. Это позволит конечным пользователям вводить данные и вносить изменения в вашу модель данных.
      3. Когда пользователь закончил редактирование, он захочет подтвердить или отменить изменения. Вы несете ответственность за обработку этого (например, используя клавишу Enter для commit the edit и клавишу ESC для cancel the edit). Вы делаете это, прикрепляя соответствующие обработчики событий к узлам, отображаемым во время редактирования.
   2. Если индекс редактирования не совпадает с индексом ячейки и если ячейка в данный момент находится в состоянии editing state, на этой ячейке будет вызван метод cancelEdit(). Как и в случае с методом startEdit(), вам следует переопределить этот метод для очистки визуального представления ячейки (и, скорее всего, вернуть свойство Labeled.graphicProperty() к значению null и установить свойство Labeled.textProperty() к его (возможно, новому) значению). Опять же, обязательно вызывайте super.cancelEdit(), чтобы убедиться, что все состояние обновлено правильно.
   3. Если индекс редактирования не совпадает с индексом ячейки и если ячейка в данный момент не находится в состоянии редактирования isEditing(), ничего не произойдет с этой ячейкой.