JGraph in action(一)

 

JGraph in action

 

资源：

[1] jgraph in action http://www.jgraph.com/pub/jgraphpadmanual.pdf

[2] jgraphpad的GPL版本: http://www.jgraph.com/jgraphpadpro-gpl/ (注意这个地址，该地址下的jar才是与[1]匹配的代码，并且jgraphpad还有商业版本。)

基本信息

JGraph有三个子项目：

• JGraph — Open source graph component for JFC/Swing

• JGraph Layout Pro — Layout and algebra package for JGraph

• JGraphpad Pro — Diagram editor framework for JGraph

 

 

 

相互关系：

JGraph Layout Pro uses JGraph, and JGraphpad Pro uses JGraph

Layout Pro, even though it is also possible to build and run JGraphpad Pro without the layouts.

 

 

 

设计目标：

MVC,IOC,KISS(keep it small and simple)

 

 

 

一些设计策略：

Ⅰ 使用 prototype 的方式创建 cell 。 prototypes are part of the application configuration and are never changed during the lifecycle of the application.

 

Ⅱ 在 Editor Framework （ JGraphpad Pro ？ ）中，使用一个工厂 factory 来为给定的 GraphLayoutCache 创建实际的 JGraph 实例。为了创建新的 graph 实例必须重写 factory 。

cell views (CellViewFactory), renderers, handlers and editors 都是可配置的，只有 JGraph 实例（定义了 basic aspects of a diagram, such as tooltips, drag and drop and double buffering ）是通过 factory 的一个方法创建的。

 

The default components implement both: All components are tied to exactly one graph during their lifecycle

(because JGraphpad only has one custom graph), and they provide a way to replace the backing

graph so they can be tied to multiple graphs if required. The initial graph is created using the factory's

createGraph method with a dummy graph layout cache as an argument. For example, the following code

is used to create the initial backing graph for the navigator:

JGraph backingGraph = editor.getFactory().createGraph(

new GraphLayoutCache());

new JGraphEditorNavigator(backingGraph);

 

 

 

关于 JGraphpad ：

现在的 JGraphpad 被分为三个组件：

• The JGraph Editor Framework (framework) contains the common parts of all editors that use JGraph and defines the basic application structure and lifecycle. Initially planned as a separate

product, it is now bundled with and named after the main application, which also forms the main example

of the framework.

包括所有利用 JGraph 创建的编辑器所需要的通用部分，

定义了基本的程序结构和生命期。

• The JGraphpad Pro Application (application) uses the framework and provides common components to implement a diagram editor. The developer is free to modify the JGraphpad Pro application

and devise a new application from it .

利用 Framework ，提供了实现一个图形编辑器的基本组件。

• The JGraphpad Plugins contain blocks of functionality, typically with dependencies to external libraries

(eg. SVG export, which uses the Batik library). However, it is not required for a Plugin to

define a large block, it can also be a small block, such as a menu item. In general, plugins are a flexible

way to add functionality to existing applications without having to recompile the application itself.

 

 

JGraph Editor Framework 简介

 

Editor Framework 定义了一种结构，这种结构可以处理 actions ， tools ，并且用它们创建 UI 。详细的可参见： http://www.javadesktop.org/articles/actions/index.html 。

这种结构的特点：

• Externalize the user interface — The UI is created using a factory based on external files. This idea is extended to use factory methods in the Editor Framework.

基于外部文件，使用工厂方法创建 UI ，

• Separate structure and content — The separation between these two yields separate configuration files, namely XML files for describing the tree-like UI-structure, and resources bundles (aka. properties

files) for defining language-dependent resources.

分离结构和内容：这种做法产生了配置文件。

支持 MVC 模式而创建的类（主要在 com.jgraph.editor 包），如下：

• com.jgraph.JGraphEditor: The main class which is a composition of the functionality from the com.jgraph.editor package. This class can be considered "glue-code" to hold the other classes together.

将 com.jgraph.editor 包里的类组合在一起。

• com.jgraph.editor.JGraphEditorModel: Following the MVC design pattern, the document model contains the actual application data, namely files, and is in charge of input and output.

• com.jgraph.editor.JGraphEditorKit: Holds actions and tools and updates their state depending on the state of the application. The actions and tools in an editor kit are used to define the functionality and behaviour of applications.

维护和更新 actions 和 tools 。

Actions 和 tools 定义 application 的功能和行为。

•com.jgraph.editor.JGraphEditorFactory: Creates and wires up the user interface according to the MVC design pattern. The user interface is created based on the configuration data and uses either built-in or factory methods.

创建 UI 。

• com.jgraph.editor.JGraphEditorSettings: Holds the structural definition of the user interface and general dynamic configuration data. This may be modified by various parties during application startup.

• com.jgraph.editor.JGraphEditorResources: Static class to hold internationalized resources and general application resources, such as images. All resource bundles must added before the UI is created.

静态类，维护国际化信息和通用资源，如图片。

所有的资源包必须在 UI 创建前被加入。

 

 

 

编辑器的生命周期是：

1. Create settings and add resource bundles, actions, tools and factory methods to the resources, kit and factory respectively.

2. Initialize external plugins to add or modify the settings, and add or replace existing resources, actions, tool and factory methods.

3. Create the user interface using the configured settings, the functionality defined by the editor kit and factory methods.

4. Run the application.

5. Exit the application by calling the exit method in the editor instance.

退出是 JGraphEditor 唯一的 hook 函数， it is implemented to call the shutdown method in the JGraphEditorSettings class to give applications a chance to save their settings.

 

 

com.jgraph.JGraphEditor

com.jgraph.JGraphEditor 维护主要的参与者：

维护引用到 an editor kit, a document model, factory and settings ，而资源包是静态的，所以可以直接使用。

 

退出Hook：

注意该hook的默认实现不是为空的，所以

1.         子类应该调用该默认实现，如

new JGraphEditor() {

public void exit(int code) {

super.exit(code);

if (!isActive())

System.exit(code);

}

}

2.      如果不调用，you should make sure that the settings are given a chance to execute the shutdown hooks before the VM exits, using the following statement:

settings.shutdown();

 

 

com.jgraph.editor.JGraphEditorModel

com.jgraph.editor. JGraphEditorModel 是树型模型，

为每个元素（结点）提供两个接口：

• com.jgraph.editor.JGraphEditorFile: Defines the basic requirements for a file. A file consists of its children in the document model tree, and is defined by the filename and the isModified and isNew flags.

• com.jgraph.editorJGraphEditorDiagram: Defines the basic requirements for a diagram in a document model. A diagram is an object that has a name and contains a graph layout cache that may be used to create a JGraph instance.

 

必须用 com.jgraph.editor. JGraphEditorModel 中的方法来改变模型中的元素的状态，因为像 swing 中模型会负责状态改变带来的复杂的通知问题。

 

com.jgraph.editor. JGraphEditorModel 负责处理 IO 问题。

IO 处理是基于 java 内嵌的 xml 处理机制，

并且采用 Persistence delegate 来处理基于 xml 的编码问题。

 

Persistence delegate ：

In the static initializer of the default model all cell view properties except cell and attributes of the known cell views, namely VertexView, PortView and EdgeView are made transient. Additionally, a set

of persistence delegates is added for the DefaultGraphModel, GraphLayoutCache and DefaultEdge.

默认模型的静态初始化器除了已知的 cell views ，即 VertexView, PortView and EdgeView 外，所有的 cell view 属性都是 transient 。

另外，一组 persistence delegates 被加到 DefaultGraphModel, GraphLayoutCache and DefaultEdge 。

DefaultRouting classes in the JGraphEditorModel constructor. The first two use a DefaultPersistenceDelegate,

which defines the properties to be written to the file and passed to the constructor when

read back into memory:

addPersistenceDelegate(DefaultGraphModel.class,

new DefaultPersistenceDelegate(new String[] { "roots",

"attributes" }));

addPersistenceDelegate(GraphLayoutCache.class,

new DefaultPersistenceDelegate(new String[] { "model",

"factory", "cellViews", "hiddenCellViews", "partial" }));

 

 

 

File 和 Diagram

默认的 model 没有对可添加的元素的 level 及内容做限制，

但是定义了一些默认的行为，比如 addFile() 就是添加 roots 级的元素。

 

Another assumption is that for each element in the document model, there exists at least one file along

the path to the root. This is implemented by the static getParentFile method, which returns the first parent.

The method is used, for example, to update the modified state of the parent file when a child diagram

changes. In the application, the document model is assumed to contain a set of JGraphEditorFiles,

each of which corresponds to exactly one physical file. The JGraphEditorFile can contain any number of

children, for example JGraphEditorDiagram objects, or it can itself be a JGraphEditorDiagram (in which

case it is considered its own parent file).

 

 

com.jgraph.editor.JGraphEditorKit

 

com.jgraph.editor.JGraphEditorKit

通用定义 action 和 tools

定义了应用的功能，

actions 和 tools 在应用运行的开始就被定义，且基于下面的类：

• com.jgraph.editor.JGraphEditorAction : May be inserted into buttons and menu items to provide the functionality that is accessible via the user interface (eg. menubar, toolbar, popupmenus etc).

提供可以附加到 buttons 和 menu items 的，通过 UI 操作的功能。

• com.jgraph.editor.JGraphEditorTool : May be used to implement special marquee handlers to insert specific graph cells or implement other functionality, such as panning or marquee selection (default) in a graph.

 

下面的例子将所有的 file menu 相关的 actions 都添加到应用中：

kit.addBundle(new JGraphpadFileAction.AllActions());

 

 

 

com.jgraph.editor.JGraphEditorAction

继承 javax.swing.AbstractAction

并加入三个属性 i sToggleAction, isSelected and isVisible ，后两个属性的变化会触发 PropertyEvent 。

 

Action 资源：

用后缀来标识资源：

例如：

about.label=About

about.icon=/com/jgraph/pad/image/about.gif

about.shortcut=control shift A

about.tooltip=About JGraphpad Pro

about.mnemonic=a

 

 

com.jgraph.editor.JGraphEditorTool

tool 就是一个具有名字和 isAlwaysActive 属性的基本的 marquee handler （选取框处理）

首先要理解 JGraph 中的 BasicMarqueeHandler 。

Technically speaking, the BasicMarqueeHandler is a paintable mouse listener base class with an added isForceMarqueeEvent method.

The real magic behind the marquee handler comes from the way it is used in the BasicGraphUI. The

class in charge is the MouseHandler inner method in the BasicGraphUI class. Its mousePressed method

has the following basic logic:

if (!event.isConsumed() && graph.isEnabled()) {

[...]

if (marquee.isForceMarqueeEvent(event)) {

marquee.mousePressed(event);

[...]

} else {

[...]

}

}

BasicMarqueeHandler 是一个可绘制的鼠标监听器基类，具有一个 isForceMarqueeEvent 方法。

它真正有意义的地方是它在 B asicGraphUI 中的使用方式，对此负责的是 B asicGraphUI 中的 MouseHandler 的内部方法，片段如上。

可见：

isForceMarqueeEvent() 方法可捕捉这个 mousePressed 事件。因为 B asicGraphUI 通常都是 JGraph 组件的第一鼠标监听器，

因此， Marquee Handler ，或者说 tools 是 graph 上的鼠标 gesture 的事件拦截器 interceptor

 

tools 资源：

例如：

selectTool.icon=/com/jgraph/pad/image/select.gif

selectTool.tooltip=Marquee Selection

 

com.jgraph.editor.JGraphEditorFactory

 

com.jgraph.editor.JGraphEditorFactory 利用

com.jgraph.editor.factory 包的类和

com.jgraph.editor.JGraphEditorSettings 类中对 UI 的描述

通过创建已知的元素，

比如 menu items, toolbar buttons and toolboxes and placing actionsand tools from the editor kit ，

来创建 UI 。

 

创建新的元素的方法是通过注册 factory methods ，而不是扩展为子类。

Factory methods 是实现 JGraphEditorFactoryMethod 接口的对象，该接口只有一个方法：

public abstract Component createInstance(Node configuration);

其注册机制：

factory.addMethod(JGraphEditorFactoryMethod);

被注册的 factory methods 的调用机制：

public Component executeMethod(String factoryMethod,

Node configuration)

{

JGraphEditorFactoryMethod method = getMethod(factoryMethod);

if (method != null)

return method.createInstance(configuration);

return null;

}

factory methods 隐式调用，也可以显式调用，

显式调用其方式是：

在 UI 描述中，用 factory methods 的名字作为 key ：

<menubar>

<item key="createOpenRecentMenu"/>

</menubar>

Component c = factory.executeFactoryMethod("createFrame");

 

例子如下，下面列举的 JGraphEditorNavigator 和 JGraphEditorComboBox 在默认情况下没有添加，但是已实现 ：

factory.addMethod(new JGraphEditorNavigator

.FactoryMethod(editor));

factory.addMethod(new JGraphEditorComboBox

.BorderComboFactoryMethod());

factory.addMethod(new JGraphEditorComboBox

.LineDecorationComboFactoryMethod());

factory.addMethod(new JGraphEditorComboBox

.LineWidthComboFactoryMethod());

factory.addMethod(new JGraphEditorComboBox

.DashPatternComboFactoryMethod());

 

连接 factory methods 和 actions ：

前者创建组件，后者创建功能，现在要把它们连在一起。

因为所有的 actions 和 factory methods 在运行前就被注册了，

所以当 factory methods 运行时， action 已注册，可引用。

 

Factory methods 有个问题：创建的组件不能被保存，如下：

public Component createInstance(Node configuration) {

JMenu menu = new JGraphpadWindowMenu();

editor.getSettings().putObject("windowMenu", menu);

return menu;

}

为了保存创建的 menu ，用了 editor.getSettings().putObject("windowMenu", menu);

 

 

com.jgraph.editor.JGraphEditorSettings

 

com.jgraph.editor.JGraphEditorSettings 用来

维护配置文件，即 xml 和 ini 文件，

修改配置文件。

 

com.jgraph.editor.JGraphEditorSettings 的生存期：

• Setup — In the setup phase, objects and files are added or merged into the settings.

• Runtime — Use the configuration data, and the map object to hold current settings.

• Shutdown — Triggered by the editor's exit hook, in this phase the settings are saved.

 

com.jgraph.editor.JGraphEditorSettings 可以

描述 UI(classpath 里的 xml) ，

维护用户设置 ( 用户根目录下的 ini) ，

保存 factory methods 创建的对象，

 

添加描述 ui 的 xml 文件，如下：

settings.add("ui", JGraphEditorSettings.parse(

JGraphEditorResources.getInputStream("/com/jgraph/pad/resources/ui.xml")));

添加 ini 文件

settings.add("userSettings", JGraphEditorResources

.getInputStream("/home/johndoe/.editor.ini"));

 

UI xml 文件的描述技巧：

<menubar>

<menu key="fileMenu">

<item key="exit"/>

</menu>

</menubar>

<menubar>

<menu key="fileMenu">

<item key="newDiagram" before="exit"/>

</menu>

</menubar>

可合并为；

<menubar>

<menu key="fileMenu">

<item key="newDiagram"/>

<item key="exit"/>

</menu>

</menubar>

 

应用程序范围内的 map ：

One example we have already come across is the

storing of objects created during the execution of the createInstance method in a factory method for later

wiring by the application. Another example is the storing of objects for later use in a shutdown hook, for

example by the caller of a factory method.