Пример: Редактор Java
Введение
Пример Редактор Java демонстрирует стандартные возможности, доступные обычным текстовым редакторам. Он
также показывает, как зарегистрировать редактор для расширения файла (в данном случае - .jav) и как
определить обычный поставщик документов для использования с этим редактором. Этот пример предназначен только
для иллюстрации. Поддержка редактирования Java предоставляется инструментами Java для Eclipse.
Модуль org.eclipse.ui.examples.javaeditor
содержит исходный код этого примера.
Если вы хотите изучить его, импортируйте модуль в рабочую среду.
Возможности, демонстрируемые в примере редактора
-
выделение синтаксиса
-
помощник по работе с содержимым, учитывающий тип содержимого (документация по Java и код Java)
-
связь между группировщиком содержимого и редактором: то есть диапазон выделения в
редакторе определяется выбором в группировщике содержимого
-
два разных режима представления
-
маркировка диапазона выделения с помощью визуального индикатора диапазона
-
наложение ограничений на размер фрагмента, отображаемого в редакторе: отображается только
текст из диапазона выделения (например, только один метод класса Java)
-
обработка маркеров
-
совместно использование документа
Не показаны следующие возможности
-
форматирование содержимого
-
динамическое согласование страницы схемы содержимого
Запуск примера редактора Java
-
Создайте проект.
-
В только что созданном проекте создайте файл с расширением ".jav".
Пример редактора Java откроется автоматически.
-
Введите код Java. Цвета для кода Java устанавливаются динамически. Следующие элементы языка выделяются в редакторе
различными цветами: многострочные комментарии,
зарезервированные слова языка Java, строковые и символьные константы, обычный код Java, а
также многострочные комментарии, сопровождающие директивы документации Java.
Ключевые слова и теги Javadoc, содержащиеся в этих комментариях Java, также выделяются различными цветами.
-
Откройте новый многострочный комментарий Java, вставив "/*" вне комментария Java.
Цвет текста, расположенного между вставленным "/*" и первым вхождением "*/" или концом текста, изменится на
красный. Добавьте еще один символ "*". Красный цвет фрагмента изменится на черный, - то
есть на цвет обычного многострочного комментария, содержащего Javadoc. Вызовите помощник по работе с кодом, нажав клавиши
CTRL-SPACE. Назначение помощника по работе с кодом состоит в том, чтобы оказывать пользователю поддержку в
написании кода. Поэтому при вызове помощник по работе с кодом выдает список всех возможных вариантов
завершения кода в месте вызова. Внутри документации Java редактор в примере всегда предлагает все ключевые слова
Javadoc.
-
Вне комментария Java вызовите подсказку по коду, нажав клавиши CTRL+SHIFT+SPACE. Появится список с пятью
предлагаемыми вариантами. Выберите один и нажмите ENTER. Над текущей строкой появится плавающее окно,
содержащее выбранное предложение. Предполагается, что подсказки по коду будут
использоваться пользователем для выражения общего намерения (например, для ввода вызова
метода) и представления контекстной информации. В примере редактора предлагаемый вариант
включает пять символов до и пять - после исходного расположения вызова. Пока подсказка по
коду остается видимой, можно вызвать помощник по работе с кодом, нажав клавиши CTRL+SPACE.
Помощник по работе с кодом, вызываемый в этот момент, должен помочь пользователю
завершить элемент, предлагаемый в подсказке по коду (при вызове помощника она не скрывается). Внутри обычного кода Java редактор в
примере всегда предлагает все ключевые слова Java.
-
Сохраните код Java. При этом обновится группировщик содержимого. Группировщик содержит десять записей, каждая
из которых представляет один из десяти сегментов кода Java одинакового размера в редакторе. Такой стиль
структурирования содержимого был выбран для того, чтобы показать, что семантика диапазонов выделения может
определяться произвольно. (См. последующие шаги.)
-
Выберите одну из записей в группировщике содержимого. Соответствующие строки маркируются синей полосой в
левой вертикальной линейке редактора.
-
Теперь переключитесь в режим представления сегментов редактора Java. Для этого убедитесь, что вы находитесь в
редакторе, и нажмите кнопку в панели инструментов рабочего стола с всплывающей подсказкой "Включить/Отключить
средство отображения сегментов исходного кода".
Этот режим используется, к примеру, для просмотра отдельных методов.
-
Выберите в группировщике содержимого другую запись. Теперь редактор показывает только выбранный сегмент. Если
отменить выделение этой записи в группировщике содержимого, то код Java опять будет отображаться
полностью.
-
Выберите запись в группировщике содержимого, выберите фрагмент видимого текста и затем добавьте задачу для
этого выбора. Задача появится в списке задач. Измените видимый код. В списке задач выберите ранее созданную
задачу и нажмите кнопку "Перейти в файл". Задача выбирается в видимой области с учетом
ранее сделанных изменений.
-
Выберите в группировщике содержимого другую запись. Найдите в списке задач
добавленную ранее задачу. Диапазон выделения редактора автоматически расширится, чтобы
охватить диапазон найденной задачи.
-
Откройте новую рабочую среду. Откройте в этой среде редактор Java для файла, который был открыт в
первой рабочей среде. Измените содержимое редактора. Переключитесь обратно в первую рабочую среду. В
редакторе будут показаны изменения, сделанные в другой рабочей среде. Два редактора, отображающие один
и тот же файл, связаны.
Принципы создания пользовательских текстовых редакторов
Для того чтобы создать пользовательский текстовый редактор, обычно требуется выполнить следующие действия:
-
Создайте поставщик документов. Поставщик документов (см. IDocumentProvider) создает документы, содержащие
текстовые представления входных элементов редактора, и управляет этими документами (см. IDocument). Важно
решить, как должно осуществляться преобразование между элементом и текстовым представлением, и должен ли поставщик
документов использоваться несколькими редакторами совместно. См. класс FileDocumentProvider в примере редакторе
Java.
-
Создайте инструмент разбиения документа. Инструмент разбиения документа (см. IDocumentPartitioner) разбивает
документ на неперекрывающиеся фрагменты и ставит в соответствие каждому фрагменту один тип содержимого из
множества предопределяемых им типов содержимого. При каждом обновлении документа необходимо обновить его
разбиение. См. класс JavaPartitioner в примере редакторе Java.
JavaPartitioner различает три типа фрагментов: "многострочный комментарий", "комментарий Javadoc" и "прочее". Необходимо убедиться,
что для каждого документа, создаваемого поставщиком документов, задан поставщик
документов.
-
Определите, какие модули средства отображения исходного кода должны быть предоставлены. Среди прочих
поддерживаются стратегии автоматического структурирования текста, стратегии двойного щелчка, верстальщик кода
и инструмент согласования текстового представления. В дальнейшем мы ограничимся только описанием инструмента
согласования текстового представления (см. IPresentationReconciler). В примере редактора Java инструмент
согласования текстового представления используется для реализации выделения синтаксиса.
-
Для всех модулей средства отображения исходного кода создайте подходящие расширения, соответствующие всем
поддерживаемым типам содержимого. Как было показано выше, поддерживаемые типы содержимого определяются
инструментом разбиения документа. Реализация по умолчанию интерфейса IPresentationReconciler поддерживает в
качестве расширений интерфейсы IPresentationDamagers и IPresentationRepairers. Эти интерфейсы считаются
относящимися к конкретному типу содержимого. Таким образом, при создании своего редактора пользователь
сначала должен выбрать подмножество поддерживаемых типов содержимого. Области с типом из
ыбранного подмножества могут быть, например, выделены цветом. Для всех этих
типов необходимо реализовать расширения. См.
JavaDamagerRepairer и JavaDocDamagerRepairer в примере редактора.
-
Скомпонуйте конфигурацию средства отображения исходного кода, используя созданные ранее модули и расширения.
См. JavaSourceViewerConfiguration в примере редактора.
-
Настройте класс TextEditor или AbstractTextEditor с созданной конфигурацией инструмента разбиения документов
и средства отображения исходного кода. Добавьте или замените действия и адаптируйте конструкцию контекстного
меню редактора. В действующей версии эта настройка должна выполняться в производном классе. См. JavaEditor в
примере редактора.
-
Задайте подходящее средство дополнения панели действий, которое будет добавлять действия
редактора в панель инструментов и меню рабочего стола. См. JavaActionContributor в примере редактора.
-
Дополните файл конфигурации XML модуля редактора, так чтобы зарегистрировать редактор в
предопределенной точке расширения редактора для определенного набора расширений файлов.
Кроме того, задайте в файле XML средство добавления панели действий. См. файл plugin.xml
данного примера.
Организация кода данного примера
Код примера Редактор Java включает четыре пакета:
-
org.eclipse.ui.examples.javaeditor
содержит все классы редактора.
-
org.eclipse.ui.examples.javaeditor.java
содержит модули средства отображения исходного кода
на Java, такие как JavaDamagerRepairer, а также инструмент разбиения документов Java.
-
org.eclipse.ui.examples.javaeditor.javadoc
содержит все модули средства отображения
документации Java, такие как JavaDocDamagerRepairer.
org.eclipse.ui.examples.javaeditor.util
содержит стандартные классы, совместно используемые
остальными тремя пакетами.