Scale

What you’ll learn#

• Scale images programmatically using Swift
• Scale proportionally or non-uniformly
• Scale grouped elements
• Apply scale constraints in templates

When to use#

Use scaling to:

• Emphasize or de-emphasize elements
• Fit images to available space without cropping
• Enable pinch-to-zoom gestures or dynamic layouts

Scale an image uniformly#

Scaling uses the scale(_ id: DesignBlockID, to scale: Float) function. A scale value of 1.0 is the original scale. Values larger than 1.0 increase the scale of the block and values lower than 1.0 scale the block smaller. A value of 2.0, for example makes the block twice as large.

This scales the image to 150% of its original size. The origin anchor point is unchanged, so the image expands down and to the right.

try engine.block.scale(imageBlock, to: 1.5)

By default, the anchor point for the image when scaling is the origin point on the top left. The scale function has two optional parameters to move the anchor point in the x and y direction. They can have values between 0.0 and 1.0

This scales the image to 150% of its original size. The origin anchor point is 0.5, 0.5 so the image expands from the center.

try engine.block.scale(block, to: 1.5, anchorX: 0.5, anchorY: 0.5)

Scale non-uniformly#

To stretch or compress only one axis, thus distoring an image, use the crop scale function in combination with the width or height function. How you decide to make the adjustment will have different results. Below are three examples of scaling the original image in the x direction only.

try engine.block.setWidthMode(imageBlock, mode: .absolute)
let newWidth: Float = try engine.block.getWidth(imageBlock) * 1.5
try engine.block.setWidth(imageBlock, value: newWidth)

This adjusts the width of the block and allows the engine to adjust the scale of the image to maintain it as a fill.

try engine.block.setCropScaleX(imageBlock, scaleX:  1.50)
try engine.block.setWidthMode(block, mode: .absolute)
let newWidth: Float = try engine.block.getWidth(block) * 1.5
try engine.block.setWidth(block, value: newWidth)

This uses crop scale to scale the image in a single direction and then adjusts the block’s width to match the change. The change in width does not take the crop into account and so distorts the image as it’s scaling the scaled image.

try engine.block.setCropScaleX(imageBlock, scaleX:  1.50)
try engine.block.setWidthMode(block, mode: .absolute)
let newWidth: Float = try engine.block.getWidth(block) * 1.5
try engine.block.setWidth(block, value: newWidth, maintainCrop: true)

By setting the maintainCrop option to true, expanding the width of the image by the scale factor respects the crop scale and the image is less distorted.

Scale multiple elements together#

Group blocks to scale them proportionally:

let groupId = try engine.block.group([imageBlock, textBlock])
try engine.block.scale(groupId, to: 0.75)

This scales the entire group to 75%.

Lock scaling#

When working with templates, you can lock a block from scaling by setting its scope. Remember that the global layer has to defer to the blocks using setGlobalScope.

try engine.block.setScopeEnabled(imageBlock, key: "layer/resize", enabled: false)

To prevent users from transforming an element at all:

try engine.block.setTransformLocked(imageBlock, locked: true)