Struct Session 

pub struct Session<'a> { /* private fields */ }

A retained pipeline: content, styling, and every stage between them and the page.

let mut session = Session::new(&registry);
session.set_content(Book::default());
session.set_style(Stylesheets::parse(&[]));
let pages = &session.preview().pages;

A computed style can only resolve to a face already in the registry. A session over a borrowed registry leaves it as the host made it, so a sheet that brings its own @font-face needs the host to load that face before the sheet is set. A session that owns its registry registers the faces the sheet declares from the files add_font_file hands over.

Implementations

impl Session<'_>

pub fn set_content(&mut self, book: Book)

Sets the book, and with it every stage below box construction.

Node identity is the engine’s: the tree is renumbered on the way in, so a host may hand over sections it built by hand.

pub fn replace_source(&mut self, name: &str, sections: Vec<Section>)

Replaces every section that came from one source file.

The source is the replaceable unit because a host names files and one file may split into several sections. A name the book does not already have appends instead, which is how a file it has not seen before arrives.

pub fn set_source_attributes(&mut self, name: &str, attributes: &Attributes)

Names every section that came from one source by these classes and this id, and styles the book again.

The names sit beside the source rather than in it, so every node keeps the bytes it was read from. A name the book does not carry changes nothing.

pub fn set_source_warnings(&mut self, warnings: Vec<Warning>)

Adds a frontend’s complaints to the run’s diagnostics.

A construct the content vocabulary cannot express is reported where the source was read, which is upstream of every stage a session runs. The output’s warnings are the whole run’s, so they belong in the same channel rather than in a second one the host has to remember to read. Which of them still apply after an edit is the caller’s to decide; this replaces the lot.

pub fn set_style(&mut self, sheets: Stylesheets)

Sets the styling, and with it whichever stage the change reaches, which is usually far short of everything.

pub fn set_metadata(&mut self, metadata: Metadata)

Names the book: title, author, and whatever else a frontend read.

The declared language is the one field a stage below reads, and a book that changes it is hyphenated again. The pages already laid out are otherwise the pages the export writes under the new name.

pub fn add_font(&mut self, source: FontSource) -> Result<Vec<u16>, AddFontError>

Registers a face, and re-runs everything a face can change.

A family the registry did not have is a family the cascade resolved to something else, so the styling is compiled again and the lines are broken again. The output’s font table is rebuilt with them.

Only a session that owns its registry has one to add to; one that borrowed it says so instead.

pub fn add_image( &mut self, url: &str, bytes: Vec<u8>, ) -> Result<Option<u32>, AddImageError>

Registers one image, and the index DrawItem::Image.asset gets for it. None for bytes no probe recognises, which is a diagnostic on the next display structure and no asset.

A url registered again with the bytes it already answers for costs nothing. Registered again with different bytes, it replaces them in place: the box the image takes is re-broken only if the header now reports a different size, since the PDF writer reads the asset table fresh on every export and needs no invalidation to see new pixels at an unchanged size. An image whose contour was traced is the exception, because the pixels are what the contour came from. Only a session that owns its asset table has one to add to; one that borrowed it says so instead.

impl Session<'_>

pub fn add_font_file( &mut self, url: &str, bytes: Vec<u8>, ) -> Result<(), AddFontError>

Keeps a font file under the url a @font-face names it by, and registers whatever the sheet declares from it.

A url no rule names is kept until one does, so the file and the sheet can arrive in either order. The same bytes at the same url again cost nothing.

impl Session<'_>

pub fn inspect(&mut self, node: NodeId) -> Option<Inspection>

The element one node stands for, the rules that matched it and what it computed to, and its border box on each page it reaches. A text node answers for the element that holds it. A pseudo-element answers for itself, with its own boxes: the box ::before or ::after generates on a block, or else the area its text covers on each page.

Nothing for a node the book does not hold, or for the id the engine writes its own text under. An id names a node only until the next edit, so the answer is about the book as it stands.

pub fn inspect_margin_box( &mut self, index: usize, which: MarginBox, ) -> Option<Inspection>

The same for one margin box of the page at index, counting from 0: the page selector it answers to, the @page rules that set it, and the box its text takes.

Nothing for a page the book does not have, for a blank page, and for a box no rule for that page names.

pub fn hit(&mut self, index: usize, x: f32, y: f32) -> Option<NodeId>

The innermost element at a point on the page at index, in points from its top-left corner: the element that holds the text there, or else the innermost block whose border box holds the point, padding and empty space included. Where two such things overlap, the one painted later answers. A pseudo-element answers with its own id: a drop cap, the line a paragraph opens on, and the box or the text of ::before and ::after. An inline element on the opening line answers for itself.

Nothing outside every box, and nothing for a page the book does not have.

impl Session<'_>

pub fn preview(&mut self) -> &LayoutOutput

The display structure, brought up to date.

pub fn export(&mut self) -> Result<Vec<u8>, PdfError>

The same, as PDF bytes. The stages above the painter are the ones the preview used, so an export cannot contradict it.

pub fn folios(&mut self, nodes: &[NodeId]) -> Vec<Option<Folios>>

Where each of these nodes’ content is set, answered in the order they were asked about: the folios it runs between, and the pages of the book those folios are.

A node covers itself and everything under it, so a heading answers with the page its own text is on, and a chapter with the pages it runs across. Nothing for a node the book does not hold, and nothing for one whose content reaches no page: a node the engine synthesized, or a scene break, whose ornament the engine wrote itself.

The answer is a walk over the pages the session already holds. It runs a stage only when an edit has left one to run.

pub fn into_output(self) -> LayoutOutput

The display structure by value, consuming the session.

impl<'a> Session<'a>

pub fn new(registry: &'a FontRegistry) -> Session<'a>

A session over the faces in registry, with no content and the built-in sheet alone.

pub fn with_assets( registry: &'a FontRegistry, assets: &'a Assets, ) -> Session<'a>

The same, over images the host has already probed.

pub fn owning(registry: FontRegistry) -> Session<'static>

A session that owns the faces it lays out against, and takes more through add_font.

This is the shape a worker needs: font bytes cross the boundary once, the module keeps them, and no caller on the other side of the wall has a registry to lend.

impl Session<'_>

pub fn book(&self) -> &Book

The session’s own copy of the book, node ids assigned.

pub fn names(&self, source: Option<&str>) -> Names

The classes and the ids the blocks and inlines of one source carry, or of the whole book when source is None, as the book holds them now. A section’s own names are not in the answer.

pub fn styles(&self) -> &StyleTree

The compiled styling behind the last update.

pub fn sheets(&self) -> Option<&Stylesheets>

The sheets the styling was compiled from, as the host last set them.

pub fn images(&self) -> &Assets

The images this session holds, by the url each was registered under.

pub fn font_files(&self) -> &dyn FontLoader

The files add_font_file handed over, by the url a @font-face names them by.

pub fn fonts(&self) -> &FontRegistry

The faces this session lays out against.

A painter that has to draw with the same file the shaper used reaches the bytes through here; the display structure names ids, and the registry is what they index.

pub fn stages(&self) -> Stages

How many times each stage has run.

pub fn reuses_sections(&self) -> bool

Whether a section’s lines survive an edit elsewhere in the book. This goes false when the styling breaks a precondition, either masters of different measures or inline content that depends on pagination, and everything is re-broken instead.