Update older annotation items to new framework

[nyalldawson]

QGIS Enhancement: Update older annotation items to new framework

Date 2023/05/02

Author Nyall Dawson (@nyalldawson)

Contact nyall dot dawson at gmail dot com

maintainer @nyalldawson

Version QGIS 3.34

Summary

For decades, QGIS supported a few "annotation" item types for drawing over map canvases: text, HTML, SVG and "form" annotations. In version 3.16 a new framework for handling annotations and annotation layers was added to QGIS which was designed around modern requirements and provided a more flexible approach for annotations. This newer framework supports point, line, polygon, text-at-point and text-along-line annotations.

In order to keep existing workflows unaffected, the older annotation items (text, html, svg and form) were left untouched during the introduction of the newer framework. The unfortunate side effect of this is that users have two completely different annotation types used in QGIS, and each has a completely different means of creation, interaction and handling.

This proposal concerns moving some of the older annotation types (specifically "text" and "svg") over to the newer framework, in order to provide a more consistent and user friendly interface to QGIS users. Porting the remaining older annotation types ("html" and "form") is left as a potential follow up project. The Text and SVG items are targeted here as they are more widely used and consequently command a higher priority.

Missing Functionality

Some feature gaps exist between the existing Text and SVG annotation items and what is possible in the newer annotation layer framework. Specifically:

1. The older annotations can be associated with another map layer, and their visibility will be controlled by the visibility of that layer.
2. The older annotations can be associated with a fixed point on the map, and have support for controlling the appearance of a marker at that point.
3. The older annotations can be styled with a balloon-callout style appearance pointing to the map marker.
4. The older text annotation item has a rich text edit GUI allowing easy control over formatting of text (text color, font family, font size and bold/italic styles).

This functionality will need to be made available to the newer annotation layer framework in order to avoid loss of features.

Proposed Solution/Deliverables

First, the missing functionality described in the above section will be added to the newer QgsAnnotationItem and QgsAnnotationLayer class.

Specifically:

• setLinkedVisibilityLayer() / linkedVisibilityLayer() will be added to QgsAnnotationLayer, and exposed through the Annotation Layer Properties dialog (under the "Rendering" tab). This will provide a means to control the visibility of an entire annotation layer (i.e. group of annotations) by toggling the visibility of a second map layer. (Addresses missing function # 1)
• The ability to set an associated fixed point on the map will be added to QgsAnnotationItem, and exposed for the "Text at Point" and "Text along Line" annotation types. API will be added to allow a QgsMarkerSymbol to be set for this fixed map point, and this functionality will be exposed in the GUI for these annotation item types. (Addresses missing function # 2)
• The "Text at Point" and "Text Along Line" items types will permit a QgsCallout to be set and used while rendering. This will allow these item types to be styled using the same balloon style appearance as the older Text annotation type. (Addresses missing function # 3)
• The QgsRichTextEditor widget class will be extended to permit a limited editing mode, which only exposes the HTML formatting subset supported for rendering text annotations (i.e. font color, family, size, style and decoration). The widget for editing text annotation items will be reworked to use the rich text editor. (Addresses missing function # 4).

Then, a new QgsAnnotationPictureItem class will be created which allows for a (linked or embedded) picture to be shown on the map. This item will support SVG and raster image formats, and is intended as a direct replacement for the existing older SVG annotation type.

Finally, code will be added to QgsProject to ensure that the older text and SVG annotations are automatically translated to their newer annotation item equivalents so that older projects will appear correctly when loaded into newer QGIS releases.

Example(s)

(optional)

Affected Files

• QgsAnnotationLayer
• QgsAnnotationItem
• QgsAnnotationPointTextItem
• QgsAnnotationLineTextItem
• QgsRichTextEditor
• associated unit test files

Performance Implications

None

Further Considerations/Improvements

(optional)

Backwards Compatibility

Projects created using the replacement item types will NOT be compatible with earlier QGIS releases. These annotations will disappear from the projects if opened in these older releases.

Issue Tracking ID(s)

• Bug / Feature request: all elements of annotation toolbar should be drawn to custom annotation layer QGIS#48584
• Expression editor to Text Annotations QGIS#37828
• Annotation display filtering via layers or map views QGIS#27841

Votes

(required)

[anitagraser]

Thank you for submitting your proposal to the 2024 QGIS Grant Programme. The 2 week discussion period starts today. At the end of the discussion, the proposal author has to provide a 3-line pitch of their proposal for the voter information material. (For an example from last year check qgis/PSC#58 (comment))