Expand description
Transient edits: changes to the document that no undo history records.
An input method’s composition (the candidates of a Chinese or Japanese input method, the
Korean syllable being built, the live text of dictation) has to be shown in the text,
where the writer is looking, and has to be replaced at every update. Made as ordinary
edits, every update was recorded, and once the composition was committed an undo
replayed each state it went through. A transient edit changes the document and is
announced as a change of its content is (DocumentEvent::ContentsChanged, and the
block and flow events when they apply), so views lay it out and draw it, but it is not
recorded: the undo and redo histories stay as they were, and so does the coalescing of
typing. Nothing arrives yet, so there is no DocumentEvent::TextInserted.
The edits are TextCursor::insert_text_transient,
TextCursor::insert_text_transient_merged,
TextCursor::insert_formatted_text_transient and
TextCursor::remove_selected_text_transient.
§The layer
The outstanding transient edits are one layer over the document as it is recorded. The layer belongs to the document, whichever cursor made its edits. It begins with the first transient edit and ends when it is reverted, which puts the recorded content back as it was before that first edit: the same text, formats and block identities, which is what every recorded undo entry refers to. Nothing is recorded and the histories are untouched.
The layer ends in one of three ways:
TextDocument::revert_transient_edits: the composition is cancelled.TextCursor::commit_transient_text: the composition is committed. The layer is reverted, and the text it changed is replaced with the committed text, recorded as one undo step of its own, closed on both sides: it does not coalesce with the typing before it, and the typing after it starts a step of its own, so an undo takes back exactly the committed text and gives back what the composition took the place of. Inside an open edit block (TextCursor::begin_edit_block) the commit joins the block, as every recorded edit there does.- Any recorded write to the document, by any cursor or clone of the document. Every edit, undo, redo and load reverts the layer before anything else, its own checks included, then acts on the recorded content, so the layer is gone even when the write then fails or changes nothing. The streaming appends alone check their lines first, and leave the layer when they refuse them.
So a host never keeps its own record of where its composition is: before each update it
asks TextDocument::transient_range, which is None once anything has reverted it.
The history’s operations that change no content do not end the layer:
TextDocument::clear_undo_redo, TextDocument::break_undo_merge and an edit block
leave it outstanding. Nor does TextDocument::set_footnote_markers: the markers are
the host’s, not content, and a revert keeps them.
§Positions
A revert puts every cursor back in the recorded text. One that only the transient edits moved goes back exactly where it stood, the table cells or the whole text it selected included. Any other (one that something else moved meanwhile, one made since) is moved back across each transient edit in turn, from the last, an edit that touches the text the one before it made counting with it as one (a syllable taken out and its candidate shown in its place are one replacement): a position before the edit stays, and one after the text it inserted moves by the difference. One inside that text, or at its end, goes to the end of the recorded text the edit replaced, and one at its start to that text’s start, except where the edit only removed text: there a selection’s start, or a caret, goes after the text put back, and its end before it. So a selection holds the recorded text it held, and one that held only text a transient edit inserted over nothing comes back empty.
The recorded writes read a cursor after their revert, so they act where it stands in the
recorded text. The explicit ranges of TextCursor::replace and
TextDocument::replace_ranges are read in the document as it was, with the layer, and
moved back the same way, under the lock the write itself takes.
§Reading
While the layer is outstanding, the document reads as it shows: the text, the flow, a
search, an export. A host that saves on a timer saves the composition with the rest, and
should revert or commit first when that matters (see
TextDocument::has_transient_edits).
A view that is not where the transient edits are made (a read-only preview beside the
editor an input method composes in) shows the recorded document instead:
TextDocument::snapshot_recorded_flow_masked, its _no_paint twin and
TextDocument::snapshot_recorded_block_at_position_masked snapshot it as a revert
would leave it. Its positions are the recorded document’s: such a view draws a cursor at
TextCursor::recorded_position and TextCursor::recorded_anchor, where a revert
puts it, places any other position of the document with
TextDocument::recorded_position, and maps a position read off its own layout into
the document with TextDocument::position_from_recorded. A view that shows only the
transient edits it made itself tells its layer from another with
TextDocument::transient_layer.
§Under a host’s lock
An input method that edits under a lock of its own (Windows’ Text Services Framework
grants one, and reads back what it wrote under the same lock) must not see application
code write the document while it holds the lock: a recorded write by a change callback
would revert the layer, and the input method would read back text other than the text it
wrote. The host holds the document’s events for the lock’s duration
(TextDocument::hold_events). Under the hold, the transient edits, their revert, their
commit and every other edit change the document and move its cursors at once, and every
read (TextDocument::transient_range, the text, a cursor’s position) sees them; only
their events wait, and go out in the order they were queued when the hold is dropped,
after the lock. A callback that then writes the document reverts or ends the layer as
any recorded write does, outside the lock.
§Refusals
What the layer cannot do is refused with DocumentError::TransientEdits, whose
TransientRefusal says which case it is. Underneath, the
document’s store enforces what the layer needs of it, whoever calls it:
- while a layer is outstanding, it refuses to begin any write that is not a transient
edit’s own (a write transaction, a streaming append), so that no recorded edit lands
over the layer and is then taken away by the revert. Every write this crate offers
reverts the layer first, so that refusal reaches a caller only when a transient edit
is made from another thread between the revert and the write
(
TransientRefusal::LayerOutstanding); - it refuses to begin a transient write while any other write is open, a transient one
included, since the first one’s snapshot is the recorded content
(
TransientRefusal::WriteInProgress); - it refuses a revert while a transient write is in progress, which the document’s lock rules out here.
Structs§
- Transient
Layer Id - Which layer of transient edits a document holds (see
TextDocument::transient_layer): the same for as long as they are outstanding, and another once they have ended and new ones begin, in this document or any other.