Re: Attempt for an UNO Undo API

Hi Frank,

after a first reading it sounds interesting and of course very useful. I
will take a closer look o the interfaces tomorrow if i can make it
before i go on vacation.

Juergen

On 10/4/10 12:27 PM, Frank Schönheit wrote:
> Hi,
> 
> An UNO Undo API has been a revenant in this list (and other places) for
> multiple years now.
> 
> Not sure if this year's attempt to exorcise (aka: implement) it will be
> more fruitful than previous ones, but let's see ...
> 
> The following are some thoughts I have on the topic, and assuming
> there's not too many people crying "that's complete nonsense", the plan
> is to embark on an implementation in a not too distant future.
> 
> Comments welcome.
> 
> Usage scenarios
> ===============
> 
> A. An extension operates on a document, doing multiple changes in a row.
>    All those changes should appear as a single entry in the "Undo" menu,
>    and be undone in a single step.
> 
> B. An extension listens for certain changes in a document, and reacts on
>    them with doing more changes to other parts of the document. The
>    latter change should not be visible in the Undo stack, and the Undo
>    action generated by the former change should implicitly also undo
>    the second change.
>    (Imagine the extension as ensuring a consistent state of the
>    document, with its own definition of "consistent".)
> 
> C. An extension listens for certain changes in a document, and reacts on
>    them with doing more changes to other parts of the document. When
>    both changes (the latter implicitly, the former explicitly) are
>    undone, the extension should have a chance to find out that the
>    change instigated by this Undo operation does not justify a new
>    change to the document.
> 
> D. An extension wants to add own Undo actions to the document's Undo
>    stack, providing a callback for the Undo/Redo operations.
> 
> Notes
> -----
> 
> Whenever the term "extension" is used in the above list, it could
> equally mean "every piece of client code which has UNO access to the
> document only".
> 
> API requirements
> ================
> 
> - entering/leaving an "Undo context" - all single Undo actions generated
>   within this context contribute to a single Undo action
> 
> - adding own undo actions to the Undo stack
> 
> - programmatic undo/redo of the top-most undo/redo action
> 
> - programmatic clearing of the Undo stack
> 
> - hiding Undo actions from the user
> 
> - determining whether an Undo/Redo operation is currently in progress
> 
> - Undo/Redo listeners
> 
> Notes
> -----
> 
> There's intentionally no direct access to the Undo actions on the stack,
> as this would widely open the door for all kind of intentional or
> accidental manipulation bypasing the Undo manager - something very hard
> to keep under control.
> 
> 
> The last two items on the list are intended to address scenario C.
> However, it is questionable whether this scenario can legitimately be
> supported without major changes to the application's core.
> 
> No matter whether an extension determines a running Undo action by
> calling some explicit "isUndoActive", or by tracing some
> "undoStarted/undoDone" notifications - if changes to the document are
> notified asynchronously, then this mechanism immediately stops working.
> So, as document change notifications are *usually* implemented
> synchronously, the mechanism *usually* would work - but is not
> guaranteed to do all the time.
> 
> Alternative approaches to address scenario C.:
> - Every document change notification must send with it a flag whether
>   the change is triggered by an Undo/Redo action.
>   This is quite illusionary, given the API and core changes it would
>   involve
> - All document change notifications are *required* to be synchronously.
> - All document change notifications are required to be asynchronously,
>   including the undoStarted/undoDone notifications. Also, all
>   notifications referring to a given document must be guaranteed to
>   arrive in-order at listeners.
> - Document changes triggered by Undo actions do not result in document
>   change listeners being called.
>   This would not be a good idea at all, since there might be listeners
>   which are nonetheless interested in document changes - not to make
>   depending changes to the document, but for other reasons.
>   As a refinement, only those listeners should be notified which have
>   those "other" motivations - but that's again something which would
>   require extensive changes to the existing API and core
>   implementations, as there currently is no way, not even a concept,
>   to distinguish those kinds of listeners (and it might be questionable
>   whether there really should).
> 
> So, not a single of these approaches is really satisfying. Which might
> imply we should not address scenario C. at all, assuming that the
> consequences are bearable.
> 
> API proposal
> ============
> 
> XUndoAction, XUndoManager, XUndoManagerSupplier - find the generated IDL
> for the proposed API at
> http://udk.openoffice.org/files/documents/23/4795/undo.zip
> 
> Ciao
> Frank
>