From 0658bb205ab9da692e1f73199e92ca40003e27af Mon Sep 17 00:00:00 2001 From: "Frank Schoenheit [fs]" Date: Thu, 14 Oct 2010 16:40:29 +0200 Subject: undoapi: initial version of an UNO Undo API, implemented empty for SFX-based documents --- offapi/com/sun/star/document/XUndoAction.idl | 59 ++++++++ offapi/com/sun/star/document/XUndoManager.idl | 161 +++++++++++++++++++++ .../com/sun/star/document/XUndoManagerSupplier.idl | 53 +++++++ offapi/com/sun/star/document/makefile.mk | 5 +- 4 files changed, 277 insertions(+), 1 deletion(-) create mode 100755 offapi/com/sun/star/document/XUndoAction.idl create mode 100755 offapi/com/sun/star/document/XUndoManager.idl create mode 100755 offapi/com/sun/star/document/XUndoManagerSupplier.idl (limited to 'offapi/com/sun/star/document') diff --git a/offapi/com/sun/star/document/XUndoAction.idl b/offapi/com/sun/star/document/XUndoAction.idl new file mode 100755 index 000000000000..e844f527fceb --- /dev/null +++ b/offapi/com/sun/star/document/XUndoAction.idl @@ -0,0 +1,59 @@ +/************************************************************************* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright 2000, 2010 Oracle and/or its affiliates. + * + * OpenOffice.org - a multi-platform office productivity suite + * + * This file is part of OpenOffice.org. + * + * OpenOffice.org is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License version 3 + * only, as published by the Free Software Foundation. + * + * OpenOffice.org is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License version 3 for more details + * (a copy is included in the LICENSE file that accompanied this code). + * + * You should have received a copy of the GNU Lesser General Public License + * version 3 along with OpenOffice.org. If not, see + * + * for a copy of the LGPLv3 License. + * + ************************************************************************/ + +#ifndef __com_sun_star_document_XUndoAction_idl__ +#define __com_sun_star_document_XUndoAction_idl__ + +//================================================================================================================== + +module com { module sun { module star { module document { + +//================================================================================================================== + +/** represents a single (undoable) action on a document + */ +interface XUndoAction +{ + /** reverts the action represented by the instance + */ + void undo(); + + /** repeats the action represented by the instance, after it had previously been reverted. + */ + void redo(); + + /** is the human-readable, localized description of the action. + */ + [attribute, readonly] string Title; +}; + +//================================================================================================================== + +}; }; }; }; + +//================================================================================================================== + +#endif diff --git a/offapi/com/sun/star/document/XUndoManager.idl b/offapi/com/sun/star/document/XUndoManager.idl new file mode 100755 index 000000000000..9ad65e4f4e82 --- /dev/null +++ b/offapi/com/sun/star/document/XUndoManager.idl @@ -0,0 +1,161 @@ +/************************************************************************* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright 2000, 2010 Oracle and/or its affiliates. + * + * OpenOffice.org - a multi-platform office productivity suite + * + * This file is part of OpenOffice.org. + * + * OpenOffice.org is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License version 3 + * only, as published by the Free Software Foundation. + * + * OpenOffice.org is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License version 3 for more details + * (a copy is included in the LICENSE file that accompanied this code). + * + * You should have received a copy of the GNU Lesser General Public License + * version 3 along with OpenOffice.org. If not, see + * + * for a copy of the LGPLv3 License. + * + ************************************************************************/ + +#ifndef __com_sun_star_document_XUndoManager_idl__ +#define __com_sun_star_document_XUndoManager_idl__ + +#include + +//================================================================================================================== + +module com { module sun { module star { module document { + +interface XUndoAction; + +//================================================================================================================== + +/** provides access to the undo/redo stacks of the document + */ +interface XUndoManager +{ + /** enters a new undo context. + +

A new undo action will be added to the undo stack, with the title given as i_title. 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 leaveUndoContext + */ + void enterUndoContext( + [in] string i_title + ); + + /** 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.

+ + @throws ::com::sun::star::util::InvalidStateException + if the Undo stack is currently empty, in which case it is impossible to push a hidden Undo action onto + it. + + @see emterUndoContext + @see leaveUndoContext + */ + void enterHiddenUndoContext() + raises( ::com::sun::star::util::InvalidStateException ); + + /** leaves the undo context previously opened via enterUndoContext respectively + enterHiddenUndoContext. + + @throws ::com::sun::star::util::InvalidStateException + if no undo context is currently open. + + @see enterUndoContext + @see enterHiddenUndoContext + */ + void leaveUndoContext() + raises( ::com::sun::star::util::InvalidStateException ); + + /** 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 XComponent + interface.

+ */ + void addUndoAction( + [in] XUndoAction i_action + ); + + /** reverts the most recent action on the document. + +

Effectively, invoking this method will +

  • close any undo contexts which are currently open

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

+ +

If one or more undo contexts are currently open, those will be implicit + + @see redo + */ + void undo(); + + /** replays the action on the document which has most recently been undone + +

Effectively, invoking this method will +

  • close any undo contexts which are currently open

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

+ + @see undo + */ + void redo(); + + /** clears the undo and the redo stack. + */ + void clear(); + + /** clears the redo stack. + */ + void clearRedo(); +}; + +//================================================================================================================== + +}; }; }; }; + +//================================================================================================================== + +#endif diff --git a/offapi/com/sun/star/document/XUndoManagerSupplier.idl b/offapi/com/sun/star/document/XUndoManagerSupplier.idl new file mode 100755 index 000000000000..14b345e44126 --- /dev/null +++ b/offapi/com/sun/star/document/XUndoManagerSupplier.idl @@ -0,0 +1,53 @@ +/************************************************************************* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright 2000, 2010 Oracle and/or its affiliates. + * + * OpenOffice.org - a multi-platform office productivity suite + * + * This file is part of OpenOffice.org. + * + * OpenOffice.org is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License version 3 + * only, as published by the Free Software Foundation. + * + * OpenOffice.org is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License version 3 for more details + * (a copy is included in the LICENSE file that accompanied this code). + * + * You should have received a copy of the GNU Lesser General Public License + * version 3 along with OpenOffice.org. If not, see + * + * for a copy of the LGPLv3 License. + * + ************************************************************************/ + +#ifndef __com_sun_star_document_XUndoManagerSupplier_idl__ +#define __com_sun_star_document_XUndoManagerSupplier_idl__ + +//================================================================================================================== + +module com { module sun { module star { module document { + +interface XUndoManager; + +//================================================================================================================== + +/** provides access to an XUndoManager. + */ +interface XUndoManagerSupplier +{ + /** returns the Undo manager associated with the component. + */ + XUndoManager getUndoManager(); +}; + +//================================================================================================================== + +}; }; }; }; + +//================================================================================================================== + +#endif diff --git a/offapi/com/sun/star/document/makefile.mk b/offapi/com/sun/star/document/makefile.mk index 48394a65008c..f705df150929 100644 --- a/offapi/com/sun/star/document/makefile.mk +++ b/offapi/com/sun/star/document/makefile.mk @@ -114,7 +114,10 @@ IDLFILES=\ XDocumentRevisionListPersistence.idl\ DocumentRevisionListPersistence.idl \ XDocumentLanguages.idl \ - XCodeNameQuery.idl + XCodeNameQuery.idl \ + XUndoAction.idl \ + XUndoManager.idl \ + XUndoManagerSupplier.idl # ------------------------------------------------------------------ -- cgit