Класс HTMLEditorKit

public class HTMLEditorKit
extends StyledEditorKit
implements Accessible

Компонент Swing JEditorPane поддерживает разные типы содержимого через механизм плагинов, называемый EditorKit. Так как HTML — очень популярный формат содержимого, предусмотрена некоторая поддержка по умолчанию. Эта поддержка обеспечивается этим классом, который поддерживает HTML версии 3.2 (с некоторыми расширениями) и переходит к версии 4.0. Тэг <applet> не поддерживается, но предоставляется некоторая поддержка для тега <object>.

Преследуются несколько целей HTML EditorKit, которые влияют на способ моделирования HTML. Они существенно повлияли на его дизайн.

Поддержка редактирования

Может показаться очевидным, что плагин для JEditorPane должен обеспечивать поддержку редактирования, но этот факт предполагает несколько соображений по проектированию. Существует значительное количество HTML-документов, которые не полностью соответствуют спецификации HTML. Их необходимо в некоторой степени нормализовать для редактирования. Кроме того, пользователи не любят избыточного редактирования структуры, поэтому предпочтительнее использовать традиционные жесты редактирования текста, а не точную структуру, определённую в HTML-документе.

Моделирование HTML обеспечивается классом HTMLDocument. В его документации подробно описано, как моделируется HTML. Поддержка редактирования в значительной степени опирается на пакет text.

Расширяемость/Масштабируемость

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

1. Парсер заменяем. По умолчанию используется парсер Hot Java, который основан на DTD. Можно использовать другой DTD или совершенно другой парсер. Для изменения парсера переопределите метод getParser. Парсер по умолчанию динамически загружается при первом запросе, поэтому файлы класса никогда не будут загружены, если используется альтернативный парсер. Парсер по умолчанию находится в отдельном пакете под названием parser ниже этого пакета.
2. Парсер управляет ParserCallback, который предоставляется HTMLDocument. Для изменения обратного вызова необходимо создать подкласс HTMLDocument и переопределить метод createDefaultDocument для возврата документа, который создаёт другой reader. Reader контролирует структуру документа. Хотя Document по умолчанию поддерживает HTML, ничего не мешает поддержке тегов, не являющихся HTML, которые приводят к альтернативным структурам элементов.
3. Представления моделей по умолчанию предоставляются в виде иерархии реализаций View, поэтому можно легко настроить отображение конкретного элемента или добавить возможности для новых типов элементов, предоставив новые реализации View. Набор представлений по умолчанию предоставляется классом HTMLFactory. Это можно легко изменить, создав подкласс или заменив HTMLFactory и переопределив метод getViewFactory для возврата альтернативной фабрики.
4. Реализации View работают в основном с атрибутами CSS, которые хранятся в представлениях. Это позволяет отображать несколько представлений над той же моделью, которые выглядят существенно по-разному. Это особенно полезно для печати. Для большинства атрибутов HTML атрибуты HTML преобразуются в атрибуты CSS для отображения. Это помогает сделать реализации View более универсальными.

Асинхронная загрузка

Большие документы подразумевают много парсинга и требуют некоторого времени для загрузки. По умолчанию этот набор инструментов создаёт документы, которые будут загружаться асинхронно, если загружены с помощью JEditorPane.setPage. Это контролируется свойством документа. Метод createDefaultDocument можно переопределить для изменения этого. Объединение работы выполняется классом HTMLDocument.HTMLReader. Фактическая работа выполняется классами DefaultStyledDocument и AbstractDocument в пакете text.

Настройка с текущей LAF

HTML предоставляет хорошо известный набор функций без точного указания характеристик отображения. Swing имеет механизм темы для своих реализаций внешнего вида и ощущения. Желательно, чтобы внешний вид и ощущения передавали характеристики отображения в HTML-представления. Например, пользователь с плохим зрением захочет высокий контраст и шрифты больше, чем типичные.

Поддержка этого предоставляется классом StyleSheet. Отображение HTML можно существенно повлиять, установив свойство StyleSheet на EditorKit.

Без потерь

EditorKit имеет возможность чтения и сохранения документов. Обычно пользователи предпочитают, если при этих операциях не происходит потерь данных. Политика HTMLEditorKit будет состоять в том, чтобы хранить не распознанные или не обязательно отображаемые элементы, чтобы их можно было впоследствии вывести. Модель HTML-документа, следовательно, должна содержать всю информацию, обнаруженную при чтении документа. Это в некоторой степени ограничено необходимостью поддержки редактирования (например, иногда необходимо нормализовать неправильные документы). Руководящим принципом является то, что информация не должна теряться, но некоторые элементы могут быть синтезированы для создания более корректной модели или перегруппированы.

Поля

DEFAULT_CSS

public static final String DEFAULT_CSS

Файл таблицы стилей по умолчанию, который настраивает представления тегов.

См. также:

Значения константных полей

BOLD_ACTION

public static final String BOLD_ACTION

Идентификатор действия «Жирный»

См. также:

Значения константных полей

ITALIC_ACTION

public static final String ITALIC_ACTION

Идентификатор действия «Курсив»

См. также:

Значения константных полей

PARA_INDENT_LEFT

public static final String PARA_INDENT_LEFT

Идентификатор действия отступа абзаца влево

См. также:

Значения константных полей

PARA_INDENT_RIGHT

public static final String PARA_INDENT_RIGHT

Идентификатор действия отступа абзаца вправо

См. также:

Значения константных полей

FONT_CHANGE_BIGGER

public static final String FONT_CHANGE_BIGGER

Идентификатор действия увеличения размера шрифта до следующего значения

См. также:

Значения константных полей

FONT_CHANGE_SMALLER

public static final String FONT_CHANGE_SMALLER

Идентификатор действия уменьшения размера шрифта до следующего значения

См. также:

Значения константных полей

COLOR_ACTION

public static final String COLOR_ACTION

Идентификатор действия выбора цвета. Цвет передаётся как аргумент

См. также:

Значения константных полей

LOGICAL_STYLE_ACTION

public static final String LOGICAL_STYLE_ACTION

Идентификатор действия выбора логического стиля. Логический стиль передаётся в качестве аргумента

См. также:

Значения константных полей

IMG_ALIGN_TOP

public static final String IMG_ALIGN_TOP

Выравнивание изображений по верху.

См. также:

Значения константных полей

IMG_ALIGN_MIDDLE

public static final String IMG_ALIGN_MIDDLE

Выравнивание изображений по центру.

См. также:

Значения константных полей

IMG_ALIGN_BOTTOM

public static final String IMG_ALIGN_BOTTOM

Выравнивание изображений по низу.

См. также:

Значения константных полей

IMG_BORDER

public static final String IMG_BORDER

Выравнивание изображений по границе.

См. также:

Значения константных полей

Конструкторы

HTMLEditorKit

public HTMLEditorKit()

Создаёт HTMLEditorKit, создаёт StyleContext и загружает таблицу стилей.

Методы

getContentType

public String getContentType()

Возвращает MIME-тип данных, поддерживаемый этим набором инструментов. Этот набор инструментов поддерживает тип text/html.

Переопределяет:

getContentType в классе DefaultEditorKit

Возвращает:

тип

getViewFactory

public ViewFactory getViewFactory()

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

Переопределяет:

getViewFactory в классе StyledEditorKit

Возвращает:

фабрику

createDefaultDocument

public Document createDefaultDocument()

Создаёт модель хранилища текста, подходящую для данного типа редактора.

Переопределяет:

createDefaultDocument в классе StyledEditorKit

Возвращает:

модель

read

public void read(Reader in,
                 Document doc,
                 int pos)
          throws IOException,
                 BadLocationException

Вставляет содержимое из заданного потока. Если doc является экземпляром HTMLDocument, это будет читать текст HTML 3.2. Вставка HTML в документ, не являющийся пустым, должна быть внутри элемента body. Если вставка не выполняется в body, будет выброшено исключение. При вставке в непустой документ все теги за пределами body (head, title) будут удалены.

Переопределяет:

read в классе DefaultEditorKit

Параметры:

in - поток для чтения

doc - место назначения для вставки

pos - расположение в документе для размещения содержимого

Исключения:

IOException - при любой ошибке ввода/вывода

BadLocationException - если pos представляет недопустимое расположение в документе

RuntimeException - (в конечном итоге BadLocationException) если pos недопустим

insertHTML

public void insertHTML(HTMLDocument doc,
                       int offset,
                       String html,
                       int popDepth,
                       int pushDepth,
                       HTML.Tag insertTag)
                throws BadLocationException,
                       IOException

Вставляет HTML в существующий документ.

Параметры:

doc - документ для вставки

offset - смещение для вставки HTML

popDepth - количество ElementSpec.EndTagTypes для генерации перед вставкой

pushDepth - количество ElementSpec.StartTagTypes с направлением ElementSpec.JoinNextDirection, которое должно быть сгенерировано перед вставкой, но после генерации закрывающих тегов

insertTag - первый тег для начала вставки в документ

Исключения:

RuntimeException - (в конечном итоге BadLocationException) если pos недопустим

BadLocationException

IOException

write

public void write(Writer out,
                  Document doc,
                  int pos,
                  int len)
           throws IOException,
                  BadLocationException

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

Переопределяет:

write в классе DefaultEditorKit

Параметры:

out - поток для записи

doc - источник для записи

pos - расположение в документе для получения содержимого

len - количество для записи

Исключения:

IOException - при любой ошибке ввода/вывода

BadLocationException - если pos представляет недопустимое расположение в документе

install

public void install(JEditorPane c)

Вызывается при установке набора инструментов в JEditorPane.

Переопределяет:

install в классе StyledEditorKit

Параметры:

c - JEditorPane

deinstall

public void deinstall(JEditorPane c)

Вызывается при удалении набора инструментов из JEditorPane. Используется для отмены регистрации любых подключённых слушателей.

Переопределяет:

deinstall в классе StyledEditorKit

Параметры:

c - JEditorPane

setStyleSheet

public void setStyleSheet(StyleSheet s)

Устанавливает набор стилей, используемых для отображения различных элементов HTML. Эти стили задаются в терминах спецификаций CSS. Каждый документ, созданный набором инструментов, будет иметь копию листа, к которой можно добавить стили, специфичные для документа. По умолчанию StyleSheet, указанный, используется всеми экземплярами HTMLEditorKit. Это следует переопределить, чтобы обеспечить более мелкую гранулярность, если необходимо.

getStyleSheet

public StyleSheet getStyleSheet()

Получает набор стилей, в настоящее время используемых для отображения элементов HTML. По умолчанию загружается ресурс, указанный в DEFAULT_CSS, и он используется всеми экземплярами HTMLEditorKit.

getActions

public Action[] getActions()

Возвращает список команд для редактора. Это список команд, поддерживаемых суперклассом, дополненный набором команд, определённых локально для операций со стилями.

Переопределяет:

getActions в классе StyledEditorKit

Возвращает:

список команд

createInputAttributes

protected void createInputAttributes(Element element,
                                     MutableAttributeSet set)

Переопределяет:

createInputAttributes в классе StyledEditorKit

getInputAttributes

public MutableAttributeSet getInputAttributes()

Возвращает набор входных атрибутов, используемых для действий по стилизованному редактированию.

Переопределяет:

getInputAttributes в классе StyledEditorKit

Возвращает:

набор атрибутов

setDefaultCursor

public void setDefaultCursor(Cursor cursor)

Устанавливает курсор по умолчанию.

С:

1.3

getDefaultCursor

public Cursor getDefaultCursor()

Возвращает курсор по умолчанию.

С:

1.3

setLinkCursor

public void setLinkCursor(Cursor cursor)

Устанавливает курсор, который будет использоваться над ссылками.

С:

1.3

getLinkCursor

public Cursor getLinkCursor()

Возвращает курсор, который используется над гиперссылками.

С:

1.3

isAutoFormSubmission

public boolean isAutoFormSubmission()

Указывает, обрабатывается ли автоматическая отправка формы HTML или срабатывает только FormSubmitEvent.

Возвращает:

true, если обработка отправки html-формы выполняется автоматически, иначе false.

С момента:

1.5

См. также:

setAutoFormSubmission(boolean)

setAutoFormSubmission

public void setAutoFormSubmission(boolean isAuto)

Указывает, обрабатывается ли отправка html-формы автоматически или срабатывает только FormSubmitEvent. По умолчанию установлено значение true.

С момента:

1.5

См. также:

isAutoFormSubmission(), FormSubmitEvent

clone

public Object clone()

Создаёт копию набора редактирования.

Переопределяет:

clone в классе StyledEditorKit

Возвращает:

копию

См. также:

Cloneable

getParser

protected HTMLEditorKit.Parser getParser()

Получить парсер для чтения потоков HTML. Это можно переопределить, чтобы использовать другой парсер. По умолчанию реализация загружается динамически, чтобы избежать накладных расходов при загрузке по умолчанию, если он не используется. По умолчанию парсер - HotJava парсер, использующий HTML 3.2 DTD.

getAccessibleContext

public AccessibleContext getAccessibleContext()

Возвращает AccessibleContext, связанный с этим набором редактирования

Определено в:

getAccessibleContext в интерфейсе Accessible

Возвращает:

AccessibleContext, связанный с этим набором редактирования

С момента:

1.4