=head1 arrows.inc

This file provides generic support for drawing custom arrows that can be used in any macro context.

=head2 USAGE

Add these lines to your macro context:

  #include <contrib/support/arrows.inc>
  #include <contrib/pml/PML.mak>

  sub root_style_hook {
    DrawArrows_init();
    # ...
  }
  sub after_redraw_hook {
    DrawArrows_cleanup();
    # ...
  }
  sub node_style_hook {
     my ($node,$styles) = @_;
     DrawArrows($node,$styles,
       [ {
           # an arrow with a target
           -target => PML::GetNodeByID($node->{ref}),
           # other options: -tag -arrow -arrowshape -width -smooth -fill -dash
         },
         {
           # an arrow without a target
           -deltax => 10,
           -deltay => '(yn-yp)/2',
           # ...
         },
         {
           # an arrow with modified origin
           -originx => 'xn+10',
           -originy => 'yn+10',
           # ...
         },
      ],
      {
        # options common to all edges
      });
    #...
  }

=head2 DESCRIPTION

This file provides a function DrawArrows which can be called from the node_style_hook to extra
arrows from the current node to some other nodes (or relative coordinates).
The USAGE section above shows a full example.

In the macros for your annotation context, you have to:

=over 5

=item 1.

include <contrib/support/arrows.inc>

=item 2.

define the root_style_hook which calls DrawArrow_init() to initialize caches.

=item 3.

define an after_redraw_hook which calls DrawArrow_cleanup() to clean-up caches.

=item 4.

define a node_style_hook which calls DrawArrows with the following arguments

  DrawArrows($node,$styles,\@arrow_definitions,\%common_arrow_options)

The first two arguments ($node and $styles) are the first two arguments passed to the node_style_hook by TrEd.
The third argument,
\@arrow_definitions, is an ARRAY reference containing definitions of
the arrows to draw. Each arrow definition is a HASH reference defining the target node or target coordinates for the other end
of the arrow and style options. Style options common to all arrows can be also passed in the optional HASH reference passed as the last argument
\%common_arrow_options.

=back

=head3 Arrow definitions and styles

Eeach arrow definition (passed in the \@rrow_definitions list to the
DrawArrows) is a HASH reference consisting of some arrow options.
With the exception of -target, -originx, -originy, -deltax, -deltay,
these options can also be passed as \%common_arrow_options to
DrawArrows.

=over 8

=item -target

the target node.

If no target is specified, the target coordinates default to the
coordinates of the current node and the flags -deltax and -deltay must
be used to specify the target coordinates.

=item -originx

the x-coordinate of the origin (defaults to 'xn' - the x-coordinate of the current node)

=item -originy

the y-coordinate of the origin (defaults to 'yn' - the y-coordinate of the current node)

=item -deltax

value to add to the x-coordinate of the target

=item -deltay

value to add to the y-coordinate of the target

=item -smooth

1 to make the arrow a smoothed curve (see also -raise and -frac)

=item -frac

Defaults to 0.12. When a curved arrow is drawn (i.e. -smooth => 1 was
given), this value defines the 'lift' of the arrow as a fraction of
the length of the straight line connecting the start and end of the
arrow. 0 means no lift (straight line). The signum of the value
decides the orientation of the lift.

=item -raise

Defaults to 25. An absolute value added to the 'lift' of an arrow.

=item -arrow

one of 'first', 'last', 'both', 'none' (where to put the the arrow head)

=item -arrowshape

a comma-separated list of three integers defining the shape of the arrow head (see Tk::Canvas manual)

=item -dash

a comma-separated list of integers (even number) specifying the lengths of dashes and spaces between them

=item -width

width of the line

=item -fill

color of the line (either the color name or a '#rrggbb' hex code)

=item -hint

a tooltip that is displayed when the user hovers mouse over the arrow

=item -tag

a comma-separated list of tags associated with the arrow on the
canvas; tags can be used for varius purposes, e.g. to raise or lower
objects on the Tk::Canvas (see the stackOrder instruction in
L<http://ufal.mff.cuni.cz/~pajas/tred/ar01s10.html>).
they are also used as classes when exporting to SVG.

=item -decoration

decoration of the arrow (see description of the Line-decoration style
instruction in L<http://ufal.mff.cuni.cz/~pajas/tred/ar01s10.html>).

=back

=pod

=head1 non_projectivity.mak

An efficient algorighm for finding non-projectivity edges in ordered
trees.

=head2 USAGE

  #include <contrib/support/non_projectivity.mak>

  non_proj_edges($root);

=head2 MACROS

The following macros (functions) are provided by this package:

=over 5

=item non_proj_edges($node,$only_visible?,$ord?,$filterNode?,$returnParents?,$subord?,$filterGap?)

Returns hash-ref containing all non-projective edges in the subtree
rooted in $node. Values of the hash are references to arrays
containing the non-projective edges (the arrays contain the lower and
upper nodes representing the edge, and then the nodes causing the
non-projectivity of the edge), keys are concatenations of stringified
references to lower and upper nodes of non-projective
edges. Description of the arguments is as follows: $node specifies the
root of a subtree to be checked for non-projective edges;
$only_visible set to true confines the subtree to visible nodes; $ord
specifies the ordering attribute to be used; a subroutine accepting
one argument passed as sub-ref in $filterNode can be used to filter
the edges taken into account (by specifying the lower nodes of the
edges); sub-ref $returnParents accepting one argument returns an array
of upper nodes of the edges to be taken into account; sub-ref $subord
accepting two arguments returns 1 iff the first one is subordinated to
the second one; sub-ref $filterGap accepting one argument can be used
to filter nodes causing non-projectivity.  Defaults are: all nodes,
the default ordering attribute, all nodes, parent (in the technical
representation), subordination in the technical sense, all nodes.

=back

=head2 AUTHOR

Jiri Havelka

=head1 fold_subtree.inc

This file can add support for folding (collapsing) subtrees to any macro context.

=head2 USAGE

1. Add these lines to your macro context:

  #include <contrib/support/fold_subtree.inc>
  #bind fold_subtree_toggle to SOME_KEY  menu Fold/unfold current subtree (toggle)

and possibly

  #bind fold_subtree_unfold_all to OTHER_KEY menu Unfold all in the current subtree

replacing I<SOME_KEY> and I<OTHER_KEY> with suitable key bindings.

2. Add the following lines to your stylesheet:

  style:<? "#{Node-hide:1}" if FileUserData('hide')->{$this}; ?>
  style:<? "#{Oval-fill:blue}#{Node-shape:rectangle}"
              if FileUserData('fold')->{$this} ?>

The fist line does the folding, the second defines the visual style
for the root of a folded subtree (blue rectangle in this case). Adjust it
as you need.

=head1 unbind_edit.inc

Disable default TredMacro key-bindings that modify trees.

=head2 USAGE

  #include <common/support/unbind_edit.inc>

=head2 DESCRIPTION

Include this macro in your binding context if you want to disable all
default TredMacro key-bindings that modify trees, such as copy/paste,
etc.

Extensions can also use TredMacro::UnbindTreeEdit($context) function.

=pod

=head1 PML

PML.mak - Miscelaneous macros of general use in Prague Dependency
Treebank (PDT) 2.0

=head2 USAGE

  #include <contrib/pml/PML.mak>

=head2 MACROS

The following macros (functions) are provided by this package:

=over 4

=item PML::SchemaName()

Return name of the root element of a PML instance as specified in the
PML schema associated with the current file. PDT uses root element
named C<adata> for analytical layer annotation and C<tdata> for
tectogrammatical layer annotation.

=item PML::SchemaDescription()

Return the content of the element C<description> of the PML schema
associated with the current file.

=item PML::Schema($object?)

For a Treex::PML::Node object returns PML schema associated with that object.
If the object is a Treex::PML::Document, return PML schema associated with the given
file. If no object is given, the current Treex::PML::Document is used.

The PML schema is returned in form of a Treex::PML::Schema object.

=item PML::GetNodeByID($id_or_ref,$fsfile?)

Looks up a node from the current file (or given fsfile) by its ID (or
PMLREF - i.e. the ID preceded by a file prefix of the form C<xy#>).

=item PML::DeleteFromNodeHash($id,$fsfile?)

Deletes a given ID from a node HASH of the current or specified Treex::PML::Document
The node previously hashed under the given ID is returned.

=item PML::AddToNodeHash($id,$node,$fsfile?)

Adds a node to the node hash (of the given or current Treex::PML::Document) using
given ID as the hash key.

=item PML::SearchForNodeById($id)

Searches for node with given id. Returns the node and the number of
the tree.

=item PML::GetNodeHash($fsfile?)

Return a reference to a hash indexing nodes in a given file (or the
current file if no argument is given). If such a hash was not yet
created, it is built upon the first call to this function (or other
functions calling it, such as C<GetNodeByID>. Use C<clearNodeHash> to
clear the hash.

=item PML::ClearNodesHash($fsfile?)

Clear the internal hash indexing nodes of a given file (or the current
file if called without an argument).

=item PML::GotoTree()

Ask user for sentence or node identificator (tree number or id) and go to the
sentence.

=item PML::NonProjEdges($node,$ord?,$filterNode?,$returnParents?,$subord?,$filterGap?)

DEPRECATED, use non_proj_edges from <contrib/support/non_projectivity.mak> instead.

=back

