Struct BlockElem

pub struct BlockElem { /* private fields */ }

A block-level container.

Such a container can be used to separate content, size it, and give it a background or border.

Blocks are also the primary way to control whether text becomes part of a paragraph or not. See the paragraph documentation for more details.

Examples

With a block, you can give a background to content while still allowing it to break across multiple pages.

#set page(height: 100pt)
#block(
  fill: luma(230),
  inset: 8pt,
  radius: 4pt,
  lorem(30),
)

Blocks are also useful to force elements that would otherwise be inline to become block-level, especially when writing show rules.

#show heading: it => it.body
= Blockless
More text.

#show heading: it => block(it.body)
= Blocky
More text.

Implementations

impl BlockElem

pub fn new() -> Self

Create a new instance of the element.

pub fn with_width(self, width: Smart<Rel<Length>>) -> Self

Builder-style setter for the width field.

pub fn with_height(self, height: Sizing) -> Self

Builder-style setter for the height field.

pub fn with_breakable(self, breakable: bool) -> Self

Builder-style setter for the breakable field.

pub fn with_fill(self, fill: Option<Paint>) -> Self

Builder-style setter for the fill field.

pub fn with_stroke(self, stroke: Sides<Option<Option<Stroke>>>) -> Self

Builder-style setter for the stroke field.

pub fn with_radius(self, radius: Corners<Option<Rel<Length>>>) -> Self

Builder-style setter for the radius field.

pub fn with_inset(self, inset: Sides<Option<Rel<Length>>>) -> Self

Builder-style setter for the inset field.

pub fn with_outset(self, outset: Sides<Option<Rel<Length>>>) -> Self

Builder-style setter for the outset field.

pub fn with_above(self, above: Smart<Spacing>) -> Self

Builder-style setter for the above field.

pub fn with_below(self, below: Smart<Spacing>) -> Self

Builder-style setter for the below field.

pub fn with_clip(self, clip: bool) -> Self

Builder-style setter for the clip field.

pub fn with_sticky(self, sticky: bool) -> Self

Builder-style setter for the sticky field.

pub fn with_body(self, body: Option<BlockBody>) -> Self

Builder-style setter for the body field.

pub fn push_width(&mut self, width: Smart<Rel<Length>>)

Setter for the width field.

pub fn push_height(&mut self, height: Sizing)

Setter for the height field.

pub fn push_breakable(&mut self, breakable: bool)

Setter for the breakable field.

pub fn push_fill(&mut self, fill: Option<Paint>)

Setter for the fill field.

pub fn push_stroke(&mut self, stroke: Sides<Option<Option<Stroke>>>)

Setter for the stroke field.

pub fn push_radius(&mut self, radius: Corners<Option<Rel<Length>>>)

Setter for the radius field.

pub fn push_inset(&mut self, inset: Sides<Option<Rel<Length>>>)

Setter for the inset field.

pub fn push_outset(&mut self, outset: Sides<Option<Rel<Length>>>)

Setter for the outset field.

pub fn push_above(&mut self, above: Smart<Spacing>)

Setter for the above field.

pub fn push_below(&mut self, below: Smart<Spacing>)

Setter for the below field.

pub fn push_clip(&mut self, clip: bool)

Setter for the clip field.

pub fn push_sticky(&mut self, sticky: bool)

Setter for the sticky field.

pub fn push_body(&mut self, body: Option<BlockBody>)

Setter for the body field.

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

The block’s width.

#set align(center)
#block(
  width: 60%,
  inset: 8pt,
  fill: silver,
  lorem(10),
)

pub fn height(&self, styles: StyleChain<'_>) -> Sizing

The block’s height. When the height is larger than the remaining space on a page and breakable is {true}, the block will continue on the next page with the remaining height.

#set page(height: 80pt)
#set align(center)
#block(
  width: 80%,
  height: 150%,
  fill: aqua,
)

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

Whether the block can be broken and continue on the next page.

#set page(height: 80pt)
The following block will
jump to its own page.
#block(
  breakable: false,
  lorem(15),
)

pub fn fill(&self, styles: StyleChain<'_>) -> Option<Paint>

The block’s background color. See the rectangle’s documentation for more details.

pub fn stroke( &self, styles: StyleChain<'_>, ) -> <Sides<Option<Option<Stroke>>> as Resolve>::Output

The block’s border color. See the rectangle’s documentation for more details.

pub fn radius( &self, styles: StyleChain<'_>, ) -> <Corners<Option<Rel<Length>>> as Resolve>::Output

How much to round the block’s corners. See the rectangle’s documentation for more details.

pub fn inset( &self, styles: StyleChain<'_>, ) -> <Sides<Option<Rel<Length>>> as Resolve>::Output

How much to pad the block’s content. See the box’s documentation for more details.

pub fn outset( &self, styles: StyleChain<'_>, ) -> <Sides<Option<Rel<Length>>> as Resolve>::Output

How much to expand the block’s size without affecting the layout. See the box’s documentation for more details.

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

The spacing between this block and its predecessor.

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

The spacing between this block and its successor.

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

Whether to clip the content inside the block.

Clipping is useful when the block’s content is larger than the block itself, as any content that exceeds the block’s bounds will be hidden.

#block(
  width: 50pt,
  height: 50pt,
  clip: true,
  image("tiger.jpg", width: 100pt, height: 100pt)
)

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

Whether this block must stick to the following one, with no break in between.

This is, by default, set on heading blocks to prevent orphaned headings at the bottom of the page.

>>> #set page(height: 140pt)
// Disable stickiness of headings.
#show heading: set block(sticky: false)
#lorem(20)

= Chapter
#lorem(10)

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

The contents of the block.

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

Access the width field in the given style chain.

pub fn height_in(styles: StyleChain<'_>) -> Sizing

Access the height field in the given style chain.

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

Access the breakable field in the given style chain.

pub fn fill_in(styles: StyleChain<'_>) -> Option<Paint>

Access the fill field in the given style chain.

pub fn stroke_in( styles: StyleChain<'_>, ) -> <Sides<Option<Option<Stroke>>> as Resolve>::Output

Access the stroke field in the given style chain.

pub fn radius_in( styles: StyleChain<'_>, ) -> <Corners<Option<Rel<Length>>> as Resolve>::Output

Access the radius field in the given style chain.

pub fn inset_in( styles: StyleChain<'_>, ) -> <Sides<Option<Rel<Length>>> as Resolve>::Output

Access the inset field in the given style chain.

pub fn outset_in( styles: StyleChain<'_>, ) -> <Sides<Option<Rel<Length>>> as Resolve>::Output

Access the outset field in the given style chain.

pub fn above_in(styles: StyleChain<'_>) -> Smart<Spacing>

Access the above field in the given style chain.

pub fn below_in(styles: StyleChain<'_>) -> Smart<Spacing>

Access the below field in the given style chain.

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

Access the clip field in the given style chain.

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

Access the sticky field in the given style chain.

pub fn body_in(styles: StyleChain<'_>) -> &Option<BlockBody>

Access the body field in the given style chain.

pub fn set_width(width: Smart<Rel<Length>>) -> Property

Create a style property for the width field.

pub fn set_height(height: Sizing) -> Property

Create a style property for the height field.

pub fn set_breakable(breakable: bool) -> Property

Create a style property for the breakable field.

pub fn set_fill(fill: Option<Paint>) -> Property

Create a style property for the fill field.

pub fn set_stroke(stroke: Sides<Option<Option<Stroke>>>) -> Property

Create a style property for the stroke field.

pub fn set_radius(radius: Corners<Option<Rel<Length>>>) -> Property

Create a style property for the radius field.

pub fn set_inset(inset: Sides<Option<Rel<Length>>>) -> Property

Create a style property for the inset field.

pub fn set_outset(outset: Sides<Option<Rel<Length>>>) -> Property

Create a style property for the outset field.

pub fn set_above(above: Smart<Spacing>) -> Property

Create a style property for the above field.

pub fn set_below(below: Smart<Spacing>) -> Property

Create a style property for the below field.

pub fn set_clip(clip: bool) -> Property

Create a style property for the clip field.

pub fn set_sticky(sticky: bool) -> Property

Create a style property for the sticky field.

pub fn set_body(body: Option<BlockBody>) -> Property

Create a style property for the body field.

impl BlockElem

pub fn single_layouter<T: NativeElement>( captured: Packed<T>, f: fn(content: &Packed<T>, engine: &mut Engine<'_>, locator: Locator<'_>, styles: StyleChain<'_>, region: Region) -> SourceResult<Frame>, ) -> Self

Create a block with a custom single-region layouter.

Such a block must have breakable: false (which is set by this constructor).

pub fn multi_layouter<T: NativeElement>( captured: Packed<T>, f: fn(content: &Packed<T>, engine: &mut Engine<'_>, locator: Locator<'_>, styles: StyleChain<'_>, regions: Regions<'_>) -> SourceResult<Fragment>, ) -> Self

Create a block with a custom multi-region layouter.

Trait Implementations

impl Capable for BlockElem

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

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

impl Clone for BlockElem

fn clone(&self) -> BlockElem

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Construct for BlockElem

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

Construct an element from the arguments.

impl Debug for BlockElem

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

Formats the value using the given formatter.

impl Fields for BlockElem

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 BlockElem

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 BlockElem

fn into_value(self) -> Value

Cast this type into a value.

impl NativeElement for BlockElem

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 PartialEq for BlockElem

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 BlockElem

fn repr(&self) -> EcoString

Return the debug representation of the value.

impl Set for BlockElem

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

Parse relevant arguments into style properties for this element.