SWI-Prolog -- Send methods

1.106.2 Send methods

Deletes node from the tree. Each of the sons of this node will be connected to each of the parents of this node.

The root of the tree may be deleted with this method. If this node has no sons, tree<-root will be set to @nil. Otherwise the first son of this node will be made the new root of the tree.

When the tree<-display_root is deleted, it is set to the first parent of this node.

Bugs: Deleting the root of a tree that has multiple sons is not well defined.

See also: - node->unlink
- node->delete_tree

node ->delete_tree:

Deletes the entire subtree starting at this node. Node that if any subnode of this node is still connected to the root through another chain of parents it will not be deleted from the tree. See also node->unlink

See also: node->delete

node ->event: event

node->event is a little different from the other refinements of graphical->event as class node is not a subclass of graphical. It is invoked from tree->event and allows for adding behaviour to nodes regardless of the underlying graphicals.

The default method uses central handler objects from the associated node<-tree:

a) If it is collapsed, run <-collapsed_handlers
b) If it is a leaf, run <-leaf_handlers
c) If it is the display_root, run <-root_handlers
d) else, run <-node_handlers

In each of the cases a) to d), run means invoke the following message for each of the members of the handler-chain:

`event ->post: graphical, recogniser`

If you wish to refine this method, please be aware that the normal schema described with graphical->event does not work for nodes. Here is a skeleton implementation:

:- pce_global(@my_node_recogniser,
                          make_my_node_recogniser).

make_my_node_recogniser(G) :-
        ...

event(Node, Ev:event) :->
        (   send_super(Node, event, Ev)
        ->  true
        ;   send(Ev, post, Node?image,
                         @my_node_recogniser)
        ).

node ->for_all: code

Invokes itself recursively on all node<-sons of this node and finally runs code on the receiving node.

Note that multiple-inheritance will cause some nodes to be visited more than once. Argument binding:

@arg1:	Node object.

See also node<-find.

NOTE: Upto version 5.0.9, the execution order was different: code was first executed on the node and then on the node<-sons. The current order allows for deleting nodes.

Diagnostics: Terminates immediately with failure if code could not be executed fro some node

Bugs: node->for_all is not safe when the executed code manipulates the subtree below this node.

See also: - node<-find
- node->for_some
- tree->for_all

node ->for_some: code

Equivalent to node->for_all, but ignores the exit-status of the executed code. Succeeds always.

See also: node->for_all

node ->initialise: image=graphical

Create a node from an arbitrary graphical object. Nodes may be created from any graphical object, including devices, dialog_items and even trees. A typical way to build a tree is the following:

?- new(T, tree(new(Root, node(text(anything))))),
   send(Root, son, new(S0, node(text(living_thing)))),
   ...

See also: node<-convert

node ->is_parent: node

Succeeds if the argument is an (indirect) parent of this node. Fails silently otherwise.

See also: node->is_son

node ->is_son: node

Succeeds if argument node is an (indirect) son of this node. Fails silently otherwise.

See also: node->is_parent

node ->move: node

Make the argument node a direct son of this node.

Succeeds without doing anything if the argument is already a son. Fails silently if one of the following is the case:

The argument node is in another tree
This node is not part of a tree
The argument node is this node
The argument node is a parent of this node @see node->son

node ->move_after: [node]*

If node and the argument are immediate sons of the same parent, the receiver is placed immediately after the argument node. If the argument is @default, the receiver is placed at the end chain of sons (making it the lowest or rightmost node). If the argument is @nil, the receiver is places at the start of the chain of sons.

Bugs: Not well defined when the receiver node has multiple parents.

See also: chain->move_after

node ->son: son=node, before=[node]*

Makes the argument node a son of this node. This is the most common way to build a hierarchy. If before is @nil or @default, the child is added at the end of the node<-sons chain. Otherwise it is added just in front of the before argument.

Diagnostics: # <Node> already in a tree Argument node is member of another tree.

<Node> should be in a tree The receiver node is not in a tree.

See also
- node-sons
- node->move

node ->sort_sons: code

Sort the chain of node<-nodes, just like chain->sort, and update the hierarchy layout afterwards.

node ->swap: node

Swap the images of the specified nodes.

Bugs: This method manipulates the images rather than the nodes as done by most of the other methods manipulating the layout of the hierarchy.

See also: node->swap_tree

node ->swap_tree: node

Swap the subtrees formed by both nodes. It performs the following steps:

Identify common parents and swap the positions in the parent node<-sons chain.
Swaps the node<-parents chain between both nodes
Destroy and recreate the necessary connections. Diagnostics: Fails silently if:
The nodes are not in the same tree or not in a tree at all
One node is a parent of the other @see node->swap

node ->unlink:

Equivalent to node->delete: removes node from the tree binding all sons to all parents of this node. To remove an entire subtree, see node->delete_tree.