Overview ->
Reference ->
API Reference ->
Commands of Category Drag and Drop
daVinci API Definition - Drag and Drop Commands
On this page, API commands of the drag and drop category are described.
This category covers all commands to implement drag and drop features in an
application.
The commands of this category are enclosed by keyword drag_and_drop(...).
Click here to get an overview of all API commands.
Possible Drag and Drop scenarios
- Create a new node
- In this case, the user presses the button BTransfer
somewhere in the graph area and no node is below the mouse pointer. The API sends the answer create_node(...)
and the application should react with the command drag_and_drop(new_node_at_coord(...)) to insert a new node. daVinci will try to insert
the new node at the coordinate where the mouse button was released.
- Create a new node connected to a parent node by a new edge
- In this case, the user presses the button BTransfer
somewhere in the graph area and the mouse pointer is over a node. The mouse button is released somewhere but not over a node. The
API sends the answer create_node_end_edge(...)
and the application should react with the command drag_and_drop(new_edge_and_node_at_coord(...)) to insert a new node and connect it as a child node
to the parent node received in the event. daVinci will try to insert
the new node at the coordinate where the mouse button was released. While
dragging the mouse pointer with the button pressed, daVinci draws an
abstract edge from the first selected node to the position of the mouse
pointer. If the mouse pointer is over a node, this node is inverted to inform
the user about the secondary selection.
- Create a new edge
- In this case, the user presses the button BTransfer
somewhere in the graph area and the mouse pointer is over a node. The mouse button is released somewhere over a node. The
API sends the answer create_edge(...)
and the application should react with the command graph(update(...)) to insert one new edge connecting the two nodes received in the event, whereas
the first node is the parent and the second node is the child. While
dragging the mouse pointer with the button pressed, daVinci draws an
abstract edge from the first selected node to the position of the mouse
pointer. If the mouse pointer is over a node, this node is inverted to inform
the user about the secondary selection. If the mouse pointer is released over
the node where the mouse button was pressed and dragged in the meantime, both
nodes received in the event are the same. The application could in this case
ignore the event or if this is allowed insert a self-edge.
- Drop a node into a window
- In this case, the user presses the button BTransfer
somewhere in the graph area together with the Shift-Key and the mouse pointer is over a node. The mouse button is released somewhere even in another daVinci base-window but not over a node. The API sends the answer the event drop_node(...)
and the application should react with some command appropriate for this action, i.e. drag_and_drop(new_node_at_coord(...)) to insert a copy of the node. daVinci will try to insert
the new node at the coordinate where the mouse button was released. While
dragging the mouse pointer with the button pressed, daVinci changes
its mouse pointer to a target, but the selected node is not moved together
with the mouse-pointer, because we can't get the appropriate events from
Tcl/Tk. The first selected node is drawn inverted to mark the node where the
dragging started. The event contains the node_id,context_id and window_id of the node where the dragging started. The second
node_id is "" in this case, because the
node wasn't dropped on another node.
- Drop a node onto another node
- In this case, the user presses the button BTransfer
somewhere in the graph area together with the Shift-Key and the mouse pointer is over a node. The mouse button is released somewhere even in another daVinci base-window over a node. The API sends the answer drop_node(...)
and the application should react with some command appropriate for this action, i.e. drag_and_drop(new_edge_and_node_at_coord(...)) to insert a copy of the node as a child of the node the first node was dropped onto. While
dragging the mouse pointer with the button pressed, daVinci changes
its mouse pointer to a target, but the selected node is not moved together
with the mouse-pointer, because we can't get the appropriate events from
Tcl/Tk. The first selected node is drawn inverted to mark the node where the
dragging started. The event contains the node_id,context_id and window_id of the node where the dragging started. The second
node_id contains the identifier of the
node over which the mouse button was released. The context_id and window_id of
this node can be retrieved from the context(...) or context_window(...) answer
immediately before the drop_node(...) answer.
Further details about drag and drop can be found in the
concepts document.
Documentation of the Category Commands:
drag_and_drop(dragging_on)
With this command an application can switch on the Drag and Drop mode, in which
case the 2D-scrolling with mouse button BTransfer is switched off. After sending this command, the
application has to be prepared to receive the API events:
drag_and_drop(dragging_off)
With this command an application can switch off the Drag and Drop mode (default), in which
case the 2D-scrolling with mouse button BTransfer is switched on.
drag_and_drop(new_node_at_coord(node_update))
This command is the recommended action after receiving the API event
create_node(...). If the daVinci
API sends the answer, the coordinate at which the mouse button was released,
is stored and reused, if this command is received, to insert the new node
defined in the parameter node_update. Therefore only a
new_node(...) update is allowed in
the parameter.
daVinci tries to insert the new node at the stored coordinate, but it
maybe not possible to do so, because of layout restrictions. Please have a
look at the concepts
document to read more about graph layout.
If no create_node(...),
create_node_and_edge(...) or
drop_node(...) event was received
before and therefore no coordinate was stored, the command behaves like a
graph(update(...)) command with only one
node update specified.
This command is the recommended action after receiving the API event
create_node_and_edge(...). The daVinci API sends the answer, the coordinate at which the mouse button was released,
is stored and reused, if this command is received, to insert the new node
defined in this parameter node_update. Therefore only a
new_node(...) update is allowed in
the parameter. The new edge specified in the parameter edge_update
should connect the new node to the node that was received with the event,
because the user expects that a new child node of this node is inserted.
Therefore only a
new_edge(...) or new_edge_behind(...) update should be used in this parameter, although this is not checked by daVinci.
daVinci tries to insert the new node at the stored coordinate, but it
maybe not possible to do so, because of layout restrictions. Please have a
look at the concepts
document to read more about graph layout.
If no create_node(...),
create_node_and_edge(...) or
drop_node(...) event was received
before and therefore no coordinate was stored, the command behaves like a
graph(update(...)) command with only one
node and one edge update specified.
daVinci V2.1 Online Documentation - Page update: June 15, 1998