Figure annotations lets Apps highlight a figure including some text to give the user feedback. Annotations are Canvas dependent, you may spawn multiple Canvas over the same document showing different annotations in each of them.

The basic API is the following:

// Annotate figures with a given message and a highlight them with a box
canvas.annotate( , { text: 'Message', pen: pen });

This will annotate each of the figures with the text message over the highlight rectangle draw using the given pen.

The first parameter is actually quite flexible because there are different kind of scenarios where this feature will be useful.

// Annotate a single figure    
canvas.annotate( figure, { ... } );
// Annotate multiple figures
canvas.annotate( figures, { ... } );
// You can also tell the system to only draw one annotation for the figures with    
canvas.annotate( figures, { grouped: true, ... } );

These versions are useful, but normally applications will have some rules that defines when a figure should be annotated. The app could work the sync of the annotations after each commit but Canvas gives a tool for this common case that will simplify the work:

// Annotate every figure conditionally
canvas.annotate( function(figure){ ... return true if it should be annotated ... }, { ... } );
// Example, apply an annotation to each Text
canvas.annotate( function(figure){ return figure instanceof Cx.Text; }, { ... } );

You basically pass a filter function that will be used to dynamically find to which figures this annotation needs to be drawn. There is one shortcut in place if you just want to annotate every figure (also dynamically):

// Annotate all figures, same as function(figure){ return true; } 
canvas.annotate( 'all', { ... } );

The basic parameters that you give to the annotation are:

Lets use a dynamic annotation to give feedback to the user about a probable date issue in its template:

// Annotate text that looks like date with "Not 2014?"   
canvas.annotate( function(figure){
  if( figure instanceof Cx.Text ){
    var year = parseInt(figure.text(),10);
    if( 2000 < year && year < 2014 )   
      return true;
  }
  return false;
},{
  text: 'Not 2014?',
  pen: Cx.Pen({color:Cx.Color({rgb:'F04111'})})
});
canvas.render$();

Here is what the user will see:

In this case the message is the same for all figures that pass the condition. But if you use dynamic annotations, you will normally want to set an individual message for each figure. Each of the annotation parameters accepts a function that takes a figure and returns the processed value. A good example, lets show the bounds of each figure to the user as an annotation:

// Annotate all figures with their bounds extents
canvas.annotate( 'all', {
  pen: Cx.Pen({color:{rgb:'9A8CDB'}}),
   text: function(figure){
    var bounds = figure.bounds_(); 
    return bounds.width().toFixed(0) + ' x ' +
             bounds.height().toFixed(0) + ' mm';  
  }
});
canvas.render$();

Important The functions passed to annotate can safely use the sync version of the figure metrics ( figure.bounds_() ). Canvas will only produce the annotation when the figure has been properly updated. This will simplify a lot of use cases that involves metrics, like annotate to small or to big figures.

We can play with the box style, use dashed lines. Or only show the text. For example, if you do not pass any pen. The result will look like:

This looks really nice in this example, but it will be confusing if there are many overlapped figures. But I like the idea of having less noise so we can show annotations without the fear of covering everything with lines.

You have the option to use a different box style, using the boxStyle parameter. Only the default and ‘Clean’ is supported for the moment. The ‘Clean’ style only draws the corners of the box, so it looks like:

It is also possible to use overlapping annotations, the system will just place the messages on top of each other. But it is a good idea to avoid using to many annotations at the same time, and give the user some way to choose what he want to see.

If you want to remove the annotation, keep a reference to it and pass that to the Canvas unannotate function like:

var ann = canvas.annotate( figures, { ... } );
// later...
canvas.unannotate( ann );

You can also just clear all the annotations using:

canvas.clearAnnotations();