Files
craft-libs/crates/wordmodel/src/para/float.rs
T
Dylan M. Taylor 08882273d1 Add craft-wordmodel: WordCraft's document model without its editing code (#963)
* Add craft-wordmodel: WordCraft's document model without its editing code

WordCraft's crates/doc (wordcraft-doc, at 07f97737) moved as it is, so the DOCX,
RTF, ODT and other text-format crates can read into and write from one model.
Module paths, type names and serde attributes are unchanged: an app that
re-exports the crate keeps its native file format.

Left in the app: range editing (edit.rs), IME text and equation editing. Not
model, and already in craft-libs: code pages (craft-rtf), the ZIP entry-count
check (craft-opc), the compound-file guard (craft-cfb). The paragraph walks
moved to walk.rs and the unit helpers of wordcraft-geom to geom.rs.

* craft-wordmodel: math_tree, the arguments of an equation node and a walk over its runs

The DOCX reader and writer walk an equation's runs. The walk and the child
accessors it uses were in WordCraft's equation editor (math_edit.rs), which
stays in the app; they are structure, not editing.

* craft-wordmodel: keep the document operations (edit.rs) with the model

The DOCX and RTF readers use them: alternative-format chunks are merged into
a document with adopt_blocks, and a reader formats ranges with format_range
and inserts objects. They operate on the document, not on a view, so they
belong beside it. The tests that drove them come back with them; the
paragraph walks stay in walk.rs and edit re-exports them.

base64 0.23, as WordCraft and craft-offcrypto use.
2026-11-11 19:43:08 -05:00

286 lines
11 KiB
Rust
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
use super::{Deserialize, Serialize};
/// How a floating object is placed.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize, Default)]
#[serde(rename_all = "camelCase")]
pub enum Wrap {
/// In line with text (not floating).
#[default]
Inline,
Square,
Tight,
Through,
TopAndBottom,
BehindText,
InFrontOfText,
}
/// Which sides of a Square, Tight or Through object text may flow on (`@wrapText`, ECMA-376
/// Part 1, §20.4.3.7 `ST_WrapText`).
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize, Default)]
#[serde(rename_all = "camelCase")]
pub enum WrapText {
/// Both sides of the object.
#[default]
BothSides,
/// Only the left side: the band to the object's right stays empty.
Left,
/// Only the right side.
Right,
/// Only whichever side has more room, decided per line.
Largest,
}
impl WrapText {
/// From the OOXML value (`bothSides`, `left`, `right`, `largest`).
pub fn from_ooxml(v: &str) -> Option<WrapText> {
let v = v.trim();
if v.eq_ignore_ascii_case("bothSides") || v.eq_ignore_ascii_case("both") {
Some(WrapText::BothSides)
} else if v.eq_ignore_ascii_case("left") {
Some(WrapText::Left)
} else if v.eq_ignore_ascii_case("right") {
Some(WrapText::Right)
} else if v.eq_ignore_ascii_case("largest") {
Some(WrapText::Largest)
} else {
None
}
}
/// The OOXML value.
pub fn ooxml(self) -> &'static str {
match self {
WrapText::BothSides => "bothSides",
WrapText::Left => "left",
WrapText::Right => "right",
WrapText::Largest => "largest",
}
}
pub fn is_both(&self) -> bool {
*self == WrapText::BothSides
}
}
/// What a floating object's offset is relative to.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize, Default)]
#[serde(rename_all = "camelCase")]
pub enum Anchor {
#[default]
Column,
Margin,
Page,
Paragraph,
/// The page's left margin area (from the page's left edge to the text).
LeftMargin,
/// The page's right margin area (from the text to the page's right edge).
RightMargin,
/// The page's top margin area (from the page's top edge to the text).
TopMargin,
/// The page's bottom margin area (from the text to the page's bottom edge).
BottomMargin,
/// The inside margin (left on odd pages, right on even pages when mirrored).
InsideMargin,
/// The outside margin.
OutsideMargin,
/// The anchor character (horizontal only).
Character,
/// The anchor line (vertical only).
Line,
}
/// Alignment of a floating object within its [`Anchor`] area, instead of an offset.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub enum FloatAlign {
/// Left or top.
Start,
Center,
/// Right or bottom.
End,
Inside,
Outside,
}
impl FloatAlign {
/// From an OOXML alignment (`wp:align`, `w:tblpXSpec`, `w:tblpYSpec`).
pub fn from_ooxml(v: &str) -> Option<FloatAlign> {
match v {
"left" | "top" => Some(FloatAlign::Start),
"center" => Some(FloatAlign::Center),
"right" | "bottom" => Some(FloatAlign::End),
"inside" => Some(FloatAlign::Inside),
"outside" => Some(FloatAlign::Outside),
_ => None,
}
}
/// The OOXML name on the horizontal (`left`, `right`) or vertical (`top`, `bottom`) axis.
pub fn ooxml(self, horizontal: bool) -> &'static str {
match (self, horizontal) {
(FloatAlign::Start, true) => "left",
(FloatAlign::Start, false) => "top",
(FloatAlign::Center, _) => "center",
(FloatAlign::End, true) => "right",
(FloatAlign::End, false) => "bottom",
(FloatAlign::Inside, _) => "inside",
(FloatAlign::Outside, _) => "outside",
}
}
}
/// Floating placement (ignored when `wrap` is `Inline`).
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, Default)]
#[serde(default, rename_all = "camelCase")]
pub struct Float {
pub wrap: Wrap,
/// The sides text wraps on (Square, Tight and Through).
#[serde(skip_serializing_if = "WrapText::is_both")]
pub wrap_text: WrapText,
pub h_rel: Anchor,
pub v_rel: Anchor,
/// Offsets, points (used when the matching alignment is `None`).
pub x: f32,
pub y: f32,
/// Alignments within the anchor area; they take precedence over the offsets.
#[serde(skip_serializing_if = "Option::is_none")]
pub h_align: Option<FloatAlign>,
#[serde(skip_serializing_if = "Option::is_none")]
pub v_align: Option<FloatAlign>,
/// Distance from surrounding text at the left and right (points).
pub dist: f32,
/// Distance from surrounding text above and below (points).
pub dist_top: f32,
pub dist_bottom: f32,
/// Room around the object for effects such as shadows (left, top, right, bottom, points),
/// inline or floating: lines and surrounding text keep clear of it. Rotation's own overhang
/// is not in here: it follows from [`Float::rot`] (see [`Float::spin_pad`]).
pub effect: [f32; 4],
/// Rotation clockwise about the object's centre, degrees (DrawingML `a:xfrm/@rot`). Offsets
/// and the size stay those of the unrotated frame, as in Word; see [`Float::spin`].
#[serde(skip_serializing_if = "is_zero")]
pub rot: f32,
/// Mirrored left to right / top to bottom (`a:xfrm/@flipH`, `@flipV`).
#[serde(skip_serializing_if = "is_false")]
pub flip_h: bool,
#[serde(skip_serializing_if = "is_false")]
pub flip_v: bool,
/// The outline Tight and Through wrapping follow (`wp:wrapPolygon`), in the object's own
/// (unrotated) frame; `None` = derived from the object (see [`crate::wrap`]).
#[serde(skip_serializing_if = "Option::is_none")]
pub wrap_polygon: Option<std::sync::Arc<crate::wrap::WrapPolygon>>,
/// What the drawing is, for screen readers and exports (`wp:docPr` `@descr`, `@title` and the
/// decorative mark). See [`InlineObject::alt_text`].
#[serde(skip_serializing_if = "AltText::is_empty")]
pub alt: AltText,
/// Hidden (`wp:docPr/@hidden`, VML `visibility:hidden`): kept and saved, but neither drawn nor
/// laid out, as Word for Windows does (Word for Mac draws hidden VML shapes).
#[serde(skip_serializing_if = "is_false")]
pub hidden: bool,
/// Anchored in a table cell but placed on the page, not in the cell (`wp:anchor/@layoutInCell`
/// off, any VML shape in a header or footer): a picture watermark in a header that starts with a table.
#[serde(skip_serializing_if = "is_false")]
pub outside_cell: bool,
/// Stacking order among floating objects (`wp:anchor/@relativeHeight`): higher is drawn on
/// top. 0 = unknown, drawn in document order (objects inserted here, or from other formats).
#[serde(skip_serializing_if = "is_zero_u32")]
pub z: u32,
/// The page a drawing anchored to a page is on, from 1 (ODF's `text:anchor-page-number`,
/// §19.872); 0 = anchored to its paragraph or not said. Kept for saving: the layout places a
/// drawing on its anchor paragraph's page.
#[serde(skip_serializing_if = "is_zero_u32")]
pub page: u32,
/// Turned, but the file keeps no room for the turn (`wp:effectExtent` missing or zero, as
/// files from other tools have): Word then keeps an inline one's line to its frame and lets
/// the turned object overhang it (see [`Float::line_pad`]). Cleared by [`Float::set_spin`].
#[serde(skip_serializing_if = "is_false")]
pub bare_turn: bool,
}
/// Longest alternative text kept (characters): hostile files and commands are capped.
pub const MAX_ALT_TEXT: usize = 10_000;
/// A drawing's alternative text (Picture/Shape Format › Accessibility › Alt Text).
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, Default)]
#[serde(default, rename_all = "camelCase")]
pub struct AltText {
/// The description of a shape, text box or group. Pictures and charts keep theirs in their
/// own `alt`; read it with [`InlineObject::alt_text`], which knows where it is.
#[serde(skip_serializing_if = "String::is_empty")]
pub text: String,
/// The short title (`wp:docPr/@title`).
#[serde(skip_serializing_if = "String::is_empty")]
pub title: String,
/// Decorative: it adds nothing to the content, so screen readers skip it and the
/// accessibility checker doesn't ask for a description.
#[serde(skip_serializing_if = "is_false")]
pub decorative: bool,
}
impl AltText {
pub fn is_empty(&self) -> bool {
self.text.is_empty() && self.title.is_empty() && !self.decorative
}
}
/// `s` cut to [`MAX_ALT_TEXT`] characters.
pub fn cap_alt(s: &str) -> String {
s.chars().take(MAX_ALT_TEXT).collect()
}
fn is_zero(v: &f32) -> bool {
*v == 0.0
}
fn is_false(v: &bool) -> bool {
!*v
}
fn is_zero_u32(v: &u32) -> bool {
*v == 0
}
impl Float {
/// The rotation and flips, the angle normalised to `0..360` (a NaN angle is no rotation).
pub fn spin(&self) -> crate::geom::Spin {
crate::geom::Spin::new(self.rot, self.flip_h, self.flip_v)
}
/// Set the rotation and flips (the angle normalised).
pub fn set_spin(&mut self, s: crate::geom::Spin) {
self.rot = crate::geom::normalize_degrees(s.deg);
self.flip_h = s.flip_h;
self.flip_v = s.flip_v;
self.bare_turn = false;
}
/// How far a `w` × `h` frame's rotated bounds reach past it on each side (x, y): the room a
/// rotated object takes beyond its frame (zero unrotated; negative where the turned object
/// is narrower than its frame, as a wide picture turned 90° is).
pub fn spin_pad(&self, w: f32, h: f32) -> (f32, f32) {
let (w, h) = (crate::geom::finite(w).clamp(0.0, 4000.0), crate::geom::finite(h).clamp(0.0, 4000.0));
let (bw, bh) = self.spin().extent(w, h);
((bw - w) / 2.0, (bh - h) / 2.0)
}
/// A [`Float::bare_turn`] still inline and without effects room: made floating, or given room
/// for a shadow or glow since, it saves, and so lays out, with the turn's room again.
pub fn is_bare_turn(&self) -> bool {
self.bare_turn && self.wrap == Wrap::Inline && self.effect_extent() == [0.0; 4]
}
/// The room an inline `w` × `h` object's line keeps past its frame on each side (x, y) for its
/// turn: its rotated bounds ([`Float::spin_pad`]) — or, for a [`Float::is_bare_turn`], none, except
/// that Word 2013+ layout (`modern`) exchanges the frame's width and height from 45° up to 135°
/// and from 225° up to 315°.
pub fn line_pad(&self, w: f32, h: f32, modern: bool) -> (f32, f32) {
if !self.is_bare_turn() {
return self.spin_pad(w, h);
}
let (w, h) = (crate::geom::finite(w).clamp(0.0, 4000.0), crate::geom::finite(h).clamp(0.0, 4000.0));
let deg = crate::geom::normalize_degrees(self.rot);
if modern && ((45.0..135.0).contains(&deg) || (225.0..315.0).contains(&deg)) { ((h - w) / 2.0, (w - h) / 2.0) } else { (0.0, 0.0) }
}
/// The effect extents, finite and clamped (left, top, right, bottom).
pub fn effect_extent(&self) -> [f32; 4] {
self.effect.map(|v| if v.is_finite() { v.clamp(0.0, 1584.0) } else { 0.0 })
}
}