net.sourceforge.nite.tools.videolabeler
Class AnnotationLayer

java.lang.Object
  extended by net.sourceforge.nite.tools.videolabeler.AnnotationLayer
Direct Known Subclasses:
FeeltraceAnnotationLayer, LabelAnnotationLayer

public abstract class AnnotationLayer
extends java.lang.Object

An annotation layer encapsulates some layer-dependent properties. This class acts like a wrapper around an NXT layer that is specified at construction. The underlying layer and the code element that is used for the annotations in this layer, are obtained with getNLayer) and getCodeElement().

This class defines some properties that are used to display annotations in an AnnotationFrame or ViewFrame. An annotation frame consists of two or three parts. At the top there is an annotation area (if showAnnotationArea() returns true), which displays all annotations for the layer (and possibly an agent). It uses the element formatter returned by getElementFormatter() to display an annotation in an annotation area. The styles that are returned by getStyleMap() are added to the annotation area, so they can be used by the element formatter. In the middle of an annotation frame there is an annotation control panel, which displays (among others) the current annotation's start time, end time and label. The label is obtained with getLabel(). At the bottom of the annotation frame there is a target control panel, which allows the user to make annotations. It is completely layer-dependent. The panel is obtained with createTargetControlPanel().

Two more methods are needed to update the corpus when annotations are created or deleted. These methods are createGap() and sameTargets().

This abstract base class uses a GenericElementFormatter, which is stored in the protected variable elementFormatter, and it handles the creation of target control panels according to the guidelines of the class AnnotationLayerFactory. Subclasses only need to implement the abstract methods, but they may also override getStyleMap() and showAnnotationArea().


Constructor Summary
AnnotationLayer(NLayer layer, java.lang.String codeName, java.lang.String panelType, org.w3c.dom.Node layerInfo)
          Constructs a new annotation layer for the specified NXT layer.
 
Method Summary
abstract  void createGap(NOMElement annotation, double startTime, double endTime)
          Splits an annotation, so there will be a gap between the specified start time and end time.
 TargetControlPanel createTargetControlPanel(AnnotationFrame frame, NAgent agent)
          Creates a new target control panel for this layer and the specified agent.
 NElement getCodeElement()
          Returns the code element for annotations in this layer.
 ElementFormatter getElementFormatter()
          Returns the element formatter that is used to display annotations in an annotation area.
abstract  java.lang.String getLabel(NOMElement annotation)
          Returns the label of an annotation in this layer.
 NLayer getNLayer()
          Returns the underlying NXT layer of this annotation layer.
 java.util.HashMap getStyleMap()
          Returns a hash map that maps style names (String) to styles (Style).
abstract  boolean sameTargets(NOMElement elem1, NOMElement elem2)
          Compares two annotations and returns true if they have the same target.
 boolean showAnnotationArea()
          Determines whether the annotation area should be shown in the annotation frame.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

AnnotationLayer

public AnnotationLayer(NLayer layer,
                       java.lang.String codeName,
                       java.lang.String panelType,
                       org.w3c.dom.Node layerInfo)
                throws java.lang.ClassNotFoundException,
                       java.lang.NoSuchMethodException,
                       java.lang.Exception

Constructs a new annotation layer for the specified NXT layer. The panelType parameter should be the qualified name of the class for the target control panels returned by createTargetControlPanel(). The class should be a subclass of TargetControlPanel and the constructor should have the same type as the constructor of TargetControlPanel.

If the specified target control panel class could not be found or if the required constructor could not be found, this constructor throws an exception. Subclasses may throw additional exceptions. Other exceptions might occur in createTargetControlPanel().

Parameters:
layer - an NXT layer
codeName - the name of the code elements that represent the annotations in this layer
panelType - the qualified class name of the target control panels
layerInfo - the layer info element from the configuration file
Throws:
java.lang.ClassNotFoundException - if the class specified in panelType was not found
java.lang.NoSuchMethodException - if the class specified in panelType does not have a constructor that takes one argument of type AnnotationLayer
java.lang.Exception - if another error occurs
Method Detail

getNLayer

public NLayer getNLayer()

Returns the underlying NXT layer of this annotation layer.

Returns:
the underlying NXT layer of this annotation layer

getCodeElement

public NElement getCodeElement()

Returns the code element for annotations in this layer.

Returns:
the code element for annotations in this layer

getStyleMap

public java.util.HashMap getStyleMap()

Returns a hash map that maps style names (String) to styles (Style). This method returns an empty hash map.

Returns:
an empty hash map

showAnnotationArea

public boolean showAnnotationArea()

Determines whether the annotation area should be shown in the annotation frame. By default this method returns true.

Returns:
true if the annotation area should be shown, false otherwise

getElementFormatter

public ElementFormatter getElementFormatter()

Returns the element formatter that is used to display annotations in an annotation area. This method returns an instance of GenericElementFormatter.

Returns:
an element formatter

getLabel

public abstract java.lang.String getLabel(NOMElement annotation)

Returns the label of an annotation in this layer. If the label could not be retrieved, an error is printed to standard output and this method returns null.

Parameters:
annotation - an annotation in this layer
Returns:
the label of the specified annotation or null

createGap

public abstract void createGap(NOMElement annotation,
                               double startTime,
                               double endTime)
                        throws java.lang.Exception

Splits an annotation, so there will be a gap between the specified start time and end time. The specified annotation must start before the start time and it must end after the end time. This method is called when a new annotation is going to be added between the specified start and end time. The method is called from the Document class and implementations of this method are free to edit the corpus without notifying document listeners.

Parameters:
annotation - the annotation that will be split
startTime - the time where the gap will start
endTime - the time where the gap will end
Throws:
java.lang.Exception - if an error occurs

sameTargets

public abstract boolean sameTargets(NOMElement elem1,
                                    NOMElement elem2)

Compares two annotations and returns true if they have the same target. If the two annotations are adjacent, it means they can be merged into one annotation.

Parameters:
elem1 - the first annotation
elem2 - the second annotation
Returns:
true if both annotations have the same target, false otherwise

createTargetControlPanel

public TargetControlPanel createTargetControlPanel(AnnotationFrame frame,
                                                   NAgent agent)

Creates a new target control panel for this layer and the specified agent. The agent parameter may be null if the layer belongs to an interaction coding rather than an agent coding. The target control panel will be of the type that was specified at construction. If the panel could not be created, an error is printed to standard output and this method returns null.

Parameters:
frame - the annotation frame that will contain the target control panel
agent - an agent (if the layer belongs to an agent coding) or null (if the layer belongs to an interaction coding)
Returns:
the new target control panel or null