Struct PlaceElem

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

Places content relatively to its parent container.

Placed content can be either overlaid (the default) or floating. Overlaid content is aligned with the parent container according to the given alignment, and shown over any other content added so far in the container. Floating content is placed at the top or bottom of the container, displacing other content down or up respectively. In both cases, the content position can be adjusted with dx and dy offsets without affecting the layout.

The parent can be any container such as a [block], [box], [rect], etc. A top level place call will place content directly in the text area of the current page. This can be used for absolute positioning on the page: with a top + left alignment, the offsets dx and dy will set the position of the element’s top left corner relatively to the top left corner of the text area. For absolute positioning on the full page including margins, you can use place in page.foreground or page.background.

Examples

#set page(height: 120pt)
Hello, world!

#rect(
  width: 100%,
  height: 2cm,
  place(horizon + right, square()),
)

#place(
  top + left,
  dx: -5pt,
  square(size: 5pt, fill: red),
)

Effect on the position of other elements { #effect-on-other-elements }

Overlaid elements don’t take space in the flow of content, but a place call inserts an invisible block-level element in the flow. This can affect the layout by breaking the current paragraph. To avoid this, you can wrap the place call in a [box] when the call is made in the middle of a paragraph. The alignment and offsets will then be relative to this zero-size box. To make sure it doesn’t interfere with spacing, the box should be attached to a word using a word joiner.

For example, the following defines a function for attaching an annotation to the following word:

>>> #set page(height: 70pt)
#let annotate(..args) = {
  box(place(..args))
  sym.wj
  h(0pt, weak: true)
}

A placed #annotate(square(), dy: 2pt)
square in my text.

The zero-width weak spacing serves to discard spaces between the function call and the next word.

Fields

body: Content

Implementations

impl PlaceElem

pub fn new(body: Content) -> Self

Create a new instance of the element.

pub fn with_alignment(self, alignment: Smart<Alignment>) -> Self

Builder-style setter for the alignment field.

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

Builder-style setter for the scope field.

pub fn with_float(self, float: bool) -> Self

Builder-style setter for the float field.

pub fn with_clearance(self, clearance: Length) -> Self

Builder-style setter for the clearance field.

pub fn with_dx(self, dx: Rel<Length>) -> Self

Builder-style setter for the dx field.

pub fn with_dy(self, dy: Rel<Length>) -> Self

Builder-style setter for the dy field.

pub fn push_alignment(&mut self, alignment: Smart<Alignment>)

Setter for the alignment field.

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

Setter for the scope field.

pub fn push_float(&mut self, float: bool)

Setter for the float field.

pub fn push_clearance(&mut self, clearance: Length)

Setter for the clearance field.

pub fn push_dx(&mut self, dx: Rel<Length>)

Setter for the dx field.

pub fn push_dy(&mut self, dy: Rel<Length>)

Setter for the dy field.

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

Relative to which position in the parent container to place the content.

• If float is {false}, then this can be any alignment other than {auto}.
• If float is {true}, then this must be {auto}, {top}, or {bottom}.

When float is {false} and no vertical alignment is specified, the content is placed at the current position on the vertical axis.

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

Relative to which containing scope something is placed.

The parent scope is primarily used with figures and, for this reason, the figure function has a mirrored scope parameter. Nonetheless, it can also be more generally useful to break out of the columns. A typical example would be to create a single-column title section in a two-column document.

Note that parent-scoped placement is currently only supported if float is {true}. This may change in the future.

#set page(height: 150pt, columns: 2)
#place(
  top + center,
  scope: "parent",
  float: true,
  rect(width: 80%, fill: aqua),
)

#lorem(25)

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

Whether the placed element has floating layout.

Floating elements are positioned at the top or bottom of the parent container, displacing in-flow content. They are always placed in the in-flow order relative to each other, as well as before any content following a later [place.flush] element.

#set page(height: 150pt)
#let note(where, body) = place(
  center + where,
  float: true,
  clearance: 6pt,
  rect(body),
)

#lorem(10)
#note(bottom)[Bottom 1]
#note(bottom)[Bottom 2]
#lorem(40)
#note(top)[Top]
#lorem(10)

pub fn clearance(&self, styles: StyleChain<'_>) -> <Length as Resolve>::Output

The spacing between the placed element and other elements in a floating layout.

Has no effect if float is {false}.

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

The horizontal displacement of the placed content.

#set page(height: 100pt)
#for i in range(16) {
  let amount = i * 4pt
  place(center, dx: amount - 32pt, dy: amount)[A]
}

This does not affect the layout of in-flow content. In other words, the placed content is treated as if it were wrapped in a [move] element.

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

The vertical displacement of the placed content.

This does not affect the layout of in-flow content. In other words, the placed content is treated as if it were wrapped in a [move] element.

pub fn alignment_in(styles: StyleChain<'_>) -> Smart<Alignment>

Access the alignment field in the given style chain.

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

Access the scope field in the given style chain.

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

Access the float field in the given style chain.

pub fn clearance_in(styles: StyleChain<'_>) -> <Length as Resolve>::Output

Access the clearance field in the given style chain.

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

Access the dx field in the given style chain.

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

Access the dy field in the given style chain.

pub fn set_alignment(alignment: Smart<Alignment>) -> Property

Create a style property for the alignment field.

pub fn set_scope(scope: PlacementScope) -> Property

Create a style property for the scope field.

pub fn set_float(float: bool) -> Property

Create a style property for the float field.

pub fn set_clearance(clearance: Length) -> Property

Create a style property for the clearance field.

pub fn set_dx(dx: Rel<Length>) -> Property

Create a style property for the dx field.

pub fn set_dy(dy: Rel<Length>) -> Property

Create a style property for the dy field.

Trait Implementations

impl Capable for PlaceElem

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

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

impl Clone for PlaceElem

fn clone(&self) -> PlaceElem

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Construct for PlaceElem

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

Construct an element from the arguments.

impl Debug for PlaceElem

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

Formats the value using the given formatter.

impl Fields for PlaceElem

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 PlaceElem

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

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 PlaceElem

fn into_value(self) -> Value

Cast this type into a value.

impl NativeElement for PlaceElem

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 PlaceElem

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 PlaceElem

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

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

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 PlaceElem

fn repr(&self) -> EcoString

Return the debug representation of the value.

impl Set for PlaceElem

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

Parse relevant arguments into style properties for this element.