Struct CATextLayerBuilder 

pub struct CATextLayerBuilder { /* private fields */ }

Builder for CATextLayer.

CATextLayer renders text using Core Text. This builder provides an ergonomic API for configuring text layers with fonts, colors, alignment, and animations.

Basic Usage

let text = CATextLayerBuilder::new()
    .text("Hello, World!")
    .font_size(24.0)
    .foreground_color(Color::WHITE)
    .alignment(TextAlign::Center)
    .build();

With Font Name

let text = CATextLayerBuilder::new()
    .text("Monospaced")
    .font_name("Menlo")
    .font_size(16.0)
    .foreground_color(Color::CYAN)
    .build();

With CTFont

For more control over font attributes, you can provide a CTFont directly:

let font = unsafe {
    CTFont::with_name(&CFString::from_static_str("Helvetica-Bold"), 18.0, std::ptr::null())
};

let text = CATextLayerBuilder::new()
    .text("Bold Text")
    .font(font)
    .foreground_color(Color::ORANGE)
    .build();

With Animations

Animations can be added inline using the .animate() method:

let text = CATextLayerBuilder::new()
    .text("Pulsing Text")
    .font_size(32.0)
    .foreground_color(Color::RED)
    .animate("pulse", KeyPath::TransformScale, |a| {
        a.values(0.9, 1.1)
            .duration(500.millis())
            .autoreverses()
            .repeat(Repeat::Forever)
    })
    .build();

Text Wrapping and Truncation

let text = CATextLayerBuilder::new()
    .text("This is a long text that will wrap to multiple lines")
    .bounds(CGRect::new(CGPoint::ZERO, CGSize::new(200.0, 100.0)))
    .wrapped(true)
    .truncation(Truncation::End)
    .build();

Implementations

impl CATextLayerBuilder

pub fn new() -> Self

Creates a new builder with default values.

pub fn text(self, text: impl Into<String>) -> Self

Sets the text content to display.

Arguments

• text - The string to render

Examples

CATextLayerBuilder::new()
    .text("Hello, World!")
    .build();

pub fn font(self, font: CFRetained<CTFont>) -> Self

Sets the font using a CTFont object.

This gives you full control over the font, including traits like bold, italic, etc.

Arguments

• font - A Core Text font object

Examples

let font = unsafe {
    CTFont::with_name(
        &CFString::from_static_str("Helvetica-Bold"),
        18.0,
        std::ptr::null()
    )
};

CATextLayerBuilder::new()
    .text("Bold Text")
    .font(font)
    .build();

Notes

When .font() is set, it takes precedence over .font_name(). The font size from the CTFont will be used unless .font_size() is also called.

pub fn font_name(self, name: impl Into<String>) -> Self

Sets the font by name (PostScript name preferred).

Common font names include:

• “Helvetica”, “Helvetica-Bold”, “Helvetica-Oblique”
• “Menlo”, “Menlo-Bold” (monospaced)
• “SF Pro”, “SF Pro Display” (system fonts on modern macOS)
• “Times New Roman”

Arguments

• name - The font name (PostScript name preferred)

Examples

CATextLayerBuilder::new()
    .text("Monospaced")
    .font_name("Menlo")
    .font_size(14.0)
    .build();

Notes

If .font() is also set, it takes precedence over .font_name(). Use .font_size() to set the size when using .font_name().

pub fn font_size(self, size: CGFloat) -> Self

Sets the font size in points.

Arguments

• size - Font size in points (e.g., 12.0, 16.0, 24.0)

Examples

CATextLayerBuilder::new()
    .text("Large Text")
    .font_size(48.0)
    .build();

Notes

If .font() is set, the font size from the CTFont is used unless .font_size() is explicitly called to override it.

pub fn foreground_color(self, color: impl Into<CFRetained<CGColor>>) -> Self

Sets the text foreground color.

Accepts any type that implements Into<CFRetained<CGColor>>, including:

• Color::RED, Color::rgb(1.0, 0.0, 0.0)
• CFRetained<CGColor> directly

Examples

CATextLayerBuilder::new()
    .text("Red Text")
    .foreground_color(Color::RED)
    .build();

pub fn foreground_rgba( self, r: CGFloat, g: CGFloat, b: CGFloat, a: CGFloat, ) -> Self

Sets the text foreground color from RGBA values (0.0-1.0).

Examples

CATextLayerBuilder::new()
    .text("Orange Text")
    .foreground_rgba(1.0, 0.5, 0.0, 1.0)
    .build();

pub fn alignment(self, alignment: TextAlign) -> Self

Sets the text alignment.

Arguments

• alignment - The text alignment mode

Examples

CATextLayerBuilder::new()
    .text("Centered")
    .alignment(TextAlign::Center)
    .build();

pub fn truncation(self, truncation: Truncation) -> Self

Sets the truncation mode for text that doesn’t fit.

Arguments

• truncation - The truncation mode

Examples

CATextLayerBuilder::new()
    .text("This text is too long to fit...")
    .truncation(Truncation::End)
    .build();

pub fn wrapped(self, wrapped: bool) -> Self

Sets whether text should wrap to multiple lines.

When true, text wraps at word boundaries when it exceeds the layer width. When false (default), text remains on a single line.

Arguments

• wrapped - Whether to enable text wrapping

Examples

CATextLayerBuilder::new()
    .text("This is a long text that will wrap")
    .bounds(CGRect::new(CGPoint::ZERO, CGSize::new(100.0, 200.0)))
    .wrapped(true)
    .build();

pub fn bounds(self, bounds: CGRect) -> Self

Sets the bounds rectangle.

The bounds define the layer’s size and the coordinate space for sublayers. For text layers, bounds control the area where text is rendered.

Examples

CATextLayerBuilder::new()
    .text("Text in a box")
    .bounds(CGRect::new(CGPoint::ZERO, CGSize::new(200.0, 50.0)))
    .build();

pub fn size(self, width: CGFloat, height: CGFloat) -> Self

Sets the bounds from width and height (origin at ZERO).

Convenience method equivalent to:

.bounds(CGRect::new(CGPoint::ZERO, CGSize::new(width, height)))

Examples

CATextLayerBuilder::new()
    .text("Sized text area")
    .size(200.0, 50.0)
    .build();

pub fn position(self, position: CGPoint) -> Self

Sets the position in superlayer coordinates.

The position is where the layer’s anchor point is placed in the superlayer. By default, the anchor point is at the center of the layer (0.5, 0.5).

Examples

CATextLayerBuilder::new()
    .text("Positioned text")
    .position(CGPoint::new(100.0, 100.0))
    .build();

pub fn transform(self, transform: CATransform3D) -> Self

Sets the 3D transform.

Examples

let rotate = CATransform3D::new_rotation(0.1, 0.0, 0.0, 1.0);
CATextLayerBuilder::new()
    .text("Rotated")
    .transform(rotate)
    .build();

pub fn hidden(self, hidden: bool) -> Self

Sets whether the layer is hidden.

pub fn opacity(self, opacity: f32) -> Self

Sets the opacity (0.0-1.0).

pub fn shadow_color(self, color: impl Into<CFRetained<CGColor>>) -> Self

Sets the shadow color.

Examples

CATextLayerBuilder::new()
    .text("Shadowed")
    .shadow_color(Color::BLACK)
    .shadow_radius(5.0)
    .shadow_opacity(0.5)
    .build();

pub fn shadow_offset(self, dx: f64, dy: f64) -> Self

Sets the shadow offset (dx, dy).

Positive dx moves the shadow right, positive dy moves it down.

pub fn shadow_radius(self, radius: f64) -> Self

Sets the shadow blur radius.

Larger values create a softer, more diffuse shadow.

pub fn shadow_opacity(self, opacity: f32) -> Self

Sets the shadow opacity (0.0 to 1.0).

pub fn scale(self, scale: f64) -> Self

Sets a uniform scale transform.

Notes

When multiple transform shortcuts are set, they are composed in order: scale -> rotation -> translation.

If you also call .transform(), the explicit transform takes precedence and scale/rotation/translate are ignored.

pub fn rotation(self, radians: f64) -> Self

Sets a z-axis rotation transform (in radians).

For degrees, use: .rotation(45.0_f64.to_radians())

Notes

When multiple transform shortcuts are set, they are composed in order: scale -> rotation -> translation.

pub fn translate(self, dx: f64, dy: f64) -> Self

Sets a translation transform (dx, dy).

Notes

When multiple transform shortcuts are set, they are composed in order: scale -> rotation -> translation.

pub fn animate<F>( self, name: impl Into<String>, key_path: KeyPath, configure: F, ) -> Self

where F: FnOnce(CABasicAnimationBuilder) -> CABasicAnimationBuilder,

Adds an animation to be applied when the layer is built.

The animation is configured using a closure that receives a CABasicAnimationBuilder and returns the configured builder.

Arguments

• name - A unique identifier for this animation (used as the animation key)
• key_path - The property to animate (e.g., KeyPath::TransformScale)
• configure - A closure that configures the animation builder

Examples

// Pulsing text
CATextLayerBuilder::new()
    .text("Pulsing")
    .font_size(24.0)
    .foreground_color(Color::CYAN)
    .animate("pulse", KeyPath::TransformScale, |a| {
        a.values(0.9, 1.1)
            .duration(500.millis())
            .autoreverses()
            .repeat(Repeat::Forever)
    })
    .build();

// Fading text
CATextLayerBuilder::new()
    .text("Fading")
    .foreground_color(Color::WHITE)
    .animate("fade", KeyPath::Opacity, |a| {
        a.values(1.0, 0.3)
            .duration(1.seconds())
            .autoreverses()
            .repeat(Repeat::Forever)
    })
    .build();

pub fn build(self) -> Retained<CATextLayer>

Builds and returns the configured CATextLayer.

All pending animations added via .animate() are applied to the layer.

Trait Implementations

impl Default for CATextLayerBuilder

fn default() -> CATextLayerBuilder

Returns the “default value” for a type.