Struct Content

pub struct Content { /* private fields */ }

Expand description

A piece of document content.

This type is at the heart of Typst. All markup you write and most functions you call produce content values. You can create a content value by enclosing markup in square brackets. This is also how you pass content to functions.

§Example

Type of *Hello!* is
#type([*Hello!*])

Content can be added with the + operator, joined together and multiplied with integers. Wherever content is expected, you can also pass a string or {none}.

§Representation

Content consists of elements with fields. When constructing an element with its element function, you provide these fields as arguments and when you have a content value, you can access its fields with field access syntax.

Some fields are required: These must be provided when constructing an element and as a consequence, they are always available through field access on content of that type. Required fields are marked as such in the documentation.

Most fields are optional: Like required fields, they can be passed to the element function to configure them for a single element. However, these can also be configured with set rules to apply them to all elements within a scope. Optional fields are only available with field access syntax when they were explicitly passed to the element function, not when they result from a set rule.

Each element has a default appearance. However, you can also completely customize its appearance with a show rule. The show rule is passed the element. It can access the element’s field and produce arbitrary content from it.

In the web app, you can hover over a content variable to see exactly which elements the content is composed of and what fields they have. Alternatively, you can inspect the output of the [repr] function.

Implementations§

§

impl Content

pub fn new<T>(elem: T) -> Content
where T: NativeElement,

Creates a new content from an element.

pub fn empty() -> Content

Creates a empty sequence content.

pub fn elem(&self) -> Element

Get the element of this content.

pub fn span(&self) -> Span

Get the span of the content.

pub fn spanned(self, span: Span) -> Content

Set the span of the content.

pub fn label(&self) -> Option<Label>

Get the label of the content.

pub fn labelled_at(&self) -> Span

Get the span where the label is attached.

pub fn labelled(self, label: Label, labelled_at: Span) -> Content

Set the label of the content.

pub fn set_label(&mut self, label: Label)

Set the label of the content.

pub fn located(self, loc: Location) -> Content

Assigns a location to the content.

This identifies the content and e.g. makes it linkable by .linked(Destination::Location(loc)).

Useful in combination with [Location::variant].

pub fn set_location(&mut self, location: Location)

Set the location of the content.

pub fn is_guarded(&self, index: RecipeIndex) -> bool

Check whether a show rule recipe is disabled.

pub fn guarded(self, index: RecipeIndex) -> Content

Disable a show rule recipe.

pub fn is_prepared(&self) -> bool

Whether this content has already been prepared.

pub fn mark_prepared(&mut self)

Mark this content as prepared.

pub fn get( &self, id: u8, styles: Option<StyleChain<'_>>, ) -> Result<Value, FieldAccessError>

Get a field by ID.

This is the preferred way to access fields. However, you can only use it if you have set the field IDs yourself or are using the field IDs generated by the #[elem] macro.

pub fn get_by_name(&self, name: &str) -> Result<Value, FieldAccessError>

Get a field by name.

If you have access to the field IDs of the element, use Self::get instead.

pub fn field(&self, id: u8) -> Result<Value, EcoString>

Get a field by ID, returning a missing field error if it does not exist.

This is the preferred way to access fields. However, you can only use it if you have set the field IDs yourself or are using the field IDs generated by the #[elem] macro.

pub fn field_by_name(&self, name: &str) -> Result<Value, EcoString>

Get a field by name, returning a missing field error if it does not exist.

If you have access to the field IDs of the element, use Self::field instead.

pub fn materialize(&mut self, styles: StyleChain<'_>)

Resolve all fields with the styles and save them in-place.

pub fn sequence(iter: impl IntoIterator<Item = Content>) -> Content

Create a new sequence element from multiples elements.

pub fn is<T>(&self) -> bool
where T: NativeElement,

Whether the contained element is of type T.

pub fn to_packed<T>(&self) -> Option<&Packed<T>>
where T: NativeElement,

Downcasts the element to a packed value.

pub fn to_packed_mut<T>(&mut self) -> Option<&mut Packed<T>>
where T: NativeElement,

Downcasts the element to a mutable packed value.

pub fn into_packed<T>(self) -> Result<Packed<T>, Content>
where T: NativeElement,

Downcasts the element into an owned packed value.

pub fn unpack<T>(self) -> Result<T, Content>
where T: NativeElement,

Extract the raw underlying element.

pub fn can<C>(&self) -> bool
where C: 'static + ?Sized,

Whether the contained element has the given capability.

pub fn with<C>(&self) -> Option<&C>
where C: 'static + ?Sized,

Cast to a trait object if the contained element has the given capability.

pub fn with_mut<C>(&mut self) -> Option<&mut C>
where C: 'static + ?Sized,

Cast to a mutable trait object if the contained element has the given capability.

pub fn is_empty(&self) -> bool

Whether the content is an empty sequence.

pub fn sequence_recursive_for_each<'a>( &'a self, f: &mut impl FnMut(&'a Content), )

Also auto expands sequence of sequences into flat sequence

pub fn styled_with_recipe( self, engine: &mut Engine<'_>, context: Tracked<'_, Context<'_>>, recipe: Recipe, ) -> Result<Content, EcoVec<SourceDiagnostic>>

Style this content with a recipe, eagerly applying it if possible.

pub fn repeat(&self, count: usize) -> Content

Repeat this content count times.

pub fn styled(self, style: impl Into<Style>) -> Content

Style this content with a style entry.

pub fn styled_with_map(self, styles: Styles) -> Content

Style this content with a full style map.

pub fn style_in_place(&mut self, styles: Styles)

Style this content with a full style map in-place.

pub fn query(&self, selector: Selector) -> Vec<Content>

Queries the content tree for all elements that match the given selector.

Elements produced in show rules will not be included in the results.

pub fn query_first(&self, selector: &Selector) -> Option<Content>

Queries the content tree for the first element that match the given selector.

Elements produced in show rules will not be included in the results.

pub fn plain_text(&self) -> EcoString

Extracts the plain text of this content.

§

impl Content

pub fn strong(self) -> Content

Strongly emphasize this content.

pub fn emph(self) -> Content

Emphasize this content.

pub fn underlined(self) -> Content

Underline this content.

pub fn linked(self, dest: Destination) -> Content

Link the content somewhere.

pub fn aligned(self, align: Alignment) -> Content

Set alignments for this content.

pub fn padded(self, padding: Sides<Rel>) -> Content

Pad this content at the sides.

pub fn moved(self, delta: Axes<Rel>) -> Content

Transform this content’s contents without affecting layout.

§

impl Content

pub fn func(&self) -> Element

The content’s element function. This function can be used to create the element contained in this content. It can be used in set and show rules for the element. Can be compared with global functions to check whether you have a specific kind of element.

pub fn has(&self, field: Str) -> bool

Whether the content has the specified field.

pub fn at(&self, field: Str, default: Option<Value>) -> Result<Value, EcoString>

Access the specified field on the content. Returns the default value if the field does not exist or fails with an error if no default value was specified.

pub fn fields(&self) -> Dict

Returns the fields of this content.

#rect(
  width: 10cm,
  height: 10cm,
).fields()

pub fn location(&self) -> Option<Location>

The location of the content. This is only available on content returned by [query] or provided by a show rule, for other content it will be {none}. The resulting location can be used with counters, [state] and queries.