New Labeling changes, issues and roadmap

This is a listing of changes (current and ongoing) to the new labeling engine (aka PAL, advanced, or ng), label tools and GUI since QGIS 1.8 and prior to 2.0, including current issues, and a roadmap for future changes. Any comments or ideas are very welcome.

Contact: Larry Shaffer, larrys [at] dakotacarto [dot] com, dakcarto on #qgis

See also: Switching from Old to New Symbology and Labeling

Changes, issues and 2.0 release feature set

PAL engine (PAL lib and QgsPalLabeling class)

  • ✓ [#6325][d8675ba] Python binding for QgsPalLayerSettings and QgsPalLabeling classes (thanks Juergen)
  • [#3975] Labels should be preserved as text in SVG output (as with old labeling engine)
    • Move from QPainterPath::addText back to QPainter::drawText()?
  • [#3517, #2949, #2812] Add to QgsPalLayerSettings an attempt to fix invalid feature geometry prior to the feature being registered with PAL (which otherwise will ignore it)
    • Actual geometry fixing method should probably reside in QgsGeometry
  • See curved labels under Placement options
  • [#3219, #2180] Add label background symbol feature
    • Ideally SVG with x/y buffers in mm or map units to scale around label text size
    • X/Y Offsets (offsetting the background so the label text is over a particular 'location' in the SVG)
    • Rotation (whether to rotate background with the label, or always stay upright or at particular angle while the label text still rotates)
    • SVG could be parameterized to have some of its elements set to chosen colors
    • See description in mailing list post


  • ✓ [#2249, #4385][547a05a, 7079f20] Fix sample label preview
    • Add preview for multi-line option
  • Save/restore which tab user is on
  • Disable multi-line options when curved labels placement is selected
    • (implement in later version, if reasonably possible to do)
  • Redesign GUI to prepare for styles and rule-based setup
    • Integrate data defined mappings beside base layer options
    • Create custom tool button or combo box class to help with mappings integration
    • Add indications that a given option is overridden by a data defined mapping, and that a data definition exists, but is off
    • Separate an option's on/off state from it value (values should always be preserved, not reset when turning off an option)
    • Design should allow should allow different styles to be loaded (when implemented), with or without data defined mappings
    • Fix disabling of options (e.g. buffer groupbox) clearing children settings

Label options

  • ✓ [538ebe0] Add label text transparency option
  • ✓ [538ebe0] Add label buffer transparency option
  • ✓ [7079f20] Add label buffer pen join styles option
  • ✓ [7079f20] Add option to hide interior fill of buffer
  • ✓ [7079f20] Add map units to buffer
  • ✓ [31d1b95] Add letter and word spacing options
  • ✓ [0386a63] Add capitalization options
    • Add Title Case option that works like Juergen's in Expression Editor
  • ✓ [eaecf0c] Add font named styles option
  • ✓ [eaecf0c] Add underline and strikeout buttons
  • ✓ [e08833a] Add multi-line height (typographic 'leading') adjustment to label drawing
  • ✓ [e08833a] Add multi-line alignment options
  • Add default label text (like with old labeling engine)
  • Add label text truncation option, removing characters until label fits feature (suggested by Nathan)
    • Additional options for minimum required characters and whether truncation is from right or left
  • Add label scale-to-fit option, where label's font size is scaled until it fits feature
    • Additional option for minimum scaled-down font size
  • ✓ [e5f07ed] Add defined minimum/maximum rendered pixel size for font label text (useful for label sizes defined in map units)
  • Remove Formatted Number in favor of expression?
    • Use expressions for all text formatting?

Advanced options

  • ✓ [a584a9a] Add option to show all labels (including colliding) for individual layer
  • ✓ [#6482, #5593][e125e98] Add option for showing upside-down label text as upside-down
  • Add map units option to 'Suppress labeling of features smaller than' option
  • ✓ [bb947b4] Add option to set character glyph to be used for direction indicator
    • ✓ Add option to reverse indicator direction (suggested by Sandro Santilli, e.g. for topology viewer)
  • ✓ [f210668, e3d30af] Add option to limit total number of features sent to PAL per layer (suggested by Sandro Santilli, e.g. for topology viewer)
    • does not guarantee the features will be labeled by PAL
    • Add option to have limited number be a randomized subset of total feature count (maybe be slow for large feature sets to create random sequence set)
  • Add option to 'show n number of labels' to be done after PAL solution (no speed increase)
    • Limits labels only for clarity, but should always show 'n number' of labels on canvas
  • Add option to 'show every n-th label'
  • [#4850] Add saving of PAL engine properties per project
  • [#4719] Fix or remove broken inactive options

Placement options

  • Add 'Midpoint' as new placement for line layers (midpoint of visible or whole line feature)
    • Add quadrant/offset/rotation/visible-or-whole options (i.e. treat like Offset point feature placement)
  • Add option to have boundaries of map canvas's current extent act as obstacles to labels (suggested by Tim Sutton)
    • Convert rectangle of extent to polygon, lines, or points, relative to layer type, and add to temporary features sent to PAL?
  • Add layer-level and data defined rotation for 'around' placements
  • Add option to set centroid to whole multi-polygon instead of just largest
  • ✓ [f143507] Add option to choose centroid of visible or whole feature
  • ✓ [#6118, #6285, #3492][61a5022] Add quadrant, offset, rotation for points/centroids
  • ✓ [#5256, #4634, #6162][5c29413] Centroid calculation update (provided by Serge Dikiy)
    • Make path accessible by other tools
  • [#5232] Fix direction symbol not showing up for curved labels
  • Change curved labeling output to single QPainterPath?
  • [#6200, #6439, #4442, #2113] Solution for issues with curved labels
    • Specific label path stored in separate data source or memory layer

Data defined options

  • Add expression editor integration as an alternative to a mapping, for all options
    • Similar to how the text for the label is defined with an expression or mapping
    • Using CASE function of exp editor allows for a limited 'rule'-based setup, especially now that custom functions can be added to exp editor
  • ✓ [2fbc98e] Add show label mapping
  • ✓ [2263435] Add scale-based visibility mapping
  • ✓ [#6373] [036d844] Fix font size not entirely overriding layer-level font size
  • Option to preserve existing label position when adding/changing Hali/Vali
    • Honor option in Change Label tool
  • Add quadrant mapping
  • Add x/y offsets mapping
  • Add font named style mapping
  • Add unit choice mappings for font/buffer/offsets/distance
  • Add buffer join mapping
  • Add buffer fill mapping
  • Add multi-line height mapping
  • Add multi-line alignment mapping
  • ✓ [15fe992] Add 'always show label' mapping (skip priority, suggested by Nathan Woodrow)
  • [#4606] Add priority mapping
  • ✓ [#4317, #4517, #3651][8a347eb] Add data defined rotation independent of x/y being defined (thanks Juergen)
  • ✓ [6cfb060] Add option to preserve existing rotation values in attribute table for pinning/unpinning operations
  • [#4607] Restrict available fields to map (in combobox) to only ones compatible with option
  • Add Help dialog for data defined mapping rST/HTML
  • Add dialog to create/add data defined fields in attribute table of memory layer or data source

Pin/Unpin Label and Highlight Pinned Labels tools

  • ✓ [83764a6, f7a3af3, f69d8d2] Add Pin/Unpin Label tool
    • Click or marquee on label to pin (set x/y, rotation data defined field values to that of label)
    • Shift-click or marquee on label to unpin (set x/y, rotation data defined field values to NULL)
    • Ctl(Cmd)-click or marquee to toggle between pinned/unpinned label states
    • Action affects all editable layers
  • Pinning operations need to respect any quadrant or x/y offsets
  • Optionally write Hali/Vali on pin (if mapped)
    • Pinning overwrites Hali/Vali to that of label's rotation point?
  • Fix error in Highlight Pinned Labels on-the-fly transform for layers dissimilar to project

Show/Hide Label tool

  • ✓ [3dd05e6] Add Show/Hide Label tool
    • Click or marquee on feature to show label (set 'show label' data defined field value to 1)
    • Shift-click or marquee on label to hide label (set 'show label' data defined field value to 1)
    • Action affects on active editable layer

Move Label tool

  • ✓ [4d9d16] Write to attribute table label's PAL solution-defined rotation on initial move, if rotation is data-defined with no previous data. (same as pinning operation)
  • ✓ [f7a3af3] Preserve calculated x, y offset for upside-down labels, when initially moved and data-defined fields have no previous data

Rotate Label tool

  • ✓ [4d9d16] Update to work with layer-level and data defined rotation, independent of x/y data defined (limited to PAL placement OverPoint)

Change Label tool

  • ✓ [2fbc98e] Add show label mapping
  • ✓ [2263435] Add scale-based visibility mappings
  • Update with new data defined settings
  • Add Apply feature
  • Add encompassing Show groupbox
  • Add QgsCollapsibleGroupBoxes
  • Use edit widget defined in layer properties (suggested by Regis Haubourg)
    • Especially be able to use a text widget with carriage return input made possible
  • [#6732] Correct msising warning when closing project if labels have been moved, but not saved.

Roadmap to a styles- and rule-based setup

See also: RuleBasedLabelingIdeas

See description at end of mailing list post