API Reference

anno.activateSelector(opt_item_url_or_callback, opt_callback)

Manually activates the selector on a specific item or globally. (The latter serves primarily as a shortcut for pages where there is only one annotatable item). Can take a callback function as parameter, which will be called when the selector is de-activated again.

NOTE: this method is currently relevant for the OpenLayers module only. Feel free to ignore in case you are only using the standard image annotation features of Annotorious.

anno.addAnnotation(annotation, opt_replace)

Adds a new annotation, or replaces an existing one. In the latter case, the parameter opt_replace is the annotation to replace.

Annotations are object literals, according to the following example:

var myAnnotation = {
    /** The URL of the image where the annotation should go **/
    src : 'http://www.example.com/myimage.jpg',

    /** The annotation text **/
    text : 'My annotation',

    /** The annotation shape **/
    shapes : [{
        /** The shape type **/
        type : 'rect',

        /** The shape geometry (relative coordinates) **/
        geometry : { x : 0.1, y: 0.1, width : 0.4, height: 0.3 }
    }]
}

Some notes on annotation shapes:

Although the shapes field requires an array of shapes, Annotorious currently uses the first shape in the array only. All other shapes are disregarded. (The array is there for future use, and for reasons of compatibility with other annotation systems.)
Currently, rect (rectangle) is the only supported shape type.
Per default, Annotorious uses a normalized coordinate system. The example above represents a rectangle that starts at a horizontal (vertical) distance of 10% of the image's width (height); has a width of 40% of the image's width; and a height of 30% of the image's height.

Using pixel coordinates: you can also use pixel coordinates for geometry. Example:

var myAnnotation = {
    /** The URL of the image where the annotation should go **/
    src : 'http://www.example.com/myimage.jpg',

    /** The annotation text **/
    text : 'My annotation',

    /** The annotation shape **/
    shapes : [{
        /** The shape type **/
        type : 'rect',

        /** 'units' only required for pixel coordinates **/
        units: 'pixel',

        /** The shape geometry (pixel coordinates) **/
        geometry : { x : 10, y: 10, width : 40, height: 60 }
    }]
}

Making annotations 'ready-only': in many cases, you won't want users to delete or edit the annotations you have added via the API. You can easily make them 'read-only' by adding an additional field to the object literal:

editable: false

If the field is set to false, there will be no delete icon in the annotation popup.

anno.addHandler(type, handler)

Adds an event handler function. Code example:

// Logs newly-created annotations to the console
anno.addHandler('onAnnotationCreated', function(annotation) {
    console.log(annotation.text);
});

You can register for the following events:

onMouseOverItem(event) - fired when the mouse enters an annotatable item
onMouseOutOfItem(event) - fired when the mouse leaves an annotatable item
onMouseOverAnnotation(event) - fired when the mouse enters an annotation
onMouseOutOfAnnotation(event) - fired when the mouse leaves an annotation
onSelectionStarted(event) - fired when the user starts a selection
onSelectionCanceled(event) - fired when the user cancels a selection (not available on all selection tools)
onSelectionCompleted(event) - fired when the user completes a selection
onSelectionChanged(event) - fired when the user changed a selection
onEditorShown(annotation) - fired when the editor opens to create a new or edit an existing annotation
onPopupShown(annotation) - fired when the annotation info popup window opens
beforePopupHide(popup) - fired just before the annotation info popup window hides
beforeAnnotationRemoved(annotation) - fired before an annotation is removed (Note: it is possible to prevent annotation removal by returning false from the handler function!)
onAnnotationRemoved(annotation) - fired when an annotation is removed from an item
onAnnotationCreated(annotation) - fired when an annotation was created
onAnnotationUpdated(annotation) - fired when an existing annotation was edited/updated

anno.addPlugin(pluginName, opt_config_options)

Registers a plugin. For more information, see the Plugins section

anno.destroy(opt_item_url)

Destroys annotation functionality. If opt_item_url is provided, only this item will be affected. Otherwise annotation functionality will be destroyed on all items on the page. Note that this method differs from anno.reset insofar as destroy does not re-evaluate the annotatable CSS attributes. What is destroyed, stays destroyed - until re-enabled through anno.makeAnnotatable.

anno.getAnnotations(opt_item_url)

Returns an array of annotations. If opt_item_url is provided, only annotations for this item will be returned. Otherwise all annotations on the page will be returned.

anno.hideAnnotations(opt_item_url)

Hides existing annotations on all, or a specific item.

anno.hideSelectionWidget(opt_item_url)

Disables the selection widget (the small tooltip in the upper left corner which says "Click and Drag to Annotate"), thus preventing users from creating new annotations. Typically, you will want to use this in conjunction with 'read-only' annotated images, so users can see existing annotations, but are not able to add any new ones.

anno.highlightAnnotation(annotation)

Highlights the specified annotation, just as if the mouse pointer was hovering over it. The annotation will remain highlighted until one of these conditions is met:

The user moves the mouse into, and out of the annotation
The user moves the mouse over another annotation
The highlight is removed by calling this method with an empty parameter (anno.highlightAnnotation() or anno.highlightAnnotation(undefined))
Another annotation is highlighted via anno.highlightAnnotation

anno.makeAnnotatable(item)

Makes an item annotatable (if there is a module available supporting the item format). You can use this method as an alternative to CSS-based activation. It works just the same way, and is simply there for convenience, and for item formats that technically don't support CSS-based activation (such as zoomable images).

anno.removeAll(opt_item_url)

Removes all annotations. If the optional parameter opt_item_url is set, only the annotations on the specified item will be removed. Otherwise all annotations on all items on the page will be removed.

anno.removeAnnotation(annotation)

Removes an annotation.

anno.reset()

Performs a 'hard reset' on Annotorious. This means that all annotation features will be removed, and the page will be re-scanned for items with the 'annotatable' CSS class. (Note: this method could be handy in case you are working with JavaScript image carousels. Just make sure the images have 'annotatable' set, then reset Annotorious after each page flip.)

anno.setProperties(properties)

Sets global properties on Annotorious. Code example:

// Sets the annotation shape's outline to red  
anno.setProperties({
  outline: 'red'
});

Currently supported property values are:

outline: outline color for annotation and selection shapes
stroke: stroke color for annotation and selection shapes
fill: fill color for annotation and selection shapes
hi_stroke: stroke color for highlighted annotation shapes
hi_fill fill color for highlighted annotation shapes
outline_width: outline width for annotation and selection shapes
stroke_width: stroke width for annotation and selection shapes
hi_outline_width: outline width for highlighted annotation shapes
hi_stroke_width: stroke width for highlighted annotation shapes

anno.showAnnotations(opt_item_url)

Shows existing annotations on all, or a specific item (if they were hidden using anno.hideAnnotations).

anno.showSelectionWidget(opt_item_url)

Enables the selection widget (the small tooltip in the upper left corner that says "Click and Drag to Annotate"), thus enabling users to creating new annotations. (Per default, the selection widget is enabled.)