undoapi: first sketch of the listener API - not sure this will survive 'til the final version

4 files changed, 195 insertions, 3 deletions

diff --git a/offapi/com/sun/star/document/UndoManagerEvent.idl b/offapi/com/sun/star/document/UndoManagerEvent.idl
new file mode 100755
index 000000000000..a95c0707ba33
--- /dev/null
+++ b/offapi/com/sun/star/document/UndoManagerEvent.idl
@@ -0,0 +1,63 @@
+/*************************************************************************
+ * 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
+ * <http://www.openoffice.org/license.html>
+ * for a copy of the LGPLv3 License.
+ *
+ ************************************************************************/
+
+#ifndef __com_sun_star_document_UndoManagerEvent_idl__
+#define __com_sun_star_document_UndoManagerEvent_idl__
+
+#include <com/sun/star/lang/EventObject.idl>
+
+//==================================================================================================================
+
+module com { module sun { module star { module document {
+
+//==================================================================================================================
+
+/** is an event sent by an <type>XUndoManager</type> implementation when the Undo/Redo stacks of the manager are
+    modified.
+    @see XUndoManager
+    @see XUndoManagerListener
+    @see XUndoAction
+ */
+struct UndoManagerEvent : ::com::sun::star::lang::EventObject
+{
+    /** the title of the Undo action which is described by the event
+        @see XUndoAction::Title
+    */
+    string  UndoActionTitle;
+
+    /** denotes the number of Undo contexts which are open, and not yet closed, at the time the event is fired.
+        @see XUndoManager::enterUndoContext
+    */
+    long    UndoContextDepth;
+};
+
+//==================================================================================================================
+
+}; }; }; };
+
+//==================================================================================================================
+
+#endif
diff --git a/offapi/com/sun/star/document/XUndoManager.idl b/offapi/com/sun/star/document/XUndoManager.idl
index d69b211f2f90..b937aa538e7a 100755
--- a/offapi/com/sun/star/document/XUndoManager.idl
+++ b/offapi/com/sun/star/document/XUndoManager.idl
@@ -29,12 +29,14 @@
 
 #include <com/sun/star/util/InvalidStateException.idl>
 #include <com/sun/star/lang/IllegalArgumentException.idl>
+#include <com/sun/star/lang/WrappedTargetException.idl>
 
 //==================================================================================================================
 
 module com { module sun { module star { module document {
 
 interface XUndoAction;
+interface XUndoManagerListener;
 
 //==================================================================================================================
 
@@ -133,8 +135,11 @@ interface XUndoManager
         <p>If one or more undo contexts are currently open, those will be implicit
 
         @see redo
+        @throws ::com::sun::star::lang::WrappedTargetException
+            if the invocation of <member>XUndoAction::undo</member> raises an exception other than a <member scope="com::sun::star::uno">RuntimeException</member>
     */
-    void    undo();
+    void    undo()
+            raises( ::com::sun::star::lang::WrappedTargetException );
 
     /** replays the action on the document which has most recently been undone
 
@@ -145,8 +150,11 @@ interface XUndoManager
         </ul></p>
 
         @see undo
+        @throws ::com::sun::star::lang::WrappedTargetException
+            if the invocation of <member>XUndoAction::redo</member> raises an exception other than a <member scope="com::sun::star::uno">RuntimeException</member>
     */
-    void    redo();
+    void    redo()
+            raises( ::com::sun::star::lang::WrappedTargetException );
 
     /** clears the undo and the redo stack.
     */
@@ -155,6 +163,18 @@ interface XUndoManager
     /** clears the redo stack.
     */
     void    clearRedo();
+
+    /** adds a listener to be notified of changes in the Undo/Redo stacks.
+    */
+    void    addUndoManagerListener(
+                [in] XUndoManagerListener i_listener
+            );
+
+    /** removes a previously added listener
+    */
+    void    removeUndoManagerListener(
+                [in] XUndoManagerListener i_listener
+            );
 };
 
 //==================================================================================================================
diff --git a/offapi/com/sun/star/document/XUndoManagerListener.idl b/offapi/com/sun/star/document/XUndoManagerListener.idl
new file mode 100755
index 000000000000..281b3911f65c
--- /dev/null
+++ b/offapi/com/sun/star/document/XUndoManagerListener.idl
@@ -0,0 +1,107 @@
+/*************************************************************************
+ * 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
+ * <http://www.openoffice.org/license.html>
+ * for a copy of the LGPLv3 License.
+ *
+ ************************************************************************/
+
+#ifndef __com_sun_star_document_XUndoManagerListener_idl__
+#define __com_sun_star_document_XUndoManagerListener_idl__
+
+#include <com/sun/star/document/UndoManagerEvent.idl>
+
+//==================================================================================================================
+
+module com { module sun { module star { module document {
+
+//==================================================================================================================
+
+/** implemented by components which want to be notified of changes in the Undo/Redo stacks of an Undo manager.
+
+    @see XUndoManager
+ */
+interface XUndoManagerListener
+{
+    /** is called when an Undo action is added to the Undo stack.
+
+        <p>Note that the action must not necessarily be the new top element of the stack: In case there's an
+        open Undo context, <member>UndoManagerEvent::UndoContextDepth</member> will be greater <code>0</code>,
+        and the newly added action will be subordinate of the context action.</p>
+    */
+    void    undoActionAdded( [in] UndoManagerEvent i_event );
+
+    /** is called when the top-most action of the Undo stack has been undone.
+    */
+    void    actionUndone( [in] UndoManagerEvent i_event );
+
+    /** is called when the top-most action of the Redo stack has been redone.
+    */
+    void    actionRedone( [in] UndoManagerEvent i_event );
+
+    /** is called when both the Undo and the Redo stack have been cleared from all Undo actions.
+        @see XUndoManager::clear
+    */
+    void    allActionsCleared( [in] ::com::sun::star::lang::EventObject i_event );
+
+    /** is called when the the Redo stack has been cleared.
+        @see XUndoManager::clearRedo
+    */
+    void    redoActionsCleared( [in] ::com::sun::star::lang::EventObject i_event );
+
+    /** is called when a new Undo context has been entered.
+
+        <p><member>UndoManagerEvent::UndoActionTitle</member> carries the title of the Undo context, and
+        <member>UndoManagerEvent::UndoContextDepth</member> the number of open Undo contexts, including the
+        one just entered.</p>
+
+        @see XUndoManager::enterUndoContext
+    */
+    void    enteredUndoContext( [in] UndoManagerEvent i_event );
+
+    /** is called when a new hidden Undo context has been entered.
+
+        <p><member>UndoManagerEvent::UndoActionTitle</member> carries the title of the Undo context, and
+        <member>UndoManagerEvent::UndoContextDepth</member> the number of open Undo contexts, including the
+        one just entered.</p>
+
+        @see XUndoManager::enterUndoContext
+    */
+    void    enteredHiddenUndoContext( [in] UndoManagerEvent i_event );
+
+    /** is called when a new Undo context has been entered.
+
+        <p><member>UndoManagerEvent::UndoActionTitle</member> carries the title of the Undo context, and
+        <member>UndoManagerEvent::UndoContextDepth</member> the number of open Undo contexts, exluding the
+        one just left.</p>
+
+        @see XUndoManager::leaveUndoContext
+    */
+    void    leftUndoContext( [in] UndoManagerEvent i_event );
+};
+
+//==================================================================================================================
+
+}; }; }; };
+
+//==================================================================================================================
+
+#endif
diff --git a/offapi/com/sun/star/document/makefile.mk b/offapi/com/sun/star/document/makefile.mk
index f705df150929..3a426123f1bf 100644
--- a/offapi/com/sun/star/document/makefile.mk
+++ b/offapi/com/sun/star/document/makefile.mk
@@ -117,7 +117,9 @@ IDLFILES=\
     XCodeNameQuery.idl \
     XUndoAction.idl \
     XUndoManager.idl \
-    XUndoManagerSupplier.idl
+    XUndoManagerListener.idl \
+    XUndoManagerSupplier.idl \
+    UndoManagerEvent.idl
 
 
 # ------------------------------------------------------------------