Помощник поля

Часто от пользователя ожидается ввод текстовой информации в простое поле, такое как текстовое поле или поле со списком. Хотя исходный код приложения, который заполняет эти поля, обычно намного проще, чем исходный код, который заполняет сложный управляющий элемент, такой как таблица или дерево, но эти "простые" поля, как правило, более обременительны для пользователя. Пользователь должен знать, какие поля требуют ввода, содержит ли поле верные данные, и какие варианты ожидаются. Помощник поля JFace предоставляет классы для помощи пользователю при вводе данных.

Пакет org.eclipse.jface.fieldassist предоставляет помощь двумя способами. Поддержка оформленных полей позволяет добавлять значки, которые показывают пользователю состояние поля. Поддержка вариантов содержимого позволяет предоставлять пользователю выбор содержимого поля с помощью всплывающего помощника.

Оформленные поля

Оформленные поля позволяют размещать рядом с собой специальные изображения, определенные в окне диалога. Значки оформления могут быть размещены рядом с одним из четырех углов поля. Как и в программах просмотра, оформленные поля предназначены для того, чтобы добавить функциональность к управляющим элементам SWT, продолжая при этом обеспечивать базовые функции управления. API DecoratedField позволяет добавлять, скрывать и показывать значки оформления рядом с полем. Доступ к базовым функциям предоставляется таким образом, что вы можете использовать существующий API SWT, например, для установки содержимого, цвета или шрифта.

Создание оформленных полей

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

...
// Создание текстового поля
Text text = new Text(parent, SWT.BORDER);
text.setText("некоторый текст");
...

Для того чтобы оформить это поле, оно должно быть создано следующим образом:

...
// Создание оформленного поля для управляющего элемента текста
DecoratedField field = new DecoratedField(parent, SWT.BORDER, new TextControlCreator());
Text text = (Text)field.getControl();
text.setText("некоторый текст");
...

Тот же предок и те же биты стиля, которые используются для создания основного управляющего элемента, применяются и для создания оформленного поля. Главное различие в коде состоит в том, что предоставляется экземпляр IControlCreator, который создает особого рода управляющий элемент, необходимый в поле. Для текстовых полей можно использовать класс TextControlCreator, чтобы создать управляющий элемент. Однако, есть возможность также реализовать IControlCreator для создания управляющего элемента другого вида внутри поля, такого как поле со списком или поле прокрутки.

Использование оформления

После создания оформленного поля к нему могут быть добавлены значки в одном из четырех расположений. Для того чтобы указать, в каком месте должен быть помещен значок оформления, применяются константы расположения SWT. Для добавления значка оформления необходимо указать FieldDecoration, который определяет изображение значка, а также (необязательно) текст описания, который может быть показан при наведении курсора мыши на значок.

...
// Создать оформление поля и добавить его к полю
Image image = JFaceResources.getImage("myplugin.specialimage");
FieldDecoration mySpecialDecoration = new FieldDecoration(image, "Это особое поле");
field.addFieldDecoration(mySpecialDecoration, SWT.TOP | SWT.LEFT, false);
...

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

...
// Произошло некоторое событие, в результате которого мы хотим скрыть значок
field.hideDecoration(mySpecialDecoration);
...

Если изображение или описание значка оформления изменено, необходимо известить поле о том, что значок должен быть повторно нарисован.

...
// По некоторой причине поле поменяло свой статус
mySpecialDecoration.setDescription("This field is extra-special");
field.updateDecoration(mySpecialDecoration);
...

Разметка оформленных и простых полей

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

...
// Создание текстового поля
Text text = new Text(parent, SWT.BORDER);
text.setText("некоторый текст");
// Установка данных разметки
GridData data = new GridData(IDialogConstants.ENTRY_FIELD_WIDTH, SWT.DEFAULT);
text.setLayoutData(data); 
...

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

...
// Создание оформленного поля для элемента управления текста
DecoratedField field = new DecoratedField(main, SWT.BORDER, new TextControlCreator());
Text text = (Text)field.getControl();
text.setText("некоторый текст");
// Установка данных разметки
GridData data = new GridData(IDialogConstants.ENTRY_FIELD_WIDTH + 
   FieldDecorationRegistry.getDefault().getMaximumDecorationWidth(), SWT.DEFAULT);
field.getLayoutControl().setLayoutData(data); 
...

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

Реестр значков оформления поля

Реестр значков оформления поля позволяет регистрировать и получать доступ к ним с помощью строкового ИД. Это предоставляет удобный способ обращения к значкам оформления, используемым в приложении. Можно определить API, экспортирующий ИД значков для доступа к ним других модулей. Заметьте, что регистрация значков оформления не управляет жизненным циклом изображений в этих значках. Управлять этими изображениями может приложение. Например, для регистрации и управления жизненным циклом изображения можно использовать запись реестра для изображения JFace. Кроме того, приложение может создать изображение по требованию и удалить его, когда оно больше не требуется. В javadoc для методов регистрации в FieldDecorationRegistry дается объяснение различных способов указания изображений при регистрации значка оформления.

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

...
// Создание текстового поля
Text text = new Text(parent, SWT.BORDER);
text.setText("некоторый текст");
// Установка данных разметки
GridData data = new GridData();
data.horizontalAlignment = SWT.FILL;
data.horizontalIndent = FieldDecorationRegistry.getDefault().getMaximumDecorationWidth();
text.setLayoutData(data); 
...

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

...
// Создание оформленного поля со значком обязательного поля
DecoratedField field = new DecoratedField(main, SWT.BORDER, new TextControlCreator());
FieldDecoration requiredFieldIndicator = FieldDecorationRegistry.getDefault().
   getFieldDecoration(FieldDecorationRegistry.DEC_REQUIRED);
field.addDecoratedField(requiredFieldIndicator, SWT.BOTTOM | SWT.LEFT, false);
...

Варианты содержимого

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

...
autoActivationCharacters = new char[] { '#', '(' };
keyStroke = KeyStroke.getInstance("Ctrl+Space");
// предположим, что myTextControl уже как-то создан
ContentProposalAdapter adapter = new ContentProposalAdapter(
	myTextControl, new TextContentAdapter(), 
	new SimpleContentProposalProvider(new String [] {"ProposalOne", "ProposalTwo", "ProposalThree"}),
	keyStroke, autoActivationCharacters);

Для того чтобы получить и установить содержимое управляющего элемента, когда пользователь выбирает вариант во всплывающем меню, адаптеру должен быть предоставлен экземпляр IControlContentAdapter, который может извлечь и установить содержимое управляющего элемента определенного типа. Для текстовых полей можно использовать класс TextContentAdapter. Однако, есть также возможность реализовать IControlContentAdapter для использования адаптера вариантов содержимого со всеми типами управляющих элементов.

При создании адаптера вариантов содержимого можно также указать экземпляр IContentProposalProvider, из которого будут извлекаться сами варианты. Этот класс ответственен за возвращение массива вариантов содержимого. Сами варианты заданы как экземпляры IContentProposal, из которого могут быть получены метки и содержимое вариантов, в дополнение к другой информации, такой как подробное описание варианта.

В приведенном выше примере используется SimpleContentProposalProvider. Этот класс определен с помощью простого массива строк, являющихся вариантами содержимого. Простой класс реализует необходимый протокол для преобразования каждой строки в ожидаемый IContentProposal. Гибкость IContentProposalProvider позволяет реализовать класс вариантов с расширенной функциональностью, такой как фильтрация вариантов на основе содержимого управляющего элемента, предоставление объяснительных меток во всплывающем меню вместо фактического содержимого и указание положения курсора после вставки содержимого. В Примере помощника поля найдите реализации IContentProposalProvider, чтобы ознакомится с расширенными возможностями.

Настройка адаптера вариантов содержимого

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

Пример помощника поля позволяет настроить эти опции и попробовать их различные комбинации. Например, адаптер может быть настроен так, что он вызывается явно комбинацией клавиш и вставляет вариант содержимого в управляющий элемент, что подобно поведению помощника содержимого текстового редактора. Или он может быть настроен так, чтобы не реагировать на комбинации клавиш, активные символы и замену содержимого, что более подобно стилю буферизации ввода, используемому в web-браузере при вводе URL или в полях поиска. Более подробная информация о каждом из этих методов и их взаимодействии находится в javadoc.

Помощник поля рабочей среды

Поддержка помощника поля на уровне JFace обеспечивает приложению большую гибкость в определении способа оформления полей и предоставлении вариантов содержимого поля. Это желательно для автономных приложений JFace или автономных приложений расширенного клиента. Однако, если приложение предназначено для интеграции с другими модулями, такими как Eclipse SDK или модулями других фирм, может понадобится использовать поддержку помощника поля тем способом, который совместим с этими модулями. Рабочая среда определяет утилиту, которая использует помощник поля для особого рода взаимодействий.

Например, класс ContentAssistField создает поле, включающее значок лампочки для уведомления пользователя о том, что помощник содержимого доступен. Он также настраивает адаптер вариантов содержимого на стиль помощника по работе с содержимым. Наконец, он предоставляет обработчик команд помощника по работе с содержимым на уровне рабочей среды, так что выпадающее меню вариантов содержимого открывается при нажатии комбинации клавиш, которая была определена в привязках клавиш рабочей среды. Более подробная информация об этих классах утилиты находится в пакете org.eclipse.ui.fieldassist.

Этот пакет расширяет использование помощника поля и стандартизует применение значков оформления для определенных состояний поля.