Struct FigureElem

pub struct FigureElem {
    pub body: Content,
    /* private fields */
}

A figure with an optional caption.

Automatically detects its kind to select the correct counting track. For example, figures containing images will be numbered separately from figures containing tables.

Examples

The example below shows a basic figure with an image:

@glacier shows a glacier. Glaciers
are complex systems.

#figure(
  image("glacier.jpg", width: 80%),
  caption: [A curious figure.],
) <glacier>

You can also insert tables into figures to give them a caption. The figure will detect this and automatically use a separate counter.

#figure(
  table(
    columns: 4,
    [t], [1], [2], [3],
    [y], [0.3s], [0.4s], [0.8s],
  ),
  caption: [Timing results],
)

This behaviour can be overridden by explicitly specifying the figure’s kind. All figures of the same kind share a common counter.

Figure behaviour

By default, figures are placed within the flow of content. To make them float to the top or bottom of the page, you can use the placement argument.

If your figure is too large and its contents are breakable across pages (e.g. if it contains a large table), then you can make the figure itself breakable across pages as well with this show rule:

#show figure: set block(breakable: true)

See the block documentation for more information about breakable and non-breakable blocks.

Caption customization

You can modify the appearance of the figure’s caption with its associated caption function. In the example below, we emphasize all captions:

#show figure.caption: emph

#figure(
  rect[Hello],
  caption: [I am emphasized!],
)

By using a where selector, we can scope such rules to specific kinds of figures. For example, to position the caption above tables, but keep it below for all other kinds of figures, we could write the following show-set rule:

#show figure.where(
  kind: table
): set figure.caption(position: top)

#figure(
  table(columns: 2)[A][B][C][D],
  caption: [I'm up here],
)

Fields

body: Content

Implementations

impl FigureElem

pub fn new(body: Content) -> FigureElem

Create a new instance of the element.

pub fn with_placement(self, placement: Option<Smart<VAlignment>>) -> FigureElem

Builder-style setter for the placement field.

pub fn with_scope(self, scope: PlacementScope) -> FigureElem

Builder-style setter for the scope field.

pub fn with_caption(self, caption: Option<Packed<FigureCaption>>) -> FigureElem

Builder-style setter for the caption field.

pub fn with_kind(self, kind: Smart<FigureKind>) -> FigureElem

Builder-style setter for the kind field.

pub fn with_supplement( self, supplement: Smart<Option<Supplement>>, ) -> FigureElem

Builder-style setter for the supplement field.

pub fn with_numbering(self, numbering: Option<Numbering>) -> FigureElem

Builder-style setter for the numbering field.

pub fn with_gap(self, gap: Length) -> FigureElem

Builder-style setter for the gap field.

pub fn with_outlined(self, outlined: bool) -> FigureElem

Builder-style setter for the outlined field.

pub fn with_counter(self, counter: Option<Counter>) -> FigureElem

Builder-style setter for the counter field.

pub fn push_placement(&mut self, placement: Option<Smart<VAlignment>>)

Setter for the placement field.

pub fn push_scope(&mut self, scope: PlacementScope)

Setter for the scope field.

pub fn push_caption(&mut self, caption: Option<Packed<FigureCaption>>)

Setter for the caption field.

pub fn push_kind(&mut self, kind: Smart<FigureKind>)

Setter for the kind field.

pub fn push_supplement(&mut self, supplement: Smart<Option<Supplement>>)

Setter for the supplement field.

pub fn push_numbering(&mut self, numbering: Option<Numbering>)

Setter for the numbering field.

pub fn push_gap(&mut self, gap: Length)

Setter for the gap field.

pub fn push_outlined(&mut self, outlined: bool)

Setter for the outlined field.

pub fn push_counter(&mut self, counter: Option<Counter>)

Setter for the counter field.

pub fn placement(&self, styles: StyleChain<'_>) -> Option<Smart<VAlignment>>

The figure’s placement on the page.

• {none}: The figure stays in-flow exactly where it was specified like other content.
• {auto}: The figure picks {top} or {bottom} depending on which is closer.
• {top}: The figure floats to the top of the page.
• {bottom}: The figure floats to the bottom of the page.

The gap between the main flow content and the floating figure is controlled by the clearance argument on the place function.

#set page(height: 200pt)

= Introduction
#figure(
  placement: bottom,
  caption: [A glacier],
  image("glacier.jpg", width: 60%),
)
#lorem(60)

pub fn scope(&self, styles: StyleChain<'_>) -> PlacementScope

Relative to which containing scope the figure is placed.

Set this to {"parent"} to create a full-width figure in a two-column document.

Has no effect if placement is {none}.

#set page(height: 250pt, columns: 2)

= Introduction
#figure(
  placement: bottom,
  scope: "parent",
  caption: [A glacier],
  image("glacier.jpg", width: 60%),
)
#lorem(60)

pub fn caption<'a>( &'a self, styles: StyleChain<'a>, ) -> &'a Option<Packed<FigureCaption>>

The figure’s caption.

pub fn kind(&self, styles: StyleChain<'_>) -> Smart<FigureKind>

The kind of figure this is.

All figures of the same kind share a common counter.

If set to {auto}, the figure will try to automatically determine its kind based on the type of its body. Automatically detected kinds are tables and code. In other cases, the inferred kind is that of an image.

Setting this to something other than {auto} will override the automatic detection. This can be useful if

• you wish to create a custom figure type that is not an image, a [table] or code,
• you want to force the figure to use a specific counter regardless of its content.

You can set the kind to be an element function or a string. If you set it to an element function other than {table}, {raw} or {image}, you will need to manually specify the figure’s supplement.

#figure(
  circle(radius: 10pt),
  caption: [A curious atom.],
  kind: "atom",
  supplement: [Atom],
)

pub fn supplement<'a>( &'a self, styles: StyleChain<'a>, ) -> &'a Smart<Option<Supplement>>

The figure’s supplement.

If set to {auto}, the figure will try to automatically determine the correct supplement based on the kind and the active text language. If you are using a custom figure type, you will need to manually specify the supplement.

If a function is specified, it is passed the first descendant of the specified kind (typically, the figure’s body) and should return content.

#figure(
  [The contents of my figure!],
  caption: [My custom figure],
  supplement: [Bar],
  kind: "foo",
)

pub fn numbering<'a>(&'a self, styles: StyleChain<'a>) -> &'a Option<Numbering>

How to number the figure. Accepts a numbering pattern or function.

pub fn gap(&self, styles: StyleChain<'_>) -> Length

The vertical gap between the body and caption.

pub fn outlined(&self, styles: StyleChain<'_>) -> bool

Whether the figure should appear in an [outline] of figures.

pub fn counter(&self) -> Option<&Option<Counter>>

Convenience field to get access to the counter for this figure.

The counter only depends on the kind:

• For (tables)[@table]: {counter(figure.where(kind: table))}
• For (images)[@image]: {counter(figure.where(kind: image))}
• For a custom kind: {counter(figure.where(kind: kind))}

These are the counters you’ll need to modify if you want to skip a number or reset the counter.

pub fn placement_in(styles: StyleChain<'_>) -> Option<Smart<VAlignment>>

Access the placement field in the given style chain.

pub fn scope_in(styles: StyleChain<'_>) -> PlacementScope

Access the scope field in the given style chain.

pub fn caption_in(styles: StyleChain<'_>) -> &Option<Packed<FigureCaption>>

Access the caption field in the given style chain.

pub fn kind_in(styles: StyleChain<'_>) -> Smart<FigureKind>

Access the kind field in the given style chain.

pub fn supplement_in(styles: StyleChain<'_>) -> &Smart<Option<Supplement>>

Access the supplement field in the given style chain.

pub fn numbering_in(styles: StyleChain<'_>) -> &Option<Numbering>

Access the numbering field in the given style chain.

pub fn gap_in(styles: StyleChain<'_>) -> Length

Access the gap field in the given style chain.

pub fn outlined_in(styles: StyleChain<'_>) -> bool

Access the outlined field in the given style chain.

pub fn set_placement(placement: Option<Smart<VAlignment>>) -> Property

Create a style property for the placement field.

pub fn set_scope(scope: PlacementScope) -> Property

Create a style property for the scope field.

pub fn set_caption(caption: Option<Packed<FigureCaption>>) -> Property

Create a style property for the caption field.

pub fn set_kind(kind: Smart<FigureKind>) -> Property

Create a style property for the kind field.

pub fn set_supplement(supplement: Smart<Option<Supplement>>) -> Property

Create a style property for the supplement field.

pub fn set_numbering(numbering: Option<Numbering>) -> Property

Create a style property for the numbering field.

pub fn set_gap(gap: Length) -> Property

Create a style property for the gap field.

pub fn set_outlined(outlined: bool) -> Property

Create a style property for the outlined field.

Trait Implementations

impl Capable for FigureElem

fn vtable(capability: TypeId) -> Option<NonNull<()>>

Get the pointer to the vtable for the given capability / trait.

impl Clone for FigureElem

fn clone(&self) -> FigureElem

Returns a duplicate of the value.

const fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Construct for FigureElem

fn construct( engine: &mut Engine<'_>, args: &mut Args, ) -> Result<Content, EcoVec<SourceDiagnostic>>

Construct an element from the arguments.

impl Debug for FigureElem

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Fields for FigureElem

type Enum = Fields

An enum with the fields of the element.

fn has(&self, id: u8) -> bool

Whether the element has the given field set.

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

Get the field with the given field ID.

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

Get the field with the given ID in the presence of styles.

fn field_from_styles( id: u8, styles: StyleChain<'_>, ) -> Result<Value, FieldAccessError>

Get the field with the given ID from the styles.

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

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

fn fields(&self) -> Dict

Get the fields of the element.

impl Hash for FigureElem

fn hash<__H>(&self, state: &mut __H)

where __H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl IntoValue for FigureElem

fn into_value(self) -> Value

Cast this type into a value.

impl NativeElement for FigureElem

fn data() -> &'static NativeElementData

Get the element data for the native Rust element.

fn elem() -> Element

where Self: Sized,

Get the element for the native Rust element.

fn pack(self) -> Content

where Self: Sized,

Pack the element into type-erased content.

impl NativeScope for FigureElem

fn constructor() -> Option<&'static NativeFuncData>

The constructor function for the type, if any.

fn scope() -> Scope

Get the associated scope for the type.

impl PartialEq for FigureElem

fn eq(&self, other: &FigureElem) -> bool

Tests for self and other values to be equal, and is used by ==.

const fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Repr for FigureElem

fn repr(&self) -> EcoString

Return the debug representation of the value.

impl Set for FigureElem

fn set( engine: &mut Engine<'_>, args: &mut Args, ) -> Result<Styles, EcoVec<SourceDiagnostic>>

Parse relevant arguments into style properties for this element.