Custom Annotations

Custom annotation ranges provide an approach for extending the document model to serve specific purposes such as persisting semantic information in the document. This article will list the steps which should be followed in order to create a custom AnnotationRange with a specific behavior.

For general information on Annotations, please refer to these articles:

• Annotations

• Manipulating Annotations

This topic explains:

• Creating Custom Annotation

• Customizing Annotations

• Serialization

Creating a Custom Annotation

The most common scenarios for the use of custom annotations is for associating semantic data to a part of the document. In order to fulfill this task, you can implement custom annotation ranges. The steps to do so are:

• Create two classes deriving from AnnotationRangeStart and AnnotationRangeEnd respectively. Depending on the behavior you would like to achieve, you can also inherit from some of the already implemented annotation ranges, such as FieldRangeStart/FieldRangeEnd.

• Override the CreateNewElementInstance method and have it return an instance of your annotation range start/end in both classes. Override the required CopyContentFromOverride method as well. In most cases, it should be left empty.

protected override DocumentElement CreateNewElementInstance()
{
    return new CustomAnnotationRangeStart();
}

protected override void CopyContentFromOverride(DocumentElement fromElement)
{
}

Protected Overrides Function CreateNewElementInstance() As DocumentElement
    Return New CustomAnnotationRangeStart()
End Function
Protected Overrides Sub CopyContentFromOverride(ByVal fromElement As DocumentElement)
End Sub

• Override the CreateRangeStartInstance in the RangeEnd class.

protected override AnnotationRangeStart CreateRangeStartInstance()
{
    return new CustomAnnotationRangeStart();
}

Protected Overrides Function CreateRangeStartInstance() As AnnotationRangeStart
    Return New CustomAnnotationRangeStart()
End Function

At this point, you will have the basic functionality working and can continue to customize the behavior of the ranges, i.e. if it will be possible to edit the content in them, what will be the behavior when you hit backspace or delete, if it will be possible to copy the ranges, etc.

Customizing Annotations

The behavior of the annotations when edited, copied and deleted is determined by the following properties and methods which you can override:

• IsCopyable - specifies if the inline can be copied and pasted somewhere else in the document. The start and end must have the same value in order to have proper behavior. For example, BookmarkRangeStart and End are not copyable, while CommentRangeStart and End are copyable.

• CopyPropertiesFromOverride - this method should be used when you have custom properties you would like to have copied. This should be done as follows:

protected override void CopyPropertiesFromOverride(DocumentElement fromElement)
{
    base.CopyPropertiesFromOverride(fromElement);
    this.Name = ((CustomAnnotationRangeStart)fromElement).Name;
}

Protected Overrides Sub CopyPropertiesFromOverride(ByVal fromElement As DocumentElement)
    MyBase.CopyPropertiesFromOverride(fromElement)
    Me.Name = CType(fromElement, CustomAnnotationRangeStart).Name
End Sub

• SkipPositionBefore - specifies where text will appear if you position the caret next to the range start/end. For example, if it returns true in the range start and false in the range end, the text you enter when you position the caret next to the start/end, will appear in the range.

• SkipPositionsInRange of AnnotationRangeStart - you can set this property to false, which will disable the option to edit the content of the range, i.e. it may be possible to delete the range altogether, but it will not be possible to position the caret in the range, select or edit only part of the range.

• DeleteBehavior, BackspaceBehavior, DeleteSelectedBehavior - you can customize these behaviors by choosing from the options in the enum AnnotationMarkerDeleteBehavior: PreserveAnnotation, SelectAnnotation, RemoveAnnotation, SelectAnnotationMarker. For example, hyperlinks keep the default settings in FieldRangeStart and FieldRangeEnd, which are:

HyperlinkRangeStart:

public override AnnotationMarkerDeleteBehavior DeleteBehavior
{
    get
    {
        return AnnotationMarkerDeleteBehavior.SelectAnnotation;
    }
}

public override AnnotationMarkerDeleteBehavior BackspaceBehavior
{
    get
    {
        return AnnotationMarkerDeleteBehavior.SelectAnnotation;
    }
}

public override AnnotationMarkerDeleteBehavior DeleteSelectedBehavior
{
    get
    {
        return AnnotationMarkerDeleteBehavior.RemoveAnnotation;
    }
}

Public Overrides ReadOnly Property DeleteBehavior() As AnnotationMarkerDeleteBehavior
    Get
        Return AnnotationMarkerDeleteBehavior.SelectAnnotation
    End Get
End Property
Public Overrides ReadOnly Property BackspaceBehavior() As AnnotationMarkerDeleteBehavior
    Get
        Return AnnotationMarkerDeleteBehavior.SelectAnnotation
    End Get
End Property
Public Overrides ReadOnly Property DeleteSelectedBehavior() As AnnotationMarkerDeleteBehavior
    Get
        Return AnnotationMarkerDeleteBehavior.RemoveAnnotation
    End Get
End Property

HyperlinkRangeEnd:

public override AnnotationMarkerDeleteBehavior DeleteBehavior
{
    get
    {
        return AnnotationMarkerDeleteBehavior.PreserveAnnotation;
    }
}

public override AnnotationMarkerDeleteBehavior BackspaceBehavior
{
    get
    {
        return AnnotationMarkerDeleteBehavior.RemoveAnnotation;
    }
}

public override AnnotationMarkerDeleteBehavior DeleteSelectedBehavior
{
    get
    {
        return AnnotationMarkerDeleteBehavior.RemoveAnnotation;
    }
}

Public Overrides ReadOnly Property DeleteBehavior() As AnnotationMarkerDeleteBehavior
    Get
        Return AnnotationMarkerDeleteBehavior.PreserveAnnotation
    End Get
End Property
Public Overrides ReadOnly Property BackspaceBehavior() As AnnotationMarkerDeleteBehavior
    Get
        Return AnnotationMarkerDeleteBehavior.RemoveAnnotation
    End Get
End Property
Public Overrides ReadOnly Property DeleteSelectedBehavior() As AnnotationMarkerDeleteBehavior
    Get
        Return AnnotationMarkerDeleteBehavior.RemoveAnnotation
    End Get
End Property

• You can also define custom properties in your annotation range start/end. If you want to be able to serialize them, you can just mark them with the XamlSerializable attribute:

[XamlSerializable]
public string Name { get; set; }

<XamlSerializable>
Public Property Name() As String

Serialization

Of the default document format providers, custom annotations are supported only in XAML. The other formats do not offer such extensibility. When exporting to XAML, the exporter will generate prefixes for each custom annotation namespace (custom1, custom2, etc.). Serialization is handled by XamlFormatProvider which looks for properties with the appropriate attributes: XamlSerializable (as inline properties) and XamlCompositePropertySerializable (as XAML composite properties).