# contrib documentation

### Table of contents

- arrows.inc
  - USAGE
  - DESCRIPTION
    - Arrow definitions and styles
- non_projectivity.mak
  - USAGE
  - MACROS
  - AUTHOR
- fold_subtree.inc
  - USAGE
- unbind_edit.inc
  - USAGE
  - DESCRIPTION
- PML
  - USAGE
  - MACROS

# arrows.inc

ToC

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

## 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
          });
        #...
      }

## 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:

1.

  include <contrib/support/arrows.inc>

2.

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

3.

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

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.

### 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.

-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.

-originx

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

-originy

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

-deltax

  value to add to the x-coordinate of the target

-deltay

  value to add to the y-coordinate of the target

-smooth

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

-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.

-raise

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

-arrow

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

-arrowshape

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

-dash

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

-width

  width of the line

-fill

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

-hint

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

-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 http://ufal.mff.cuni.cz/~pajas/tred/ar01s10.html). they are also used as classes when exporting to SVG.

-decoration

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

# non_projectivity.mak

ToC

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

## USAGE

      #include <contrib/support/non_projectivity.mak>

      non_proj_edges($root);

## MACROS

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

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.

## AUTHOR

Jiri Havelka

# fold_subtree.inc

ToC

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

## 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 SOME_KEY and 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.

# unbind_edit.inc

ToC

Disable default TredMacro key-bindings that modify trees.

## USAGE

      #include <common/support/unbind_edit.inc>

## 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.

# PML

ToC

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

## USAGE

      #include <contrib/pml/PML.mak>

## MACROS

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

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 `adata` for analytical layer annotation and `tdata` for tectogrammatical layer annotation.

PML::SchemaDescription()

  Return the content of the element `description` of the PML schema associated with the current file.

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.

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 `xy#`).

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.

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.

PML::SearchForNodeById($id)

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

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 `GetNodeByID`. Use `clearNodeHash` to clear the hash.

PML::ClearNodesHash($fsfile?)

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

PML::GotoTree()

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

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

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