Changes between Version 2 and Version 3 of HemlockProgrammer/Utilities


Ignore:
Timestamp:
01/28/08 23:06:54 (7 years ago)
Author:
gz
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • HemlockProgrammer/Utilities

    v2 v3  
    189189element. A negative offset rotates the ring the other way. 
    190190 
    191 == 16.3 Undoing commands ==#UndoingCommands 
     191== 16.3. Undoing commands ==#UndoingCommands 
    192192 
    193 `save-for-undo`         name method &optional cleanup method-undo buffer         [Function] 
    194                  
    195 This saves information to undo a command. Name is a string to display 
    196 when prompting the user for confirmation when he invokes the Undo 
    197 command (for example, "kill" or "Fill Paragraph"). Method is the 
    198 function to invoke to undo the effect of the command. Method-undo is a 
    199 function that undoes the undo function, or effectively re-establishes 
    200 the state immediately after invoking the command. If there is any 
    201 existing undo information, this invokes the cleanup function; 
    202 typically method closes over or uses permanent marks into a buffer, 
    203 and the cleanup function should delete such references. Buffer 
    204 defaults to the current-buffer, and the Undo command only invokes undo 
    205 methods when they were saved for the buffer that is current when the 
    206 user invokes Undo. 
    207  
    208  
    209  
    210 `make-region-undo`      kind name region &optional mark-or-region        [Function] 
    211                  
    212 This handles three common cases that commands fall into when setting 
    213 up undo methods, including cleanup and method-undo functions (see 
    214 save-for-undo). These cases are indicated by the kind argument: 
    215  
    216  :twiddle:: 
    217  Use this kind when a command modifies a region, and the undo 
    218  information indicates how to swap between two regions -- the one 
    219  before any modification occurs and the resulting region. Region is 
    220  the resulting region, and it has permanent marks into the 
    221  buffer. Mark-or-region is a region without marks into the buffer (for 
    222  example, the result of copy-region). As a result of calling this, a 
    223  first invocation of Undo deletes region, saving it, and inserts 
    224  mark-or-region where region used to be. The undo method sets up for a 
    225  second invocation of Undo that will undo the effect of the undo; that 
    226  is, after two calls, the buffer is exactly as it was after invoking 
    227  the command. This activity is repeatable any number of times. This 
    228  establishes a cleanup method that deletes the two permanent marks 
    229  into the buffer used to locate the modified region. 
    230  
    231  :insert:: 
    232  Use this kind when a command has deleted a region, and the undo 
    233  information indicates how to re-insert the region. Region is the 
    234  deleted and saved region, and it does not contain marks into any 
    235  buffer. Mark-or-region is a permanent mark into the buffer where the 
    236  undo method should insert region. As a result of calling this, a 
    237  first invocation of Undo inserts region at mark-or-region and forms a 
    238  region around the inserted text with permanent marks into the 
    239  buffer. This allows a second invocation of Undo to undo the effect of 
    240  the undo; that is, after two calls, the buffer is exactly as it was 
    241  after invoking the command. This activity is repeatable any number of 
    242  times. This establishes a cleanup method that deletes either the 
    243  permanent mark into the buffer or the two permanent marks of the 
    244  region, depending on how many times the user used Undo. 
    245  
    246  :delete:: 
    247  Use this kind when a command has inserted a block of text, and the 
    248  undo information indicates how to delete the region. Region has 
    249  permanent marks into the buffer and surrounds the inserted 
    250  text. Leave Mark-or-region unspecified. As a result of calling this, 
    251  a first invocation of Undo deletes region, saving it, and establishes 
    252  a permanent mark into the buffer to remember where the region 
    253  was. This allows a second invocation of Undo to undo the effect of 
    254  the undo; that is, after two calls, the buffer is exactly as it was 
    255  after invoking the command. This activity is repeatable any number of 
    256  times. This establishes a cleanup method that deletes either the 
    257  permanent mark into the buffer or the two permanent marks of the 
    258  region, depending on how many times the user used Undo. 
    259  
    260 Name in all cases is an appropriate string indicating what the command 
    261 did. This is used by Undo when prompting the user for confirmation 
    262 before calling the undo method. The string used by Undo alternates 
    263 between this argument and something to indicate that the user is 
    264 undoing an undo. 
    265  
     193No API to the undo facility is provided at this time. 
    266194 
    267195