示例 - Java 编辑器
简介
“Java 编辑器示例”演示可用于定制文本编辑器的标准功能。它还显示如何注册用于文件扩展名(在此例中为 .jav)的编辑器以及如何定义供该编辑器使用的“定制文档提供程序”。此示例仅供演示之用。Java
编辑支持由 Eclipse Java 工具提供。
此示例的代码位于 org.eclipse.ui.examples.javaeditor
插件中。要探查代码,建议将该插件导入到工作空间中。
在示例编辑器中演示的功能
-
语法突出显示
-
与内容类型相关的内容辅助(JavaDoc 和 Java 代码)
-
内容大纲窗口与编辑器之间的通信,即,内容大纲窗口选择填充编辑器的突出显示范围
-
两种不同的表示方式
-
使用可视范围指示符标记突出显示范围
-
将编辑器限制为仅显示突出显示范围内的文本(如显示 Java 类的某个方法)
-
标记处理
-
文档共享
未演示功能
运行示例 Java 编辑器
-
创建项目
-
在最近创建的项目中创建扩展名为“.jav”的文件。Java 示例编辑器自动打开。
-
插入 Java 代码。Java 代码是动态着色的。示例编辑器用不同的颜色显示下列语言元素:多行注释、单行注释、Java
语言保留字、字符串和字符常量、常规 Java 代码以及 JavaDoc 指南后面的多行注释。在那些
JavaDoc 注释中,JavaDoc 关键字(绿色)和 HTML 标记(灰色)的颜色不同。
-
通过将“/*”插入在 Java 注释外边来打开一个新的 Java 多行注释。在插入的“/*”与第一个出现的“*/”之间或与文本末尾之间的所有文本的颜色变成红色。追加另一个“*”。由于现在认为常规多行注释包含 Javadoc,红色范围的颜色变为黑色。使用 Alt-/ 调用代码辅助。内容辅助的功能是在编写代码方面支持用户。因此,在调用时,内容辅助应将所有可能的有效完成列示于调用位置。在
Javadoc 中,示例编辑器总是提供所有建议的 Javadoc 关键字。
-
在 Java 注释外使用 CTRL+SHIFT+SPACE 来调用内容提示。列示了五个建议。选择其中一个并按 ENTER 键。一个小小的浮动红色窗口出现在当前行上面,显示所选建议。使用内容提示的目的是让用户表达其意图(例如:输入方法调用)并显示指导用户进行该操作的上下文信息。在示例编辑器中,建议被视作初始调用位置附近的五个有效字符。当内容提示可见时,使用“CTRL+空格”调用内容辅助。在这种情况下,调用的内容辅助应帮助用户完成其在内容提示中仍可见的指定意图。在常规
Java 代码中,示例编辑器总是提供所有建议的 JavaDoc 关键字。
-
保存 Java 代码。保存会更新内容大纲窗口。内容大纲窗口包含十个条目,每个条目表示编辑器中
Java 代码的十个大小相等的段之一。选择这种样式的内容大纲来说明可任意定义突出显示范围的语义。(请参阅下面的步骤。)
-
选择内容大纲窗口中的条目之一。用编辑器左边的垂直标尺中的蓝条标记了相应的行。
-
现在切换到 Java 编辑器的分段表示方式。因此,应确保编辑器具有焦点并按其悬浮式帮助显示““启用/禁用”分段源查看器”的桌面工具栏中的按钮。此功能将用于单方法视图及类似功能。
-
选择内容大纲窗口中的另一个条目。现在,编辑器仅显示所选段。通过取消对内容大纲窗口中的条目的选择,再次显示出完整的 Java 代码。
-
选择内容大纲窗口中的一个条目,再选择可见文本中的一部分,然后为该选择添加任务。任务显示在任务列表中。修改可见的代码。在任务列表中,选择先前创建的任务并按“转至文件”按钮。这就在可见区域中选择了该任务,并正确地考虑了先前应用的修改。
-
选择内容大纲窗口中的另一条目。显示出任务列表中先前添加的任务。编辑器的突出显示范围自动放大以包括所显示任务的范围。
-
打开新工作空间。在新工作空间中,为原来工作空间中的那个文件打开 Java 编辑器。修改编辑器内容。切换回原来的工作空间。编辑器显示在其它工作空间中所做的更改。显示同一个文件的两个编辑器是链接的。
用于创建定制文本编辑器的原则
开发定制文本编辑器通常需要执行下列步骤。
-
创建文档提供程序。文档提供程序(请参阅 IDocumentProvider)生成并管理包含编辑器输入元素的文本表示的文档(请参阅
IDocument)。决定如何执行元素与文本表示之间转换及多个编辑器是否应共享文档提供程序是非常重要的。请参阅 Java 示例编辑器中的 FileDocumentProvider 类。
-
创建文档分区程序。文档分区程序(请参阅
IDocumentPartitioner)将文档分成若干个不相连的区域。分区程序给每一个区域指定该分区程序预先定义的一组内容类型中的一个。在更改每一个文档时,必须更新文档的分区。请参阅 Java 示例编辑器中的 JavaPartitioner
类。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
包含所有 Javadoc
特定源查看器插件(如 JavaDocDamagerRepairer)。
org.eclipse.ui.examples.javaeditor.util
包含由其它三个包共享的便利类。