addPlaceholder method Null safety

void addPlaceholder(
  1. double width,
  2. double height,
  3. PlaceholderAlignment alignment,
  4. {double scale = 1.0,
  5. double? baselineOffset,
  6. TextBaseline? baseline}
)

Adds an inline placeholder space to the paragraph.

The paragraph will contain a rectangular space with no text of the dimensions specified.

The width and height parameters specify the size of the placeholder rectangle.

The alignment parameter specifies how the placeholder rectangle will be vertically aligned with the surrounding text. When PlaceholderAlignment.baseline, PlaceholderAlignment.aboveBaseline, and PlaceholderAlignment.belowBaseline alignment modes are used, the baseline needs to be set with the baseline. When using PlaceholderAlignment.baseline, baselineOffset indicates the distance of the baseline down from the top of the rectangle. The default baselineOffset is the height.

Examples:

  • For a 30x50 placeholder with the bottom edge aligned with the bottom of the text, use: addPlaceholder(30, 50, PlaceholderAlignment.bottom);
  • For a 30x50 placeholder that is vertically centered around the text, use: addPlaceholder(30, 50, PlaceholderAlignment.middle);.
  • For a 30x50 placeholder that sits completely on top of the alphabetic baseline, use: addPlaceholder(30, 50, PlaceholderAlignment.aboveBaseline, baseline: TextBaseline.alphabetic).
  • For a 30x50 placeholder with 40 pixels above and 10 pixels below the alphabetic baseline, use: addPlaceholder(30, 50, PlaceholderAlignment.baseline, baseline: TextBaseline.alphabetic, baselineOffset: 40).

Lines are permitted to break around each placeholder.

Decorations will be drawn based on the font defined in the most recently pushed TextStyle. The decorations are drawn as if unicode text were present in the placeholder space, and will draw the same regardless of the height and alignment of the placeholder. To hide or manually adjust decorations to fit, a text style with the desired decoration behavior should be pushed before adding a placeholder.

Any decorations drawn through a placeholder will exist on the same canvas/layer as the text. This means any content drawn on top of the space reserved by the placeholder will be drawn over the decoration, possibly obscuring the decoration.

Placeholders are represented by a unicode 0xFFFC "object replacement character" in the text buffer. For each placeholder, one object replacement character is added on to the text buffer.

The scale parameter will scale the width and height by the specified amount, and keep track of the scale. The scales of placeholders added can be accessed through placeholderScales. This is primarily used for accessibility scaling.

Implementation

void addPlaceholder(double width, double height, PlaceholderAlignment alignment, {
  double scale = 1.0,
  double? baselineOffset,
  TextBaseline? baseline,
}) {
  // Require a baseline to be specified if using a baseline-based alignment.
  assert(!(alignment == PlaceholderAlignment.aboveBaseline ||
          alignment == PlaceholderAlignment.belowBaseline ||
          alignment == PlaceholderAlignment.baseline) || baseline != null);
  // Default the baselineOffset to height if null. This will place the placeholder
  // fully above the baseline, similar to [PlaceholderAlignment.aboveBaseline].
  baselineOffset = baselineOffset ?? height;
  _addPlaceholder(width * scale, height * scale, alignment.index, baselineOffset * scale, (baseline ?? TextBaseline.alphabetic).index);
  _placeholderCount++;
  _placeholderScales.add(scale);
}