Класс 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 и другие подобные элементы управления могут потенциально использоваться для отображения огромного количества данных, создание фактической ячейки для каждого элемента в элементе управления нецелесообразно. Мы представляем чрезвычайно большие наборы данных, используя только очень мало ячеек. Каждая ячейка "перерабатывается" или повторно используется. Вот что мы подразумеваем, когда говорим, что эти элементы управления виртуализированы.

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

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

Ячейка устанавливает focusTraversable в false.

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

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

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

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

 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;
 }

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

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

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

Другой подход к первому примеру выше (форматирование списка чисел) заключался бы в использовании стилей. Предположим, у вас есть ObservableList чисел для отображения в ListView и вы хотите сделать все отрицательные значения красными, а все положительные или нулевые — черными. Один из способов добиться этого — использовать пользовательскую фабрику ячеек, которая изменяет стиль ячейки в зависимости от того, отрицательно ли значение. Это так же просто, как добавить код для проверки, отрицательно ли число в ячейке, и добавить стиль «отрицательный». Если число не отрицательное, строка «отрицательный» должна быть удалена. Этот подход позволяет определить цвета из 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() — идеальное время для изменения визуальных элементов ячейки. Например (и обратите внимание, что этот пример более подробно описан в javadoc для элементов управления пользовательского интерфейса 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() состоянии редактирования, на этой ячейке ничего не произойдёт.