Using Strokes

import IMGLYEngine

@MainActor
func stroke(engine: Engine) async throws {
  // Demo scaffolding: a scene with a page and a single rectangle graphic block
  // to outline. A light fill keeps the rectangle visible so the blue stroke
  // stands out against it.
  let scene = try engine.scene.create()
  let page = try engine.block.create(.page)
  try engine.block.setWidth(page, value: 800)
  try engine.block.setHeight(page, value: 600)
  try engine.block.appendChild(to: scene, child: page)

  let block = try engine.block.create(.graphic)
  try engine.block.setShape(block, shape: engine.block.createShape(.rect))
  try engine.block.setFill(block, fill: engine.block.createFill(.color))
  let fill = try engine.block.getFill(block)
  try engine.block.setColor(fill, property: "fill/color/value", color: .rgba(r: 0.9, g: 0.9, b: 0.9, a: 1.0))
  try engine.block.setWidth(block, value: 400)
  try engine.block.setHeight(block, value: 300)
  try engine.block.setPositionX(block, value: 200)
  try engine.block.setPositionY(block, value: 150)
  try engine.block.appendChild(to: page, child: block)

  guard try engine.block.supportsStroke(block) else { return }

  try engine.block.setStrokeEnabled(block, enabled: true)
  let strokeEnabled = try engine.block.isStrokeEnabled(block)
  print("Stroke enabled: \(strokeEnabled)")

  try engine.block.setStrokeColor(block, color: .rgba(r: 0.0, g: 0.0, b: 1.0, a: 1.0))
  let strokeColor: Color = try engine.block.getStrokeColor(block)
  print("Stroke color: \(strokeColor)")

  try engine.block.setStrokeWidth(block, width: 10)
  let strokeWidth = try engine.block.getStrokeWidth(block)
  print("Stroke width: \(strokeWidth)")

  try await engine.captureGuide(page, label: "after-basic-stroke")

  try engine.block.setStrokeStyle(block, style: .dashed)
  let strokeStyle = try engine.block.getStrokeStyle(block)
  print("Stroke style is dashed: \(strokeStyle == .dashed)")

  try engine.block.setStrokePosition(block, position: .outer)
  let strokePosition = try engine.block.getStrokePosition(block)
  print("Stroke position is outer: \(strokePosition == .outer)")

  try engine.block.setStrokeCornerGeometry(block, cornerGeometry: .round)
  let strokeCornerGeometry = try engine.block.getStrokeCornerGeometry(block)
  print("Stroke corner geometry is round: \(strokeCornerGeometry == .round)")

  try await engine.captureGuide(page, label: "hero")
}

Strokes are visual outlines on design blocks. This guide focuses on controlling stroke color, width, line pattern, position relative to the block edge, and corner geometry through the block API. Mutating stroke properties requires the stroke/change scope. Additional overprint, end-cap, and custom-dash APIs are listed in the API Reference.

The snippets use a rectangle graphic block named block, but the same calls apply to any block once supportsStroke() returns true.

Using the Built-in Stroke UI#

On iOS, the editor shows stroke controls in the Fill & Stroke sheet for selected blocks that support strokes and allow the stroke/change scope. That sheet can render fill controls, stroke controls, or both, depending on the selected block. The color row doubles as the on/off control: choosing no color disables the stroke, while choosing a swatch or custom color enables and colors it.

• No-color and color swatches - Disable the stroke or apply a preset RGBA stroke color
• Color picker - Choose a custom stroke color
• Width slider - Adjust stroke thickness in design units
• Style picker - Select solid, dashed, rounded-dashed, dotted, long-dashed, or long round-ended dashed patterns
• Position and corner pickers - Adjust stroke placement and corner joins when available for the selected block

Checking Stroke Support#

Before applying stroke settings, check whether the block supports them. Return before the mutation calls when supportsStroke() is false.

guard try engine.block.supportsStroke(block) else { return }

Enabling Strokes#

Enable the stroke with setStrokeEnabled(), then read the state back with isStrokeEnabled() when your app needs to update its UI or validate the change.

try engine.block.setStrokeEnabled(block, enabled: true)
let strokeEnabled = try engine.block.isStrokeEnabled(block)
print("Stroke enabled: \(strokeEnabled)")

Setting Stroke Color#

Use setStrokeColor() with a Color value. The .rgba case takes red, green, blue, and alpha components from 0.0 to 1.0. The sample sets a blue stroke and reads it back with getStrokeColor().

try engine.block.setStrokeColor(block, color: .rgba(r: 0.0, g: 0.0, b: 1.0, a: 1.0))
let strokeColor: Color = try engine.block.getStrokeColor(block)
print("Stroke color: \(strokeColor)")

Swift’s overload resolution can’t pick between the deprecated RGBA-returning overload and the canonical Color one without help, so annotate the binding (let strokeColor: Color = ...).

Setting Stroke Width#

Set the thickness in design units with setStrokeWidth(). Larger values create more prominent outlines, and getStrokeWidth() returns the current value.

try engine.block.setStrokeWidth(block, width: 10)
let strokeWidth = try engine.block.getStrokeWidth(block)
print("Stroke width: \(strokeWidth)")

Stroke Styles#

Use setStrokeStyle() to control the line pattern. The StrokeStyle enum provides:

• .solid - Continuous line
• .dashed - Square-ended dashes with gaps
• .dashedRound - Round-ended dashes with gaps
• .dotted - Circular dots
• .longDashed - Longer square-ended dashes
• .longDashedRound - Longer round-ended dashes

try engine.block.setStrokeStyle(block, style: .dashed)
let strokeStyle = try engine.block.getStrokeStyle(block)
print("Stroke style is dashed: \(strokeStyle == .dashed)")

Stroke Position#

Use setStrokePosition() to control where the stroke renders relative to the block edge:

• .center - Centered on the edge (default)
• .inner - Rendered inside the block boundary
• .outer - Rendered outside the block boundary

Inner strokes stay within the block bounds, while outer strokes extend beyond them.

try engine.block.setStrokePosition(block, position: .outer)
let strokePosition = try engine.block.getStrokePosition(block)
print("Stroke position is outer: \(strokePosition == .outer)")

Stroke Corner Geometry#

Use setStrokeCornerGeometry() to control how stroke corners are joined. The effect is easiest to see on rectangular shapes.

• .miter - Sharp pointed corners (default)
• .round - Smoothly curved corners
• .bevel - Flat cut corners

try engine.block.setStrokeCornerGeometry(block, cornerGeometry: .round)
let strokeCornerGeometry = try engine.block.getStrokeCornerGeometry(block)
print("Stroke corner geometry is round: \(strokeCornerGeometry == .round)")

Troubleshooting#

If strokes do not appear as expected, check these common issues:

• Stroke not visible - Verify isStrokeEnabled() returns true and the width is greater than 0.
• Stroke color appears wrong - Use normalized color components from 0.0 to 1.0, not 0 to 255.
• Stroke affects the visual bounds - Use .inner to keep the stroke inside the block boundary, or .outer when the outline should extend beyond it.
• Block does not support strokes - Guard mutations with supportsStroke() before applying stroke properties.

API Reference#

Related Types#

Next Steps#

• Apply Colors — Apply colors to design elements programmatically
• Fills — Add solid colors, gradients, images, or videos inside blocks
• Shadows and Glows — Add depth with shadow and glow effects
• Create and Edit Shapes — Create shape blocks you can style with strokes