text_document/lib.rs
1//! A model for text documents.
2//!
3//! This model is thought as a backend for a text UI. [`TextDocument`] can't be modified directly by the user, only for setting the whole document with `set_plain_text(...)`.
4//! The user must use a [`TextCursor`] using `document.create_cursor()` to make any change.
5//!
6//! # Document structure
7//!
8//! ## Elements
9//!
10//! - [`Frame`]: contains Block elements and other Frame elements, formatable with FrameFormat
11//! - [`Block`]: contains Text elements or Image elements, formatable with BlockFormat
12//! - [`Text`]: contains the actuel text, formatable with TextFormat
13//! - [`Image`]: represent the position of an image, formatable with ImageFormat
14//!
15//! All these items are encapsulated in its corresponding [`Element`] for ease of storage.
16//!
17//! ## The simpler plain text
18//!
19//! ```raw
20//! Frame
21//! |- Block
22//! |- Text
23//! |- Block
24//! |- Text
25//! ```
26//!
27//! ## The more complex rich text
28//!
29//! ```raw
30//! Frame
31//! |- Block
32//! |- Text --> I really lo
33//! |- Text --> ve (imagine it Formatted in bold)
34//! |- Text --> Rust
35//! |- Image
36//! |- Text
37//! |- Frame
38//! |- Block
39//! |- Text
40//! |- Text
41//! |- Text
42//! |- Block
43//! |- Text
44//! |- Text
45//! |- Text
46//! |- Block
47//! |- Image
48//! ```
49//!
50//! # Signaling changes
51//!
52//! Each modification is signaled using callbacks. [`TextDocument`] offers different ways to make your code aware of any change:
53//!- [`TextDocument::add_text_change_callback()`]
54//!
55//! Give the number of removed characters and number of added characters with the reference of a cursor position.
56//!
57//!- [`TextDocument::add_element_change_callback()`]
58//!
59//! Give the modified element with the reason. If two direct children elements changed at the same time.
60//!
61//! # Examples
62//!
63//! ```rust
64//! use text_document::{TextDocument, ChangeReason, MoveMode};
65//!
66//! let mut document = TextDocument::new();
67//!
68//! document.add_text_change_callback(|position, removed_characters, added_characters|{
69//! println!("position: {}, removed_characters: {}, added_characters: {}", position, removed_characters, added_characters);
70//! } );
71//!
72//! document.add_element_change_callback(|element, reason|{
73//! assert_eq!(element.uuid(), 0);
74//! assert_eq!(reason, ChangeReason::ChildrenChanged );
75//! } );
76//! document.set_plain_text("beginningend").unwrap();
77//!
78//! let mut cursor = document.create_cursor();
79//! cursor.set_position(9, MoveMode::MoveAnchor);
80//! cursor.insert_plain_text("new\nplain_text\ntest");
81//!
82//!
83//! ```
84
85pub mod block;
86pub mod font;
87pub mod format;
88pub mod frame;
89pub mod image;
90pub mod text;
91pub mod text_cursor;
92pub mod text_document;
93
94pub use crate::text_document::*;
95pub use block::*;
96pub use frame::*;
97pub use image::*;
98pub use text::*;
99pub use text_cursor::*;
100
101// Not public API.
102#[doc(hidden)]
103pub mod private {}