Attribute Macro elem

#[elem]

Makes a native Rust type usable as a Typst element.

This implements NativeElement for the given type.

/// A section heading.
#[elem(Show, Count)]
struct HeadingElem {
    /// The logical nesting depth of the heading, starting from one.
    #[default(NonZeroUsize::ONE)]
    level: NonZeroUsize,

    /// The heading's title.
    #[required]
    body: Content,
}

Properties

You can customize some properties of the resulting type:

• scope: Indicates that the type has an associated scope defined by the #[scope] macro.
• name = "<name>": The element’s normal name (e.g. align), as exposed to Typst. Defaults to the Rust name in kebab-case.
• title = "<title>": The type’s title case name (e.g. Align). Defaults to the long name in title case.
• keywords = [..]: A list of alternate search terms for this element. Defaults to the empty list.
• The remaining entries in the elem macros list are traits the element is capable of. These can be dynamically accessed.

Fields

By default, element fields are named and optional (and thus settable). You can use various attributes to configure their parsing behaviour:

• #[positional]: Makes the argument positional (but still optional).
• #[required]: Makes the argument positional and required.
• #[default(..)]: Specifies the default value of the argument as ...
• #[variadic]: Parses a variable number of arguments. The field type must be Vec<_>. The field will be exposed as an array.
• #[parse({ .. })]: A block of code that parses the field manually.

In addition that there are a number of attributes that configure other aspects of the field than the parsing behaviour.

• #[resolve]: When accessing the field, it will be automatically resolved through the Resolve trait. This, for instance, turns Length into Abs. It’s just convenient.
• #[fold]: When there are multiple set rules for the field, all values are folded together into one. E.g. set rect(stroke: 2pt) and set rect(stroke: red) are combined into the equivalent of set rect(stroke: 2pt + red) instead of having red override 2pt.
• #[borrowed]: For fields that are accessed through the style chain, indicates that accessor methods to this field should return references to the value instead of cloning.
• #[internal]: The field does not appear in the documentation.
• #[external]: The field appears in the documentation, but is otherwise ignored. Can be useful if you want to do something manually for more flexibility.
• #[synthesized]: The field cannot be specified in a constructor or set rule. Instead, it is added to an element before its show rule runs through the Synthesize trait.
• #[ghost]: Allows creating fields that are only present in the style chain, this means that they cannot be accessed by the user, they cannot be set on an individual instantiated element, and must be set via the style chain. This is useful for fields that are only used internally by the style chain, such as the fields from ParElem and TextElem. If your element contains any ghost fields, then you cannot auto-generate Construct for it, and you must implement Construct manually.