provides access to the undo/redo stacks of a document More...

import"XUndoManager.idl";

Inheritance diagram for XUndoManager:

Exported Interfaces
interface	::com::sun::star::util::XLockable
	allows locking the undo manager. More...

interface	::com::sun::star::container::XChild
	allows accessing the component, usually a document, which the undo manager works for. More...

Public Member Functions
void	enterUndoContext ([in] string iTitle)
	enters a new undo context. More...

void	enterHiddenUndoContext () raises ( EmptyUndoStackException )
	enters a new undo context, creating a hidden undo action. More...

void	leaveUndoContext () raises ( ::com::sun::star::util::InvalidStateException )
	leaves the undo context previously opened via enterUndoContext() respectively enterHiddenUndoContext(). More...

void	addUndoAction ([in] XUndoAction iAction) raises ( ::com::sun::star::lang::IllegalArgumentException )
	adds the given undo action to the undo stack. More...

void	undo () raises ( ::com::sun::star::document::EmptyUndoStackException, ::com::sun::star::document::UndoContextNotClosedException, ::com::sun::star::document::UndoFailedException )
	reverts the most recent action on the document. More...

void	redo () raises ( ::com::sun::star::document::EmptyUndoStackException, ::com::sun::star::document::UndoContextNotClosedException, ::com::sun::star::document::UndoFailedException )
	replays the action on the document which has most recently been undone More...

boolean	isUndoPossible ()
	determines whether undo() can reasonably be expected to succeed. More...

boolean	isRedoPossible ()
	determines whether redo() can reasonably be expected to succeed. More...

string	getCurrentUndoActionTitle () raises ( ::com::sun::star::document::EmptyUndoStackException )
	returns the title of the top-most action on the undo stack More...

string	getCurrentRedoActionTitle () raises ( ::com::sun::star::document::EmptyUndoStackException )
	returns the title of the top-most action on the Redo stack More...

sequence< string >	getAllUndoActionTitles ()
	returns the titles of all actions currently on the undo stack, from top to bottom More...

sequence< string >	getAllRedoActionTitles ()
	returns the titles of all actions currently on the Redo stack, from top to bottom More...

void	clear () raises ( ::com::sun::star::document::UndoContextNotClosedException )
	clears the undo and the redo stack. More...

void	clearRedo () raises ( ::com::sun::star::document::UndoContextNotClosedException )
	clears the redo stack. More...

void	reset ()
	resets the Undo manager More...

void	addUndoManagerListener ([in] XUndoManagerListener iListener)
	adds a listener to be notified of changes in the Undo/Redo stacks. More...

void	removeUndoManagerListener ([in] XUndoManagerListener iListener)
	removes a previously added listener More...

Public Member Functions inherited from XLockable
void	lock ()
	locks the component More...

void	unlock () raises ( NotLockedException )
	unlocks the component More...

boolean	isLocked ()
	determines whether the component is currently locked. More...

Public Member Functions inherited from XChild
com::sun::star::uno::XInterface	getParent ()
	grants access to the object containing this content. More...

void	setParent ([in] com::sun::star::uno::XInterface Parent) raises ( com::sun::star::lang::NoSupportException )
	sets the parent to this object. More...

Public Member Functions inherited from XInterface
any	queryInterface ([in] type aType)
	queries for a new interface to an existing UNO object. More...

void	acquire ()
	increases the reference counter by one. More...

void	release ()
	decreases the reference counter by one. More...

Detailed Description

provides access to the undo/redo stacks of a document

Undo

Changes to a document usually result in recording of information how to undo those changes, if desired. A so-called undo action records the information how to undo a single change. Undo actions are maintained in a stack, so that the changes they represent can be undo in the reverse order they have originally been applied.

Redo

Additionally, the Undo manager manages a Redo stack: Actions which are undone are moved from the Undo to the Redo stack, so it is possible to re-apply the changes to the document.

Undo contexts

For collecting multiple changes in a single undo action, so-called Undo contexts are provided. When an Undo context is entered, all subsequently added Undo actions are not pushed onto the undo stack directly, but considered a sub action of the Undo context. Once the Undo context is left, a single undo action is pushed onto the undo stack, which comprises all those single Undo actions.
Undo contexts can be arbitrarily nested.

Hidden Undo actions

Hidden Undo actions are those which in no observable way contribute to the undo stack. That is, any method retrieving information about the stack will behave as if the undo action does not exist. Nonetheless, calling undo() respectively redo() will include those actions.
Hidden Undo actions can be created by calling enterHiddenUndoContext(), following by leaveUndoContext().

Locking

An Undo manager can be locked and unlocked, using the XLockable::lock() and XLockable::unlock() methods. When it is locked, then every attempt to add an undo action, or to enter or leave an Undo context, will be silently ignored.

Since: OOo 3.4

Exported Interfaces

◆ ::com::sun::star::container::XChild

interface ::com::sun::star::container::XChild

allows accessing the component, usually a document, which the undo manager works for.

com::sun::star::container::XChild::setParent() is not supported, and will throw a com::sun::star::lang::NoSupportException.

◆ ::com::sun::star::util::XLockable

interface ::com::sun::star::util::XLockable

allows locking the undo manager.

Member Function Documentation

◆ addUndoAction()

void addUndoAction	(	[in] XUndoAction	iAction	)
raises	(	::com::sun::star::lang::IllegalArgumentException
	)

adds the given undo action to the undo stack.

The redo stack is cleared when a new action is pushed onto the undo stack.

The Undo manager takes ownership of any actions pushed onto the undo stack. This means that if the action is finally removed from the Undo manager's control (e.g. by calling clear() resp. clearRedo()), it will be disposed, as long as it supports the com::sun::star::lang::XComponent interface.

If the Undo manager is locked at the moment the method is called, the call will be ignored, and the undo action will immediately be disposed, if applicable.

Exceptions

com::sun::star::lang::IllegalArgumentException if the given undo action is NULL.

◆ addUndoManagerListener()

void addUndoManagerListener ( [in] XUndoManagerListener iListener )

adds a listener to be notified of changes in the Undo/Redo stacks.

◆ clear()

void clear	(		)
raises	(	::com::sun::star::document::UndoContextNotClosedException
	)

clears the undo and the redo stack.

All actions will be removed from both the Undo and the Redo stack. Actions which implement the com::sun::star::lang::XComponent interface will be disposed.

Exceptions

UndoContextNotClosedException if the method is invoked while an undo context is still open

◆ clearRedo()

void clearRedo	(		)
raises	(	::com::sun::star::document::UndoContextNotClosedException
	)

clears the redo stack.

All actions will be removed from the Redo stack. Actions which implement the com::sun::star::lang::XComponent interface will be disposed.

Exceptions

UndoContextNotClosedException if the method is invoked while an undo context is still open

◆ enterHiddenUndoContext()

void enterHiddenUndoContext	(		)
raises	(	EmptyUndoStackException
	)

enters a new undo context, creating a hidden undo action.

A hidden undo action does not, in any visible way, contribute to the undo stack. This means that

Calling undo() when the top-element is a hidden undo action will transparently undo this action, and also undo the new top element of the stack.
Calling redo() when the top-element is a hidden action will transparently redo this action, and also redo the new top element of the stack.
In any user interface presenting the current Undo or Redo actions to the user, a hidden action will not be listed.

A new undo action will be added to the undo stack. As long as the context is not left, every undo action added to the stack will be treated as sub action. This means it will not be directly accessible at the undo manager, not appear in any user interface, and cannot be separately undone or re-done.

Each call to enterHiddenUndoContext must be paired by a call to leaveUndoContext(), otherwise, the document's undo stack is left in an inconsistent state.

Undo contexts can be nested, i.e. it is legitimate to call enterUndoContext() and enterHiddenUndoContext multiple times without calling leaveUndoContext() inbetween.

Exceptions

EmptyUndoStackException if the undo stack is currently empty, in which case it is impossible to push a hidden undo action onto it.

See also: enterUndoContext; leaveUndoContext

◆ enterUndoContext()

void enterUndoContext ( [in] string iTitle )

enters a new undo context.

A new undo action will be added to the undo stack, with the title given as iTitle. As long as the context is not left, every undo action added to the stack will be treated as sub action. This means it will not be directly accessible at the Undo manager, not appear in any user interface, and cannot be separately undone or re-done.

Each call to enterUndoContext must be paired by a call to leaveUndoContext(), otherwise, the document's undo stack is left in an inconsistent state.

Undo contexts can be nested, i.e. it is legitimate to call enterUndoContext and enterHiddenUndoContext() multiple times without calling leaveUndoContext() inbetween.

See also: leaveUndoContext

◆ getAllRedoActionTitles()

sequence< string > getAllRedoActionTitles ( )

returns the titles of all actions currently on the Redo stack, from top to bottom

See also: XUndoAction::Title

◆ getAllUndoActionTitles()

sequence< string > getAllUndoActionTitles ( )

returns the titles of all actions currently on the undo stack, from top to bottom

See also: XUndoAction::Title

◆ getCurrentRedoActionTitle()

string getCurrentRedoActionTitle	(		)
raises	(	::com::sun::star::document::EmptyUndoStackException
	)

returns the title of the top-most action on the Redo stack

Exceptions

EmptyUndoStackException when the Redo stack is currently empty

See also: XUndoAction::Title

◆ getCurrentUndoActionTitle()

string getCurrentUndoActionTitle	(		)
raises	(	::com::sun::star::document::EmptyUndoStackException
	)

returns the title of the top-most action on the undo stack

Exceptions

EmptyUndoStackException when the undo stack is currently empty

See also: XUndoAction::Title

◆ isRedoPossible()

boolean isRedoPossible ( )

determines whether redo() can reasonably be expected to succeed.

Returns: FALSE if and only if the redo stack is currently empty, or there is an open and not-yet-closed undo context.

◆ isUndoPossible()

boolean isUndoPossible ( )

determines whether undo() can reasonably be expected to succeed.

Returns: FALSE if and only if the undo stack is currently empty, or there is an open and not-yet-closed undo context.

◆ leaveUndoContext()

void leaveUndoContext	(		)
raises	(	::com::sun::star::util::InvalidStateException
	)

leaves the undo context previously opened via enterUndoContext() respectively enterHiddenUndoContext().

If no undo action has been added since the context has been opened, the context is not only left, but silently removed, and does not contribute to the undo stack at all. In this case, possible listeners will be notified via XUndoManagerListener::cancelledContext().

Otherwise, the undo context will be closed, and added to the Undo stack; the redo stack will be cleared, and listeners will be notified via XUndoManagerListener::leftContext() resp. XUndoManagerListener::leftHiddenContext()

Exceptions

com::sun::star::util::InvalidStateException if no undo context is currently open.

See also: enterUndoContext; enterHiddenUndoContext

◆ redo()

void redo	(		)
raises	(	::com::sun::star::document::EmptyUndoStackException,
		::com::sun::star::document::UndoContextNotClosedException,
		::com::sun::star::document::UndoFailedException
	)

replays the action on the document which has most recently been undone

Effectively, invoking this method will

invoke XUndoAction::redo() on the top-most action of the redo stack
move this action from the redo stack to the undo stack

Exceptions

EmptyUndoStackException	when the Redo stack is currently empty
UndoContextNotClosedException	if there currently is an open undo context
UndoFailedException	if the invocation of XUndoAction::redo() raised this exception. In this case, the redo stack of the undo manager will have been cleared.

See also: undo

◆ removeUndoManagerListener()

void removeUndoManagerListener ( [in] XUndoManagerListener iListener )

removes a previously added listener

◆ reset()

void reset ( )

resets the Undo manager

In particular, this method will

remove all locks from the undo manager
close all open undo contexts
clear the undo stack
clear the redo stack

Note that possible listeners will not get notifications for the single parts of the reset, i.e. there will be no single XUndoManagerListener::allActionsCleared(), XUndoManagerListener::leftContext(), etc., notifications. Instead, listeners will be notified of the reset by calling their XUndoManagerListener::resetAll() method.

◆ undo()

void undo	(		)
raises	(	::com::sun::star::document::EmptyUndoStackException,
		::com::sun::star::document::UndoContextNotClosedException,
		::com::sun::star::document::UndoFailedException
	)

reverts the most recent action on the document.

Effectively, invoking this method will

invoke XUndoAction::undo() on the top-most action of the undo stack
move this undo action from the undo stack to the redo stack

Exceptions

EmptyUndoStackException	if the undo stack is currently empty
UndoContextNotClosedException	if there currently is an open undo context
UndoFailedException	if the invocation of XUndoAction::undo() raised this exception. In this case, the undo stack of the undo manager will have been cleared.

See also: redo; enterUndoContext

The documentation for this interface was generated from the following file:

com/sun/star/document/XUndoManager.idl

Exported Interfaces

Public Member Functions

Detailed Description

Undo

Redo

Undo contexts

Hidden Undo actions

Locking

Exported Interfaces

◆ ::com::sun::star::container::XChild

◆ ::com::sun::star::util::XLockable

Member Function Documentation

◆ addUndoAction()

◆ addUndoManagerListener()

◆ clear()

◆ clearRedo()

◆ enterHiddenUndoContext()

◆ enterUndoContext()

◆ getAllRedoActionTitles()

◆ getAllUndoActionTitles()

◆ getCurrentRedoActionTitle()

◆ getCurrentUndoActionTitle()

◆ isRedoPossible()

◆ isUndoPossible()

◆ leaveUndoContext()

◆ redo()

◆ removeUndoManagerListener()

◆ reset()

◆ undo()