Show
Ignore:
Timestamp:
08/01/07 00:35:21 (1 year ago)
Author:
arj..@yirdis.nl
Message:

updated (rst'ed) txt files.

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • gaphas/trunk/state.txt

    r1716 r1803  
    77The state system consists of two parts: 
    88 
    9  1. A basic observer (the @observed decorator) 
    10  2. A reverter 
     91. A basic observer (the ``@observed`` decorator) 
     102. A reverter 
     11 
     12.. contents:: 
    1113 
    1214Observer 
    1315-------- 
    1416 
    15 The observer simply dispatches the function called (as <function ..>, not as 
    16 <unbound method..>!) to each handler registered in an observers list. 
     17The observer simply dispatches the function called (as ``<function ..>``, not as 
     18``<unbound method..>``!) to each handler registered in an observers list. 
    1719 
    1820    >>> from gaphas import state 
    …… 
    5355    [] 
    5456 
    55 The @observed decorator can also be applied to properties, as is done in 
     57The ``@observed`` decorator can also be applied to properties, as is done in 
    5658gaphas/item.py's Handle class: 
    5759 
    …… 
    7274What should you know: 
    7375 
    74  1. The observer always generates events based on 'function' calls. Even for 
    75     class method invokations. This is because, when calling a method (say 
    76     Tree.add) it's the im_func field is executed, which is a function type 
    77     object. 
    78  
    79  2. It's important to know if an event came from invoking a method or a simple 
    80     function. With methods, the first argument always is an instance. This can 
    81     be handy when writing an undo management systems in case multiple calls 
    82     from the same instance do not have to be registered (e.g. if a method 
    83     set_point() is called with exact coordinates (in stead of deltas), only the 
    84     first call to set_point needs to be remembered. 
     761. The observer always generates events based on 'function' calls. Even for 
     77   class method invokations. This is because, when calling a method (say 
     78   Tree.add) it's the im_func field is executed, which is a function type 
     79   object. 
     80 
     812. It's important to know if an event came from invoking a method or a simple 
     82   function. With methods, the first argument always is an instance. This can 
     83   be handy when writing an undo management systems in case multiple calls 
     84   from the same instance do not have to be registered (e.g. if a method 
     85   set_point() is called with exact coordinates (in stead of deltas), only the 
     86   first call to set_point needs to be remembered. 
    8587 
    8688 
    …… 
    9092The reverser requires some registration. 
    9193 
    92  1. Property setters should be declared with reversible_property() 
    93  2. Method (or function) pairs that implement each others reverse operation 
    94     (e.g. add and remove) should be registered as reversible_pair()'s in the 
    95     reverser engine. 
    96     The reverser will construct a tuple (callable, arguments) which are send 
    97     to every handler registered in the subscribers list. Arguments is a dict(). 
    98  
    99 First thing to do is to actually enable the revert_handler: 
     941. Property setters should be declared with reversible_property() 
     952. Method (or function) pairs that implement each others reverse operation 
     96   (e.g. add and remove) should be registered as reversible_pair()'s in the 
     97   reverser engine. 
     98   The reverser will construct a tuple (callable, arguments) which are send 
     99   to every handler registered in the subscribers list. Arguments is a dict(). 
     100 
     101First thing to do is to actually enable the ``revert_handler``: 
    100102 
    101103    >>> state.observers.add(state.revert_handler) 
    102104 
    103105This handler is not enabled by default because: 
    104  1. it generates quite a bit of overhead if it isn't used anyway 
    105  2. you might want to add some additional filtering. 
     106 
     1071. it generates quite a bit of overhead if it isn't used anyway 
     1082. you might want to add some additional filtering. 
    106109 
    107110Point 2 may require some explanation. First of all observers have been added 
    …… 
    129132applied to that function. 
    130133 
    131 The inverse operation is easiest performed by the function saveapply(). Of course 
    132 an inverse operation is emitting a change event too: 
     134The inverse operation is easiest performed by the function saveapply(). Of 
     135course an inverse operation is emitting a change event too: 
    133136 
    134137    >>> state.saveapply(*events.pop())                  # doctest: +ELLIPSIS 
    …… 
    155158    >>> state.observers.remove(state.revert_handler) 
    156159 
    157 TODO 
    158 ---- 
    159  
    160 Function wrappers should have an extra property indicating if a function needs 
    161 to be dispatched or not. If it needs to be dispatched an extra flag should be 
    162 set. This will prevent the system from slowing down due to emitting signals that 
    163 are filtered out later on. 
    164  
    165160What is Observed  
    166161---------------- 
    …… 
    170165to monitor the Matrix class (which is from Cairo). 
    171166 
    172  canvas.py: 
    173   Canvas: 
    174     add() and remove() 
    175  
    176  item.py: 
    177   Handle: 
    178     x, y, connectable, movable, visible, connected_to and disconnect properties 
    179   Item: 
    180     canvas and matrix properties 
    181   Element: 
    182     min_height and min_width properties 
    183   Line: 
    184     line_width, fuzziness, orthogonal and horizontal properties; 
    185     split_segment() and merge_segment() 
    186  
    187  solver.py: 
    188   Variable: 
    189     strength and value properties 
    190   Solver: 
    191     add_constraint() and remove_constraint()  
    192  
    193  tree.py: 
    194   Tree: 
    195     add() and remove() 
    196  
    197  matrix.py: 
    198   Matrix: 
    199     invert, translate, rotate and scale 
     167canvas.py: 
     168  Canvas: 
     169    add() and remove() 
     170 
     171item.py: 
     172  Handle: 
     173    x, y, connectable, movable, visible, connected_to and disconnect properties 
     174  Item: 
     175    canvas and matrix properties 
     176  Element: 
     177    min_height and min_width properties 
     178  Line: 
     179    line_width, fuzziness, orthogonal and horizontal properties; 
     180    split_segment() and merge_segment() 
     181 
     182solver.py: 
     183  Variable: 
     184    strength and value properties 
     185  Solver: 
     186    add_constraint() and remove_constraint()  
     187 
     188tree.py: 
     189  Tree: 
     190    add() and remove() 
     191 
     192matrix.py: 
     193  Matrix: 
     194   invert, translate, rotate and scale 
    200195 
    201196Testcases are described in undo.txt.