GEF 进阶，第 4 部分: Locator

文档选项 未显示需要 JavaScript 的文档选项 样例代码

级别： 中级

马 若劼 (maruojie@cn.ibm.com), 软件工程师, IBM 中国软件开发中心

2007 年 10 月 25 日

本文是GEF进阶的第四部分，主要描述了Locator的概念和使用方法。Locator是 一个图形定位器，用来动态的决定某个图形相对于另外一个图形的位置，因此可以用来构造一些 复杂的图形或者实现一些比较有趣的功能。由于Eclipse 3.3已经发布，本文的示例代码是在 Eclipse 3.3, GEF 3.3运行调试的。

本文是GEF进阶的第四部分，主要描述了Locator的概念和使用方法。Locator是一个图形定 位器，用来动态的决定某个图形相对于另外一个图形的位置，因此可以用来构造一些复杂的图形或者 实现一些比较有趣的功能。由于Eclipse 3.3已经发布，本文的示例代码是在Eclipse 3.3, GEF 3.3 运行调试的。

Locator

Locator，顾名思义，是一个定位器。我们先来看看这个接口：
清单1. Locator接口

                    public interface Locator {
   void relocate(IFigure target);   
}

这个接口非常简单，只有一个方法，参数是一个IFigure，所以首先可以明确的是：Locator是一个 图形定位器。那么一个Locator用在什么地方，又为什么要用Locator呢？一般来讲，如果你希望一个图形 能跟着另外一个图形移动，那么Locator就很有用了。因此Locator是相对定位的有利工具。我们下面来介 绍Locator的几个典型应用。

回页首

Connection Label

我们在运行GEF shapes的例子时，可以看到图形之间可以有连线，但是连线上没有文字说明，如果有 文字说明的话，会有如下图所示的效果:

从图1看到连线上有了一个“Label”的字样，你可以把它叫做Connection Label（连线标签）。总之， 这个标签是附着在连线上的。不光如此，如果你拖动连线，这个标签也会跟着移动，这就是Locator 的功劳。我们先来修改shapes例子的代码，给连线加上这样的标签。要修改的地方在ConnectionEditPart 的createFigure方法里，修改后如下所示:

                protected IFigure createFigure() {
   final PolylineConnection connection = (PolylineConnection) super.createFigure();
   connection.setTargetDecoration(new PolygonDecoration()); // arrow at target endpoint
   connection.setLineStyle(getCastedModel().getLineStyle());  // line drawing style
   
   // add a label
   final Label label = new Label("Label");
   label.setOpaque(true);
   connection.add(label, new MidpointLocator(connection, 0));
   
   return connection;
}

加这么一个label确实很简单，我们先创建一个Label对象，再将它加到连线里面，所以本质上Label是连线的 一个孩子。在添加的时候，我们使用了MidpointLocator, 这是GEF缺省带的一个Locator，作用是把图形定位 到连线的中点。所以我们看到Label的中点始终和连线的中点相同。而连线的中点又叫做MidpointLocator的 reference point(参考点), 我们在本系列的第一部分里面介绍过Anchor(锚点)，这个参考点的概念与其是类似的。

提示: 再仔细研究一下add()方法会发现，add方法的第二个参数其实是一个Object类型， 参数名是constraint. 也就是说Locator在这里充当了一个constraint的角色。Constraint是被布局管理器解释的， 如果你想自定义一个constraint类型，则需要自定义一个布局管理器。本文不详细解释这些内容。

随之而来我们会发现一个局限性：这个Label永远只能在连线的中心，无法移动到其它的地方。在有些时候这 确实是个问题：比如某个图特别复杂，连线特别多，以致于连线上的标签都重叠在了一起，可是由于它不能拖动，所 以看上去很不美观。如果我们希望这个Label能被拖动该怎么办呢？有两个方案：

1. 为这个Label创建一个EditPart，负责控制这个label的移动，改变大小，等等。
2. 使用一个自定义的Locator，并处理Label的鼠标事件，随时刷新它的位置

确定Locator的策略

首要的问题是我们的Locator如何工作呢？我们已经使用了MidpointLocator，它可以随时定位到连线的中点， 如果我们给它加一个偏移，不就可以实现拖动到任何位置的功能了吗？这个概念如图2所示:

MidpointOffsetLocator

策略定下来之后我们来实现一个MidpointOffsetLocator，它直接继承自MidpointLocator，但是我们给它添 加一个offset的成员变量，这样我们就可以控制标签中点的位置了。代码如下所示：

                public class MidpointOffsetLocator extends MidpointLocator {
   private Point offset;
   
   public MidpointOffsetLocator(Connection c, int i) {
      super(c, i);
      offset = new Point(0, 0);
   }
   
   @Override
   protected Point getReferencePoint() {
      Point point = super.getReferencePoint();
      return point.getTranslated(offset);
   }

   public Point getOffset() {
      return offset;
   }
   
   public void setOffset(Point offset) {
      this.offset = offset;
   }
}

关键的方法在于我们覆盖了getReferencePoint()，让它返回之前加上我们的偏移量。就这么简单，我们自己的Locator诞生了！

处理鼠标事件

Locator有了，下面的问题就是如何才能在适当的时机修改这个偏移量呢？第一想到的就是鼠标事件监听器。由于Figure本身 已经支持添加各种各样的监听器，所以这一步也非常简单。我们继续修改ConnectionEditPart的createFigure方法，给我们的Label 加上鼠标事件处理方法，如下所示：

                protected IFigure createFigure() {
   // 省略其它无关代码
   ......
   
   // add a label
   final Label label = new Label("Label");
   label.setOpaque(true);
   connection.add(label, new MidpointOffsetLocator(connection, 0));
   label.addMouseListener(new MouseListener() {
      public void mouseDoubleClicked(MouseEvent me) {
      }
      
      public void mousePressed(MouseEvent me) {
         anchorX = me.x;
         anchorY = me.y;
         me.consume();
      }
      
      public void mouseReleased(MouseEvent me) {
         me.consume();
      }
   });
   label.addMouseMotionListener(new MouseMotionListener() {
      public void mouseDragged(MouseEvent me) {
         dx += me.x - anchorX;
         dy += me.y - anchorY;
         anchorX = me.x;
         anchorY = me.y;
         Object constraint = connection.getLayoutManager().getConstraint(label);
         if(constraint instanceof MidpointOffsetLocator) {
            ((MidpointOffsetLocator)constraint).setOffset(new Point(dx, dy));
            label.revalidate();
         }
         me.consume();
      }
   
      // 省略其它无关代码
      ......
   });
   
   return connection;
}

要注意的有三点，第一我把MidpointLocator替换成了我们自己的Locator，第二我在ConnectionEditPart加了四个成员变量(dx, dy, anchorX, anchorY)来跟踪鼠标位置，第三我在鼠标拖动事件中修改偏移量并刷新它，但是为了安全起见，我先判断了constraint类型。

小节总结

我们现在完成了Label的拖动功能，不过你可以发现一些可以继续提高的地方，最明显的莫过于Label的位置不能保存。我们应该把这个偏移量保存到Connection模型中去。这个问题和本文无关，留给读者做个练习。本小节的示例代码在org.eclipse.gef.examples.shapes_locator_step1.zip中，大家可以看看实际的效果。

回页首

Handle

Locator另一个典型的应用是用在handle中，所谓handle，就是你选择一个图形之后，在它的边框周围出现的一些辅助性的图形，比如一些小方块。如下图所示:

因为Handle也使用了Locator，所以我们在拖动图形的时候，Handle的位置也会随之更新。回头看看上一小节中的Label，可以发现一个美中不足的是：Label的周围没有handle，这样的话用户可能会不知道我们的Label是可以拖动的，对用户不太直观，如果能在连线被选择的时候把Label的周围也加上handle，那么用户可以容易的发现这个Label原来也支持拖动，这有利于提高用户友好度。本小节的例子就来实现这个功能。

提示：本系列第三部分介绍了Layer的概念，Handle也是存在一个单独的层中的，叫做Handle Layer

MyConnectionEndpointEditPolicy

追究handle的发源地，会发现连线上的handle是在ConnectionEndpointEditPolicy中创建的， 我们要添加handle，自然就是要实现一个自己的EditPolicy了。关于EditPolicy的相关概念，这里不做赘述。观察ConnectionEndpointEditPolicy的实现，可以看到一个有趣的方法createSelectionHandles，那么我们来覆盖它，如下:

                public class MyConnectionEndpointEditPolicy extends	ConnectionEndpointEditPolicy {
   @Override
   protected List createSelectionHandles() {
      List handles = super.createSelectionHandles();
      List<IFigure> children = (List<IFigure>)getHostFigure().getChildren();
      for(IFigure figure : children) {
         if(figure instanceof Label)
            handles.add(new MoveHandle((GraphicalEditPart)getHost(), 
               new MoveHandleLocator(figure)));
      }
       return handles;
   }
}

我们遍历了连线的所有孩子，如果它是一个Label，就为它创建一个MoveHandle，MoveHandle使用了MoveHandleLocator，这些类都是GEF自带的，不需要费什么功夫。

有了自定义的EditPolicy，别忘了在ConnectionEditPart中替换原来的EditPolicy，这部分代码过于简单，省略不提。

修改Label上的鼠标事件处理代码

到这里为止，我们的Label就有了handle了，如下图所示：

MoveHandle的效果是在Label周围画了一个矩形框, 表明这个图形可以移动。不过我们还有一个小问题：点击Label的时候MoveHandle不出来，要解决这个问题也很简单，在Label的鼠标点击事件中增加一行getViewer().appendSelection(ConnectionEditPart.this)就可以了。

小节总结

本小节的示例代码在org.eclipse.gef.examples.shapes_locator_step2.zip中。我们仍然有很多可以提高的地方，首先，我们用的是缺省的MoveHandle，如果不喜欢Label周围这个矩形或者矩形的位置，可以自定义一个Handle，使用自定义的Locator. 其次，我们的Label只能拖动，不能改变大小，这牵涉到为Label添加Resize Handle并使用相应的Locator，这些内容都留给有兴趣的读者作为练习。

回页首

结束语

GEF中的几乎一切东西都可以定制，本文介绍的是Locator的定制，Locator是相对布局的关键接口。灵活使用Locator，可以实现一些很有趣的功能。

回页首

声明

本文仅代表作者的个人观点，不代表IBM的立场。

回页首

下载

	关于下载方法的信息

参考资料

• “GEF进阶，第三部分：Layer”（developerWorks 中国，XXXX 年 X 月）本系列前一部分，介绍了Layer的概念。
  
  
• “使用图形编辑框架创建基于 Eclipse 的应用程序”（developerWorks 中国，XXXX 年 X 月）介绍了GEF基础知识。
  
  
• 下载 GEF，体验强大的图形编辑功能

关于作者

		马若劼，IBM 公司软件工程师，主要从事 Workplace Forms 的设计与开发。他在 Java，Eclipse 以及 Eclipse 插件技术方面拥有多年经验，同时也是开源项目 LumaQQ 的创立者。

对本文的评价

太差！ (1) 需提高 (2) 一般；尚可 (3) 好文章 (4) 真棒！(5) 建议？

回页首