Angular Chart User Annotation Layer

    In Ignite UI for Angular, you can annotate the IgxDataChartComponent with slice, strip, and point annotations at runtime using the user annotations feature. This allows the end user to add more details to the plot such as calling out single important events such as company quarter reports by using the slice annotation or events that have a duration by using the strip annotation. You can also call out individual points on the plotted series by using the point annotation or any combination of these three.

    This is directly integrated with the available tools of the IgxToolbarComponent. The following topic explains, with examples, how you can utilize the IgxToolbarComponent to add user annotations to the plot area of the chart, as well as how to do add these user annotations programmatically.

    [!Note] This feature is designed to support X and Y axes and does not currently support radial or angular axes.

    Using the User Annotations with the Toolbar

    The IgxToolbarComponent exposes an Annotations menu item with two tools with the labels of "Annotate Chart" and "Delete Note." In order for this menu item to appear, you first need to set the isUserAnnotationsEnabled property on the corresponding chart to true.

    The "Annotate Chart" option that appears after opening allows you to annotate the plot area of the IgxDataChartComponent. This can be done by adding slice, strip, or point annotations. You can add a slice annotation by clicking on a label on the X or Y axis. You can add a strip annotation by clicking and dragging in the plot area. Also, you can add a point annotation by clicking on a point in a series plotted in the chart.

    Angular user-annotation-create

    You can delete the annotations that you have previously added by selecting the "Delete Note" menu item and then clicking on the axis annotation for the slice or strip user annotations, or by clicking the corresponding data point for the point user annotation.

    Angular user-annotation-delete

    When adding one of these user annotations via the XamToolbar, the IgxDataChartComponent will raise an event named UserAnnotationInformationRequested where you can provide more information for the user annotations. This event's arguments have a property named AnnotationInfo that will return a IgxUserAnnotationInformation object that allows the configuration of multiple different aspects of the annotation to be added.

    The table below details the different configurable properties on IgxUserAnnotationInformation:

    Property Type Description
    annotationData string This property allows additional information for the user annotation. This property is designed to be utilized with the UserAnnotationToolTipContentUpdating event to show additional information in the annotation's tooltip.
    annotationId string This read-only property returns the unique string ID of the user annotation.
    badgeColor string This property gets or sets the color to use for the badge in the user annotation.
    badgeImageUri string This property gets or sets a path to an image to use for the badge in the user annotation.
    dialogSuggestedXLocation double This property gets a recommended X location to show a dialog based on the location that the user annotation was added.
    dialogSuggestedYLocation double This property gets a recommended Y location to show a dialog based on the location that the user annotation was added.
    label string This property gets or sets the label to be shown in the user annotation.
    mainColor string This property gets or sets the color to be used to fill the background of the user annotation.

    After you have made the changes to the annotation through the UserAnnotationInformationRequested event, you should invoke the finishAnnotationFlow method on the IgxDataChartComponent to finish creating the annotation and commit the changes to it. Alternatively, you can also cancel the annotation's creation by calling cancelAnnotationFlow and passing the annotationId of the annotation, which can be obtained from the AnnotationInfo parameter of the UserAnnotationInformationRequested event's arguments, as mentioned above. This will remove the annotation from the plot area.

    Using the User Annotations Programmatically

    When using the IgxUserAnnotationLayerComponent programmatically, you can invoke two different methods on the IgxDataChartComponent to put the chart into a mode where you can add or remove a user annotation. These methods are named startCreatingAnnotation and startDeletingAnnotation, respectively.

    After invoking startCreatingAnnotation, you can add a slice annotation by clicking on a label on the X or Y axis, add a strip annotation by clicking and dragging in the plot area and releasing the mouse button, or add a point annotation by clicking on a data point on a series plotted in the chart.

    Adding one of these user annotations will raise an event named UserAnnotationInformationRequested, where you can provide more information for the user annotation. This event's arguments have a property named AnnotationInfo that will return a IgxUserAnnotationInformation object that allows the configuration of multiple different aspects of the annotation to be added.

    After you have made the changes to the annotation through the UserAnnotationInformationRequested event, you should invoke the finishAnnotationFlow method on the IgxDataChartComponent to finish creating the annotation and commit the changes to it. Alternatively, you can also cancel the annotation's creation by calling cancelAnnotationFlow and passing the annotationId of the annotation, which can be obtained from the AnnotationInfo parameter of the UserAnnotationInformationRequested event's arguments, as mentioned above. This will remove the annotation from the plot area.

    Once the user annotation has been added to the chart, it will appear in the IgxSeriesComponent collection as a IgxUserAnnotationLayerComponent. The IgxUserAnnotationLayerComponent has an annotations collection that can store IgxUserSliceAnnotation, IgxUserStripAnnotation and IgxUserPointAnnotation elements depending on the type of annotations added to the plot area.

    User Annotation ToolTip

    Each of the user annotations can show a tooltip on mouse hover to add even more detail to the annotations.

    The chart exposes a UserAnnotationToolTipContentUpdating event that you can handle to update the content of the tooltip for the user annotation as the tooltip is shown. The event arguments of this event exposes two properties: Content and AnnotationInfo.

    The tooltip is designed to work in tandem with the UserAnnotationInformationRequested event so that you can provide more detail to the user annotation via that event's annotationData property. The AnnotationInfo property on the event arguments of the UserAnnotationToolTipContentUpdating event will be the same instance as the AnnotationInfo property in the UserAnnotationInformationRequested that you can modify in that event. This allows you to utilize the information provided to the user annotation on its creation and provide even more information within the tooltip.

    API References

    The following is a list of API members mentioned in the above sections:

    Additional Resources

    You can find more information about related chart features in these topics: