Options
All
  • Public
  • Public/Protected
  • All
Menu

Class DraggingTool

Hierarchy

DraggingTool是通过用鼠标来移动或者复制选中的parts的. 它设置了 Part.location 属性;你可以在Parts/Nodes/Groups的模板中通过使用TwoWay绑定Binding来将"location"保存到model中。

拖拽会移动选中元素中那些Part.canMove是ture的part. 如果用户按下了Control键(Mac中是Option键),这个工具会为那些被拖拽的元素中Part.canCopy是true的元素创建一个副本。

拖拽开始时,它会调用computeEffectiveCollection 方法去查找可以被移动的Parts的集合.一般来说这个集合不仅仅是Diagram.selection, 还包含那些被选中元素包含的parts,例如组合中包含的成员. 如果 dragsTree 为真, 有效的集合包含从选择的节点开始组成子树的所有节点和链接。 computeEffectiveCollection 函数返回的不是一个 Set 而是一个 Map 它记录了所有被拖拽的part的原始位置Part.location. Map作为DraggingTool的属性draggedParts的值.

拖拽过程中如果用户按下了Control或者Option键,tool会创建draggedParts的一个副本,接着会拖着创建的副本继续拖动。 (如果copiesEffectiveCollection 是假的话,tool只会复制Diagram.selection的内容,而不是整个effective collection.)复制出来的parts被保存为 copiedParts. 它也是一个 Map 记录了parts的原始位置. 如果那时tool是moving而不是copying,copiedParts 会是空

每一个Part的movement取决于Diagram.computeMove 方法的返回结果. 默认情况下Part.location 的值在给出的边界条件Part.minLocationPart.maxLocation之间. (默认是负无穷到正无穷之间.) 为了更方便,minLocation和maxLocation的值NaN,使得Diagram.computeMove 方法使用 part的当前location的值. 因此,例如,一个简单办法去生命用户只能水平拖动一个节点,你可以这样设置:

$(go.Node,
  . . .
  { minLocation: new go.Point(-Infinity, NaN), maxLocation: new go.Point(Infinity, NaN) },
  . . .
)

如果你设置isGridSnapEnabled为真, 拖拽或者复制出来的parts将会吸附到grid上点. 除非你设置了isGridSnapRealtime 为假,否则当你拖拽的时候吸附行为将持续发生. 一般情况下珊格点来自与Diagram.grid, 即使画布的珊格是不可见的GraphObject.visible. 然而你可以覆盖grid的属性,比如你可以这样设置吸附珊格的cell size和offset: gridSnapCellSizegridSnapOrigin. 这会为每一个拖拽的part计算出吸附到grid上的点. 计算出的点将会作为Part.location的新值.

对于绝大多数拖拽的part而言,可以设置Part.dragComputation 属性 或者覆盖 Diagram.computeMove方法. 对于想拖拽的Group中的节点,并保持在Group内这种常见的例子来说, 你可以这样设置:

 // this is a Part.dragComputation function for limiting where a Node may be dragged
  function stayInGroup(part, pt, gridpt) {
    // don't constrain top-level nodes
    var grp = part.containingGroup;
    if (grp === null) return pt;
    // try to stay within the background Shape of the Group
    var back = grp.resizeObject;
    if (back === null) return pt;
    // allow dragging a Node out of a Group if the Shift key is down
    if (part.diagram.lastInput.shift) return pt;
    var p1 = back.getDocumentPoint(go.Spot.TopLeft);
    var p2 = back.getDocumentPoint(go.Spot.BottomRight);
    var b = part.actualBounds;
    var loc = part.location;
    // find the padding inside the group's placeholder that is around the member parts
    var m = grp.placeholder.padding;
    // now limit the location appropriately
    var x = Math.max(p1.x + m.left, Math.min(pt.x, p2.x - m.right - b.width - 1)) + (loc.x-b.x);
    var y = Math.max(p1.y + m.top, Math.min(pt.y, p2.y - m.bottom - b.height - 1)) + (loc.y-b.y);
    return new go.Point(x, y);
  }

注意如果Group可视化树中有SHAPE这样的object,part被拖拽时要保持在group中,. 这个时候要设置Group.computesBoundsIncludingLinks为假. 那么在你的nodeTemplate中这样设置:

$(go.Node,
  . . .,
  { dragComputation: stayInGroup },
  . . .
)

该工具不会使用任何的装饰类和工具具柄. 如果拖拽陈工了,它将触发"SelectionMoved" 或者 "SelectionCopied" 画布事件 并且会产生一个 "Move" 或者 "Copy" 事务.

如果你想通过代码实现一个新的用户拖拽某个已经存在的节点的话, 你应该先确保那个节点已经被选中了, 然后设置DraggingTool的currentPart 属性, 然后开始激活DraggingTool工具.

  var node = ...;
  myDiagram.select(node);        // in this case the only selected node
  var tool = myDiagram.toolManager.draggingTool;
  tool.currentPart = node;       // the DraggingTool will not call standardMouseSelect
  myDiagram.currentTool = tool;  // starts the DraggingTool
  tool.doActivate();             // activates the DraggingTool

Index

Constructors

constructor

Properties

copiedParts : Map<Part, DraggingInfo> | null

  • Gets the collection of Parts that this tool has copied. The value is a Map mapping Parts to DraggingInfo Objects that have a "point" property remembering the original location of that Part. The value is null when moving instead of copying.

    draggedParts provides the map of Parts that are being moved and from which this collection was copied.

copiesEffectiveCollection : boolean

  • Gets or sets whether for a copying operation the extended selection is copied or only the selected parts. The default value is true. Setting this property does not raise any events.

    The CommandHandler.copiesConnectedLinks property serves a similar role for the CommandHandler.copySelection command, when the user types control-C to copy the currently selected parts.

currentPart : Part | null

delay : number

  • On touch gestures only, this property gets or sets the time in milliseconds for which the mouse must be stationary before this tool can be started. The default value is 100 milliseconds. Setting this property does not raise any events.

dragOptions : DraggingOptions

draggedParts : Map<Part, DraggingInfo> | null

  • Gets the collection of Parts being moved. The value is a Map mapping Parts to DraggingInfo Objects that have a "point" property remembering the original location of that Part.

    copiedParts provides the map of Parts that have been copied during a copying operation, if any.

dragsLink : boolean

  • Gets or sets whether the user can drag a single Link, disconnecting it from its connected nodes and possibly connecting it to valid ports when the link is dropped. The default value is false. Setting this property does not raise any events.

    In order to avoid too many cases of having both ends of a dragged Link connect to the same node (if allowed), it is commonplace to decrease the LinkingBaseTool.portGravity to a smaller value such as 10 or 20.

    This property is a convenience getter/setter, and sets a value on dragOptions.

    since

    1.3

dragsTree : boolean

  • Gets or sets whether moving or copying a node also includes all of the node's tree children and their descendants, along with the links to those additional nodes. The default value is false. Setting this property does not raise any events.

    The CommandHandler.copiesTree property serves a similar role for the CommandHandler.copySelection command, when the user types control-C to copy the currently selected parts.

    This property is a convenience getter/setter, and sets a value on dragOptions.

gridSnapCellSize : Size

  • Gets or sets the size of the grid cell used when snapping during a drag if the value of isGridSnapEnabled is true. By default this property is the Size(NaN, NaN), which causes this tool to use the Panel.gridCellSize value of the Diagram.grid. Setting this property does not raise any events.

    This property is a convenience getter/setter, and sets a value on dragOptions.

gridSnapCellSpot : Spot

  • Gets or sets the Spot that specifies what point in the grid cell dragged parts snap to, if the value of isGridSnapEnabled is true. By default this property is Spot.TopLeft: node locations will snap exactly to the grid point. Setting this property does not raise any events.

    This property is a convenience getter/setter, and sets a value on dragOptions.

gridSnapOrigin : Point

  • Gets or sets the snapping grid's origin point, in document coordinates, if the value of isGridSnapEnabled is true. By default this property is the Point(NaN, NaN), which causes this tool to use the Panel.gridOrigin value from the Diagram.grid. Setting this property does not raise any events.

    This property is a convenience getter/setter, and sets a value on dragOptions.

isComplexRoutingRealtime : boolean

  • Gets or sets whether link routing takes some short-cuts during dragging. When false Links whose routing is AvoidsNodes are not routed to avoid Nodes, in order to improve dragging performance. The default value is true.

    since

    1.4

isCopyEnabled : boolean

  • Gets or sets whether for any internal copying operation is permitted by control-drag-and-drop. This property affects the behavior of mayCopy, but does not affect whether copied objects may be dropped into this diagram from a different diagram.

    The default value is true. Setting this property does not raise any events.

    since

    1.4

isGridSnapEnabled : boolean

  • Gets or sets whether the DraggingTool snaps objects to grid points. Whether the snapping movement of the dragged parts occurs during the drag or only upon a drop is determined by the value of isGridSnapRealtime.

    This property does not affect dragging disconnected links, but those links to respect the Part.dragComputation, which can be used to snap them.

    By default this property is false. Setting this property does not raise any events.

    This property is a convenience getter/setter, and sets a value on dragOptions.

isGridSnapRealtime : boolean

  • Gets or sets whether the DraggingTool snaps objects to grid points during the drag. This property is ignored unless isGridSnapEnabled is true. By default this property is true; when false parts are only snapped to grid locations upon the drop (i.e. mouse-up). Setting this property does not raise any events.

    This property is a convenience getter/setter, and sets a value on dragOptions.

    since

    1.1

startPoint : Point

  • Gets or sets the mouse point from which parts start to move. The value is a Point in document coordinates. This property is normally set to the diagram's mouse-down point in doActivate, but may be set to a different point if parts are being copied from a different control. Setting this property does not raise any events.

Methods

Virtual Override canStart

  • canStart(): boolean
  • This tool can run if the diagram allows selection and moves/copies/dragging-out, if the mouse has moved far enough away to be a drag and not a click, and if findDraggablePart has found a selectable part at the mouse-down point.

    This method may be overridden. Please read the Introduction page on Extensions for how to override methods and how to call this base method.

    Returns boolean

Virtual computeEffectiveCollection

Virtual computeMove

  • This method computes the new location for a Node or simple Part, given a new desired location and an optional Map of dragged parts, taking any grid-snapping into consideration, any Part.dragComputation function, and any Part.minLocation and Part.maxLocation.

    As of 2.0, this just calls Diagram.computeMove and remains for compatibility.

    This method may be overridden, but should usually be overridden on Diagram. Please read the Introduction page on Extensions for how to override methods and how to call this base method.

    since

    1.1

    Parameters

    • n: Part

      the Node or simple Part that is being moved

    • newloc: Point

      the proposed new location

    • Optional draggedparts: Map<Part, DraggingInfo> | null

      an optional Map mapping Parts to DraggingInfo Objects that have a "point" property remembering the original location of that Part.

    • Optional result: Point

      an optional Point that is modified and returned

    Returns Point

    the possibly grid-snapped computed Point that is within the minimum and maximum permitted locations

Override doActivate

  • doActivate(): void
  • Start the dragging operation. This calls computeEffectiveCollection and saves the result as draggedParts.

    This starts a "Drag" transaction. Depending on what happens, the transaction may be finished as a "Move" or a "Copy" transaction, or it may be rolled-back if the tool is cancelled.

    Normally when this method is called the value of currentPart will be null, in which case this will call Tool.standardMouseSelect which will set currentPart. But if when this method is called the value of currentPart has already been set because the programmer wants the user to start dragging that Part, then this method will not need to call Tool.standardMouseSelect because the Part(s) to be selected and dragged have already been determined by the caller.

    Returns void

Override doCancel

  • doCancel(): void
  • Abort any dragging operation.

    Returns void

Override doDeactivate

  • doDeactivate(): void
  • Stop the dragging operation by stopping the transaction and cleaning up any temporary state.

    Returns void

Virtual doDragOver

  • Perform any additional side-effects during a drag, whether an internal move or copy or an external drag, that may affect the existing non-moved object(s).

    This method may be overridden. Please read the Introduction page on Extensions for how to override methods and how to call this base method.

    since

    1.1

    Parameters

    • pt: Point

      a Point in document coordinates.

    • obj: GraphObject | null

      the GraphObject at the point, excluding what is being dragged or temporary objects; the argument may be null if the drag is occurring in the background of the diagram. Use GraphObject.part to get the Node or Part at the root of the visual tree of the stationary object.

    Returns void

Virtual doDropOnto

  • Perform any additional side-effects after a drop, whether an internal move or copy or an external drop, that may affect the existing non-moved object(s).

    This method may be overridden. Please read the Introduction page on Extensions for how to override methods and how to call this base method.

    since

    1.1

    Parameters

    • pt: Point

      a Point in document coordinates.

    • obj: GraphObject | null

      the GraphObject where the drop occurred, excluding what was dropped or temporary objects; the argument may be null if the drop occurred in the background of the diagram. Use GraphObject.part to get the Node or Part at the root of the visual tree of the stationary object.

    Returns void

Override doKeyDown

  • doKeyDown(): void
  • Handle switching between copying and moving modes as the Control/Option key is pressed or released.

    Returns void

Override doKeyUp

  • doKeyUp(): void
  • Handle switching between copying and moving modes as the Control/Option key is pressed or released.

    Returns void

Override doMouseMove

  • doMouseMove(): void
  • Move the draggedParts (or if copying, the copiedParts) to follow the current mouse point.

    If this creates any temporary parts, by default it adds them to the Tool layer.

    This calls doDragOver for any side-effects on stationary parts.

    Returns void

Override doMouseUp

  • doMouseUp(): void
  • On a mouse-up finish moving or copying the effective selection.

    This calls doDropOnto for any side-effects on stationary parts.

    This also updates the diagram's bounds, raises a "SelectionCopied" or "SelectionMoved" DiagramEvent, and stops this tool.

    This method also raises the "ChangingSelection" and "ChangedSelection" diagram events. Changes are performed in a "Drag" transaction, but the "ChangedSelection" event is raised outside the transaction.

    Returns void

Virtual findDraggablePart

  • findDraggablePart(): Part | null
  • Return the selectable and movable/copyable Part at the mouse-down point. This is called by canStart to decide if this tool is ready to run.

    This method may be overridden. Please read the Introduction page on Extensions for how to override methods and how to call this base method.

    Returns Part | null

Virtual mayCopy

  • mayCopy(): boolean
  • This predicate is true when the diagram allows objects to be copied and inserted, and some object in the selection is copyable, and the user is holding down the Control key (Option key on Mac).

    This method may be overridden, although in most cases it is easiest to set Part.copyable. Please read the Introduction page on Extensions for how to override methods and how to call this base method.

    Returns boolean

Virtual mayMove

  • mayMove(): boolean
  • This predicate is true when the diagram allows objects to be moved, and some object in the selection is movable.

    This method may be overridden, although in most cases it is easiest to set Part.movable. Please read the Introduction page on Extensions for how to override methods and how to call this base method.

    Returns boolean

Virtual moveParts

  • Move a collection Map of Parts by a given offset.

    If check is true this respects the Part.canMove predicate for Nodes or simple Parts when this is the Diagram.currentTool. It also respects isGridSnapEnabled in order to try to automatically snap part locations to a grid. And it also uses the Part.dragComputation function, if any, to determine the new location for each part.

    The first argument is a Map as produced by computeEffectiveCollection, not a List or Set or Iterator of Parts. Call Diagram.moveParts if you want to move a simple collection of Parts without having to create the argument Map.

    since

    1.1

    Parameters

    • parts: Map<Part, DraggingInfo>

      a Map mapping Parts to DraggingInfo Objects that have a "point" property remembering the original location of that Part.

    • offset: Point

      The offset, before snapping, to move parts. This offset reflects the total amount moved during tool operation, based on original Part locations remembered when the DraggingTool activated.

    • check: boolean

      Whether to check Part.canMove on each part.

    Returns void

Virtual Override standardMouseSelect

  • standardMouseSelect(): void
  • This override prevents the Control modifier unselecting an already selected part. This also remembers the selectable currentPart at the current mouse point.

    This method may be overridden. Please read the Introduction page on Extensions for how to override methods and how to call this base method.

    Returns void