pptx_rs/shape/
base.rs

1//! `Shape`：所有形状的"基类"包装。
2//!
3//! 本文件定义高阶形状的统一接口 [`Shape`]，由 `AutoShape` / `TextBox` /
4//! `Picture` / `Group` / `Connector` / `TableShape` 各自实现。
5//!
6//! # 设计要点
7//!
8//! - **位置 / 尺寸 / 旋转** 等通用属性被提到 trait 层，避免在每个形状上重复定义；
9//! - **类型相关**的属性（如 `Picture::set_stretch`、`Connector::cxn`）保留在
10//!   具体类型的 `impl` 块中；
11//! - trait 方法均**只读 / 可变**访问 `self`，不返回额外句柄，
12//!   避免破坏"借用 oxml 模型"的不变式。
13//!
14//! # 与 python-pptx 的对应
15//!
16//! - `pptx.shapes.base.BaseShape` ←→ [`Shape`] trait；
17//! - python-pptx 把通用属性都挂在 `BaseShape` 上，python 端可以直接调用；
18//!   本库因 Rust trait 限制需要在每个 impl 上"转发"方法。
19
20use crate::units::Emu;
21
22/// 高阶形状的抽象接口。
23///
24/// 调用方拿到一个 `Shape`（trait object）或具体类型时，可通过此 trait
25/// 访问"位置 / 尺寸 / 旋转"等通用属性。具体类型特有属性需用具体类型
26/// 句柄访问。
27pub trait Shape {
28    /// 形状唯一 ID（在所属 slide 内）。
29    ///
30    /// ID 由 `add_*` 流程自动分配，调用方一般不应手动设置。
31    fn id(&self) -> u32;
32    /// 设置 ID。
33    fn set_id(&mut self, id: u32);
34    /// 形状名。
35    fn name(&self) -> &str;
36    /// 设置形状名。
37    fn set_name(&mut self, name: String);
38    /// 形状类型（如 `"text_box"` / `"picture"` / ...）。
39    ///
40    /// 返回值与 [`crate::shape::ShapeKind::shape_type`] 保持一致。
41    fn shape_type(&self) -> &'static str;
42
43    /// 左上角 x（EMU）。
44    fn left(&self) -> Emu;
45    /// 设置左上角 x。
46    fn set_left(&mut self, emu: Emu);
47    /// 左上角 y（EMU）。
48    fn top(&self) -> Emu;
49    /// 设置左上角 y。
50    fn set_top(&mut self, emu: Emu);
51    /// 宽（EMU）。
52    fn width(&self) -> Emu;
53    /// 设置宽。
54    fn set_width(&mut self, emu: Emu);
55    /// 高（EMU）。
56    fn height(&self) -> Emu;
57    /// 设置高。
58    fn set_height(&mut self, emu: Emu);
59
60    /// 旋转角度（度数，正向顺时针）。
61    ///
62    /// 与 OOXML 规范的"60000 分之一度"通过 `set_rotation` 自动转换；
63    /// 读取时返回度数。
64    fn rotation(&self) -> f64;
65    /// 设置旋转角度。
66    fn set_rotation(&mut self, deg: f64);
67}
pptx_rs/shape/base.rs

pptx_rs/shape/
base.rs
