Show
Ignore:
Timestamp:
04/09/07 23:15:35 (2 years ago)
Author:
arj..@yirdis.nl
Message:

New version tag: 0.10.2

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • gaphor/trunk/doc/undo.txt

    r1142 r1202  
    5353    Variable state 
    5454 
    55   In Gaphor, connecting two diagram items is considered an atomic task, 
    56   performed by a IConnect adapter. This operation results in a set of primitive 
    57   tasks (properties set and a constraint created). 
     55In Gaphor, connecting two diagram items is considered an atomic task, 
     56performed by a IConnect adapter. This operation results in a set of primitive 
     57tasks (properties set and a constraint created). 
    5858 
    59   For methods, it should be possible to create a decorator (@reversable) that 
    60   schedules a method with the same signature as the calling operation, but with 
    61   the inverse effect (e.g. the gaphas.tree module): 
     59For methods, it should be possible to create a decorator (@reversible) that 
     60schedules a method with the same signature as the calling operation, but with 
     61the inverse effect (e.g. the gaphas.tree module): 
    6262 
    6363  Tree(object): 
    …… 
    7171        ... remove 
    7272 
    73  Okay, so the second case is toucher... 
     73Okay, so the second case is tougher... 
    7474  
    7575  
    76 We have three options: 
    77  
    78  1. Add a StateManager to gaphas. All changed are send to the statemanager. 
    79     Gaphor should implement it's own state manager. 
    80      + all state changes can easely be recorded 
    81      + fix it in one place 
    82      + reusable thoughout Gaphas and subtypes. 
    83      ? does this solve undo-problems for other applications too? 
    84  
    85  2. Override all attrs and properties, decorate the method from a special 
    86     update script at runtime. 
    87      + keeps Gaphas' code clean, less complicated 
    88      - it's not clear what happens 
    89      - users require some sort of state recording/undo mechanism anyway 
    90  
    91  3. Why not use Tools? 
    92      - Lot's of interaction can be achieved though menu items or other 
    93        programmatic actions. 
     76So what we did: 
     77Add a StateManager to gaphas. All changed are send to the statemanager. 
     78Gaphor should implement it's own state manager. 
     79  + all state changes can easily be recorded 
     80  + fix it in one place 
     81  + reusable throughout Gaphas and subtypes. 
    9482 
    9583 
    96 References: 
     84Transactions 
     85============ 
     86 
     87Gaphor's Undo manager works transactional. Typically, methods can be  
     88decorated with @transactional and undo data is stored in the current 
     89transaction. A new tx is created when none exists. 
     90 
     91Although undo functionality is at the core of Gaphor (diagram items and 
     92model elements have been adapted to provide proper undo information), the  
     93UndoManager itself is just a service. 
     94 
     95Transaction support though is a real core functionality. By letting elements 
     96and items emit event notifications on important changed other (yet to be 
     97defined) services can take benefit of those events. The UML module already 
     98works this way. Gaphas (the Gaphor canvas) also emits state changes.  
     99 
     100When state changes happen in model elements and diagram items an event is 
     101emitted. Those events are handled by special handlers that produce 
     102"reverse-events". Reverse events are functions that perform exactly the 
     103opposite operation. Those functions are stored in a list (which technically is 
     104the Transaction). When an undo request is done the list is executed in LIFO 
     105order. 
     106 
     107To start a transaction: 
     108 
     109  1. A Transaction object has been created. 
     110  2. This results in the emission of a TransactionBegin event. 
     111  3. The TransactionBegin event is a trigger for the UndoManager to start 
     112     listening for IUndoEvent actions. 
     113 
     114Now, that should be done when a model element or diagram item sends a state 
     115change: 
     116 
     117  1. The event is handled by the "reverse-handler" 
     118  2. Reverse handler generates a IUndoEvent signal  
     119  3. The signal is received and stored as part of the undo-transaction. 
     120 
     121(Maybe step 2 and 3 can be merged, since only one function is not of any 
     122interest to the rest of the application - creates nasty dependencies) 
     123 
     124If nested transaction are created a simple counter is incremented. 
     125 
     126When the topmost Transaction is committed: 
     127 
     128  1. A TransactionCommit event is emitted 
     129  2. This triggers the UndoManager to close and store the transaction. 
     130 
     131When a transaction is rolled back: 
     132  
     133  1. The main transaction is marked for rollback 
     134  2. When the toplevel tx is rolled back or commited a 
     135     TransactionRollback event is emitted 
     136  2. This triggers the UndoManager to play back all recorded actions and 
     137     stop listening. 
     138 
     139 
     140References 
     141========== 
    97142 
    98143A Framework for Undoing Actions in Collaborative Systems