JabRef 6.0-beta.1 · org.jabref.logic.undo.UndoManager

Puts changes on the undo journal. What almost every client of undo actually needs.

Undoing, redoing, asking whether the library differs from the last saved position and subscribing to stack changes are the business of a handful of classes — the Undo and Redo actions, the menu bindings and the library tab that draws the modified marker. Everything else edits the library and hands the change over, and there are roughly 120 such classes. Passing them the whole manager hands every field editor, cleanup and import task the ability to rewrite the user's history, when all any of them does is describe what it just changed.

Those classes depend on this type; the few that drive the stacks depend on JabRefUndoManager. What a class asks for therefore says what it does with it.

Method Summary

Modifier and Type	Method and Description
public void	addEdit(BibChange change) Records a change the caller has already made.
public boolean	Returns: whether anything was recorded, for callers that report the outcome to the user addEdit(String name, Consumer<CompoundEdit> mutations) Runs `mutations` and records whatever it reports as one undo step named `name`.
public default ApplyResult	Returns: what was applied, and what was not — see `BibChange#apply` applyEdit(BibChange change) Performs `change` and records it in one go, as one user action.
public ApplyResult	Returns: what was applied, and what was not — see `BibChange#apply` applyEdit(BibChange change, EditSource source) Performs `change` and records it in one go, saying who is recording it.
public void	endStep() Ends the step being collected, so that the next change starts one of its own.
public void	markChanged() Marks the library as changed by something this journal cannot take back — a migration on load, an external change the user denied, a setting written without being recorded.
public UndoSuspension	suspendUndo(String the command holding the library, as the user would recognise it — shown when undo declines name) Suspends undo and redo for this library while the caller applies changes it has not yet handed over.

Method Detail

addEdit	back to summary
public void addEdit(BibChange change) Records a change the caller has already made.

addEdit back to summary

addEdit	back to summary
public boolean addEdit(String name, Consumer<CompoundEdit> mutations) Runs `mutations` and records whatever it reports as one undo step named `name`. Returns:boolean whether anything was recorded, for callers that report the outcome to the user

public boolean addEdit(String name, Consumer<CompoundEdit> mutations)

Runs mutations and records whatever it reports as one undo step named name.

Returns:boolean: whether anything was recorded, for callers that report the outcome to the user

applyEdit back to summary

applyEdit	back to summary
public default ApplyResult applyEdit(BibChange change) Performs `change` and records it in one go, as one user action. Returns:ApplyResult what was applied, and what was not — see `BibChange#apply`

public default ApplyResult applyEdit(BibChange change)

Performs change and records it in one go, as one user action.

Returns:ApplyResult: what was applied, and what was not — see BibChange#apply

applyEdit back to summary

applyEdit	back to summary
public ApplyResult applyEdit(BibChange change, EditSource source) Performs `change` and records it in one go, saying who is recording it. Only `EditSource#TYPING` may continue the step on top of the stack; everything else is a step of its own, so a command that writes the field the user was just typing in does not join what they typed. Returns:ApplyResult what was applied, and what was not — see `BibChange#apply`

public ApplyResult applyEdit(BibChange change, EditSource source)

Performs change and records it in one go, saying who is recording it.

Only EditSource#TYPING may continue the step on top of the stack; everything else is a step of its own, so a command that writes the field the user was just typing in does not join what they typed.

Returns:ApplyResult: what was applied, and what was not — see BibChange#apply

endStep	back to summary
public void endStep() Ends the step being collected, so that the next change starts one of its own. A field editor records one change per keystroke, and the journal groups a run of them into one step so that Ctrl+Z takes back a word rather than a letter. It cannot see where the run ends, though — that is the editor's knowledge — so an editor that stops editing one thing and starts another says so here. Ending a step nobody is continuing does nothing.

endStep

back to summary

public void endStep()

Ends the step being collected, so that the next change starts one of its own.

A field editor records one change per keystroke, and the journal groups a run of them into one step so that Ctrl+Z takes back a word rather than a letter. It cannot see where the run ends, though — that is the editor's knowledge — so an editor that stops editing one thing and starts another says so here. Ending a step nobody is continuing does nothing.

markChanged	back to summary
public void markChanged() Marks the library as changed by something this journal cannot take back — a migration on load, an external change the user denied, a setting written without being recorded. The modified marker derives from the saved position, so a write nobody recorded has to say so here, or the library looks saved. Saving is what clears it again.

markChanged

back to summary

public void markChanged()

Marks the library as changed by something this journal cannot take back — a migration on load, an external change the user denied, a setting written without being recorded.

The modified marker derives from the saved position, so a write nobody recorded has to say so here, or the library looks saved. Saving is what clears it again.

suspendUndo back to summary

suspendUndo	back to summary
public UndoSuspension suspendUndo(String name) Suspends undo and redo for this library while the caller applies changes it has not yet handed over. The undo UI reads the other end of this through `GuiUndoManager#suspendedBy`. A command that mutates on a background thread writes to the library long before anything reaches the stack, and an undo arriving in that window takes back a change underneath those writes: the library then holds a state no step on the stack describes, and the push that follows discards the undone change with the redo stack. Suspending is how a caller says that window is open. Nothing waits: undo and redo decline while a suspension is open rather than blocking on it, so a long import can never freeze the JavaFX thread on Ctrl+Z. `addEdit(String, Consumer)` suspends for the duration of the block, so only the commands that collect by hand need this. Close it after the push, or the window reopens between the last write and the record. Parameters name:String the command holding the library, as the user would recognise it — shown when undo declines

public UndoSuspension suspendUndo(String name)

Suspends undo and redo for this library while the caller applies changes it has not yet handed over. The undo UI reads the other end of this through GuiUndoManager#suspendedBy.

A command that mutates on a background thread writes to the library long before anything reaches the stack, and an undo arriving in that window takes back a change underneath those writes: the library then holds a state no step on the stack describes, and the push that follows discards the undone change with the redo stack. Suspending is how a caller says that window is open.

Nothing waits: undo and redo decline while a suspension is open rather than blocking on it, so a long import can never freeze the JavaFX thread on Ctrl+Z.

addEdit(String, Consumer) suspends for the duration of the block, so only the commands that collect by hand need this. Close it after the push, or the window reopens between the last write and the record.

Parameters

name:String: the command holding the library, as the user would recognise it — shown when undo declines

public Interface UndoManager

Method Summary

Method Detail