| 17 |
<o:DocumentProperties> |
<o:DocumentProperties> |
| 18 |
<o:Author>IBM_USER</o:Author> |
<o:Author>IBM_USER</o:Author> |
| 19 |
<o:LastAuthor>IBM_USER</o:LastAuthor> |
<o:LastAuthor>IBM_USER</o:LastAuthor> |
| 20 |
<o:Revision>2</o:Revision> |
<o:Revision>7</o:Revision> |
| 21 |
<o:TotalTime>4237</o:TotalTime> |
<o:TotalTime>4518</o:TotalTime> |
| 22 |
<o:LastPrinted>2004-11-08T17:14:00Z</o:LastPrinted> |
<o:LastPrinted>2004-11-08T17:14:00Z</o:LastPrinted> |
| 23 |
<o:Created>2004-11-09T19:14:00Z</o:Created> |
<o:Created>2004-12-20T21:30:00Z</o:Created> |
| 24 |
<o:LastSaved>2004-11-09T19:14:00Z</o:LastSaved> |
<o:LastSaved>2004-12-20T21:50:00Z</o:LastSaved> |
| 25 |
<o:Pages>1</o:Pages> |
<o:Pages>1</o:Pages> |
| 26 |
<o:Words>6221</o:Words> |
<o:Words>6341</o:Words> |
| 27 |
<o:Characters>35461</o:Characters> |
<o:Characters>36147</o:Characters> |
| 28 |
<o:Company>IBM</o:Company> |
<o:Company>IBM</o:Company> |
| 29 |
<o:Lines>295</o:Lines> |
<o:Lines>301</o:Lines> |
| 30 |
<o:Paragraphs>83</o:Paragraphs> |
<o:Paragraphs>84</o:Paragraphs> |
| 31 |
<o:CharactersWithSpaces>41599</o:CharactersWithSpaces> |
<o:CharactersWithSpaces>42404</o:CharactersWithSpaces> |
| 32 |
<o:Version>10.6626</o:Version> |
<o:Version>10.6626</o:Version> |
| 33 |
</o:DocumentProperties> |
</o:DocumentProperties> |
| 34 |
</xml><![endif]--><!--[if gte mso 9]><xml> |
</xml><![endif]--><!--[if gte mso 9]><xml> |
| 35 |
<w:WordDocument> |
<w:WordDocument> |
|
<w:SpellingState>Clean</w:SpellingState> |
|
| 36 |
<w:Compatibility> |
<w:Compatibility> |
| 37 |
<w:BreakWrappedTables/> |
<w:BreakWrappedTables/> |
| 38 |
<w:SnapToGridInCell/> |
<w:SnapToGridInCell/> |
| 152 |
{color:purple; |
{color:purple; |
| 153 |
text-decoration:underline; |
text-decoration:underline; |
| 154 |
text-underline:single;} |
text-underline:single;} |
| 155 |
span.SpellE |
code |
| 156 |
{mso-style-name:""; |
{font-family:"Courier New"; |
| 157 |
mso-spl-e:yes;} |
mso-ascii-font-family:"Courier New"; |
| 158 |
|
mso-fareast-font-family:"Times New Roman"; |
| 159 |
|
mso-hansi-font-family:"Courier New"; |
| 160 |
|
mso-bidi-font-family:"Courier New";} |
| 161 |
|
pre |
| 162 |
|
{margin:0in; |
| 163 |
|
margin-bottom:.0001pt; |
| 164 |
|
mso-pagination:widow-orphan; |
| 165 |
|
font-size:10.0pt; |
| 166 |
|
font-family:"Courier New"; |
| 167 |
|
mso-fareast-font-family:"Times New Roman";} |
| 168 |
@page Section1 |
@page Section1 |
| 169 |
{size:8.5in 11.0in; |
{size:8.5in 11.0in; |
| 170 |
margin:1.0in .75in .5in 1.0in; |
margin:1.0in .75in .5in 1.0in; |
| 175 |
{page:Section1;} |
{page:Section1;} |
| 176 |
/* List Definitions */ |
/* List Definitions */ |
| 177 |
@list l0 |
@list l0 |
| 178 |
{mso-list-id:-132; |
{mso-list-id:306130254; |
| 179 |
mso-list-type:simple; |
mso-list-template-ids:-1505884488;} |
|
mso-list-template-ids:-446383164;} |
|
| 180 |
@list l0:level1 |
@list l0:level1 |
|
{mso-level-tab-stop:1.25in; |
|
|
mso-level-number-position:left; |
|
|
margin-left:1.25in; |
|
|
text-indent:-.25in;} |
|
|
@list l1 |
|
|
{mso-list-id:-131; |
|
|
mso-list-type:simple; |
|
|
mso-list-template-ids:1534092348;} |
|
|
@list l1:level1 |
|
|
{mso-level-tab-stop:1.0in; |
|
|
mso-level-number-position:left; |
|
|
margin-left:1.0in; |
|
|
text-indent:-.25in;} |
|
|
@list l2 |
|
|
{mso-list-id:-130; |
|
|
mso-list-type:simple; |
|
|
mso-list-template-ids:710070486;} |
|
|
@list l2:level1 |
|
|
{mso-level-tab-stop:.75in; |
|
|
mso-level-number-position:left; |
|
|
margin-left:.75in; |
|
|
text-indent:-.25in;} |
|
|
@list l3 |
|
|
{mso-list-id:-129; |
|
|
mso-list-type:simple; |
|
|
mso-list-template-ids:682940366;} |
|
|
@list l3:level1 |
|
|
{mso-level-tab-stop:.5in; |
|
|
mso-level-number-position:left; |
|
|
text-indent:-.25in;} |
|
|
@list l4 |
|
|
{mso-list-id:-128; |
|
|
mso-list-type:simple; |
|
|
mso-list-template-ids:949130314;} |
|
|
@list l4:level1 |
|
| 181 |
{mso-level-number-format:bullet; |
{mso-level-number-format:bullet; |
| 182 |
mso-level-text:\F0B7; |
mso-level-text:\F0B7; |
| 183 |
mso-level-tab-stop:1.25in; |
mso-level-tab-stop:.5in; |
| 184 |
mso-level-number-position:left; |
mso-level-number-position:left; |
|
margin-left:1.25in; |
|
| 185 |
text-indent:-.25in; |
text-indent:-.25in; |
| 186 |
|
mso-ansi-font-size:10.0pt; |
| 187 |
font-family:Symbol;} |
font-family:Symbol;} |
| 188 |
@list l5 |
@list l1 |
| 189 |
{mso-list-id:-127; |
{mso-list-id:322004125; |
| 190 |
mso-list-type:simple; |
mso-list-template-ids:933166844;} |
| 191 |
mso-list-template-ids:-1842289842;} |
@list l2 |
| 192 |
@list l5:level1 |
{mso-list-id:347761159; |
| 193 |
|
mso-list-type:hybrid; |
| 194 |
|
mso-list-template-ids:-1680017606 67698689 67698691 67698693 67698689 67698691 67698693 67698689 67698691 67698693;} |
| 195 |
|
@list l2:level1 |
| 196 |
{mso-level-number-format:bullet; |
{mso-level-number-format:bullet; |
| 197 |
mso-level-text:\F0B7; |
mso-level-text:\F0B7; |
| 198 |
mso-level-tab-stop:1.0in; |
mso-level-tab-stop:.5in; |
| 199 |
mso-level-number-position:left; |
mso-level-number-position:left; |
|
margin-left:1.0in; |
|
| 200 |
text-indent:-.25in; |
text-indent:-.25in; |
| 201 |
font-family:Symbol;} |
font-family:Symbol;} |
| 202 |
@list l6 |
@list l2:level2 |
| 203 |
{mso-list-id:-126; |
{mso-level-tab-stop:1.0in; |
|
mso-list-type:simple; |
|
|
mso-list-template-ids:819084850;} |
|
|
@list l6:level1 |
|
|
{mso-level-number-format:bullet; |
|
|
mso-level-text:\F0B7; |
|
|
mso-level-tab-stop:.75in; |
|
| 204 |
mso-level-number-position:left; |
mso-level-number-position:left; |
| 205 |
margin-left:.75in; |
text-indent:-.25in;} |
| 206 |
text-indent:-.25in; |
@list l2:level3 |
| 207 |
font-family:Symbol;} |
{mso-level-tab-stop:1.5in; |
|
@list l7 |
|
|
{mso-list-id:-125; |
|
|
mso-list-type:simple; |
|
|
mso-list-template-ids:-676417338;} |
|
|
@list l7:level1 |
|
|
{mso-level-number-format:bullet; |
|
|
mso-level-text:\F0B7; |
|
|
mso-level-tab-stop:.5in; |
|
| 208 |
mso-level-number-position:left; |
mso-level-number-position:left; |
| 209 |
text-indent:-.25in; |
text-indent:-.25in;} |
| 210 |
font-family:Symbol;} |
@list l2:level4 |
| 211 |
@list l8 |
{mso-level-tab-stop:2.0in; |
|
{mso-list-id:-120; |
|
|
mso-list-type:simple; |
|
|
mso-list-template-ids:1291634668;} |
|
|
@list l8:level1 |
|
|
{mso-level-tab-stop:.25in; |
|
| 212 |
mso-level-number-position:left; |
mso-level-number-position:left; |
|
margin-left:.25in; |
|
| 213 |
text-indent:-.25in;} |
text-indent:-.25in;} |
| 214 |
@list l9 |
@list l2:level5 |
| 215 |
{mso-list-id:-119; |
{mso-level-tab-stop:2.5in; |
|
mso-list-type:simple; |
|
|
mso-list-template-ids:964484384;} |
|
|
@list l9:level1 |
|
|
{mso-level-number-format:bullet; |
|
|
mso-level-text:\F0B7; |
|
|
mso-level-tab-stop:.25in; |
|
| 216 |
mso-level-number-position:left; |
mso-level-number-position:left; |
| 217 |
margin-left:.25in; |
text-indent:-.25in;} |
| 218 |
text-indent:-.25in; |
@list l2:level6 |
| 219 |
font-family:Symbol;} |
{mso-level-tab-stop:3.0in; |
| 220 |
@list l10 |
mso-level-number-position:left; |
| 221 |
{mso-list-id:172575666; |
text-indent:-.25in;} |
| 222 |
|
@list l2:level7 |
| 223 |
|
{mso-level-tab-stop:3.5in; |
| 224 |
|
mso-level-number-position:left; |
| 225 |
|
text-indent:-.25in;} |
| 226 |
|
@list l2:level8 |
| 227 |
|
{mso-level-tab-stop:4.0in; |
| 228 |
|
mso-level-number-position:left; |
| 229 |
|
text-indent:-.25in;} |
| 230 |
|
@list l2:level9 |
| 231 |
|
{mso-level-tab-stop:4.5in; |
| 232 |
|
mso-level-number-position:left; |
| 233 |
|
text-indent:-.25in;} |
| 234 |
|
@list l3 |
| 235 |
|
{mso-list-id:604456885; |
| 236 |
mso-list-type:hybrid; |
mso-list-type:hybrid; |
| 237 |
mso-list-template-ids:1725869360 67698703 67698691 67698693 67698689 67698691 67698693 67698689 67698691 67698693;} |
mso-list-template-ids:1734899956 67698703 67698691 67698693 67698689 67698691 67698693 67698689 67698691 67698693;} |
| 238 |
@list l10:level1 |
@list l3:level1 |
| 239 |
{mso-level-tab-stop:.5in; |
{mso-level-tab-stop:.5in; |
| 240 |
mso-level-number-position:left; |
mso-level-number-position:left; |
| 241 |
text-indent:-.25in;} |
text-indent:-.25in;} |
| 242 |
@list l10:level2 |
@list l3:level2 |
| 243 |
{mso-level-number-format:bullet; |
{mso-level-number-format:bullet; |
| 244 |
mso-level-text:o; |
mso-level-text:o; |
| 245 |
mso-level-tab-stop:1.0in; |
mso-level-tab-stop:1.0in; |
| 246 |
mso-level-number-position:left; |
mso-level-number-position:left; |
| 247 |
text-indent:-.25in; |
text-indent:-.25in; |
| 248 |
font-family:"Courier New";} |
font-family:"Courier New";} |
| 249 |
@list l10:level3 |
@list l3:level3 |
| 250 |
{mso-level-number-format:bullet; |
{mso-level-number-format:bullet; |
| 251 |
mso-level-text:\F0A7; |
mso-level-text:\F0A7; |
| 252 |
mso-level-tab-stop:1.5in; |
mso-level-tab-stop:1.5in; |
| 253 |
mso-level-number-position:left; |
mso-level-number-position:left; |
| 254 |
text-indent:-.25in; |
text-indent:-.25in; |
| 255 |
font-family:Wingdings;} |
font-family:Wingdings;} |
| 256 |
@list l10:level4 |
@list l3:level4 |
| 257 |
{mso-level-number-format:bullet; |
{mso-level-number-format:bullet; |
| 258 |
mso-level-text:\F0B7; |
mso-level-text:\F0B7; |
| 259 |
mso-level-tab-stop:2.0in; |
mso-level-tab-stop:2.0in; |
| 260 |
mso-level-number-position:left; |
mso-level-number-position:left; |
| 261 |
text-indent:-.25in; |
text-indent:-.25in; |
| 262 |
font-family:Symbol;} |
font-family:Symbol;} |
| 263 |
@list l11 |
@list l3:level5 |
| 264 |
{mso-list-id:190000114; |
{mso-level-tab-stop:2.5in; |
| 265 |
|
mso-level-number-position:left; |
| 266 |
|
text-indent:-.25in;} |
| 267 |
|
@list l3:level6 |
| 268 |
|
{mso-level-tab-stop:3.0in; |
| 269 |
|
mso-level-number-position:left; |
| 270 |
|
text-indent:-.25in;} |
| 271 |
|
@list l3:level7 |
| 272 |
|
{mso-level-tab-stop:3.5in; |
| 273 |
|
mso-level-number-position:left; |
| 274 |
|
text-indent:-.25in;} |
| 275 |
|
@list l3:level8 |
| 276 |
|
{mso-level-tab-stop:4.0in; |
| 277 |
|
mso-level-number-position:left; |
| 278 |
|
text-indent:-.25in;} |
| 279 |
|
@list l3:level9 |
| 280 |
|
{mso-level-tab-stop:4.5in; |
| 281 |
|
mso-level-number-position:left; |
| 282 |
|
text-indent:-.25in;} |
| 283 |
|
@list l4 |
| 284 |
|
{mso-list-id:798038152; |
| 285 |
mso-list-type:hybrid; |
mso-list-type:hybrid; |
| 286 |
mso-list-template-ids:1560301118 423934604 67698691 67698693 67698689 67698691 67698693 67698689 67698691 67698693;} |
mso-list-template-ids:-2087438622 67698703 67698713 67698715 67698703 67698713 67698715 67698703 67698713 67698715;} |
| 287 |
@list l11:level1 |
@list l4:level1 |
| 288 |
{mso-level-start-at:0; |
{mso-level-tab-stop:39.0pt; |
|
mso-level-number-format:bullet; |
|
|
mso-level-text:-; |
|
|
mso-level-tab-stop:.5in; |
|
| 289 |
mso-level-number-position:left; |
mso-level-number-position:left; |
| 290 |
text-indent:-.25in; |
margin-left:39.0pt; |
| 291 |
font-family:Arial; |
text-indent:-.25in;} |
| 292 |
mso-fareast-font-family:"Times New Roman";} |
@list l4:level2 |
| 293 |
@list l12 |
{mso-level-tab-stop:1.0in; |
| 294 |
{mso-list-id:215170042; |
mso-level-number-position:left; |
| 295 |
|
text-indent:-.25in;} |
| 296 |
|
@list l4:level3 |
| 297 |
|
{mso-level-tab-stop:1.5in; |
| 298 |
|
mso-level-number-position:left; |
| 299 |
|
text-indent:-.25in;} |
| 300 |
|
@list l4:level4 |
| 301 |
|
{mso-level-tab-stop:2.0in; |
| 302 |
|
mso-level-number-position:left; |
| 303 |
|
text-indent:-.25in;} |
| 304 |
|
@list l4:level5 |
| 305 |
|
{mso-level-tab-stop:2.5in; |
| 306 |
|
mso-level-number-position:left; |
| 307 |
|
text-indent:-.25in;} |
| 308 |
|
@list l4:level6 |
| 309 |
|
{mso-level-tab-stop:3.0in; |
| 310 |
|
mso-level-number-position:left; |
| 311 |
|
text-indent:-.25in;} |
| 312 |
|
@list l4:level7 |
| 313 |
|
{mso-level-tab-stop:3.5in; |
| 314 |
|
mso-level-number-position:left; |
| 315 |
|
text-indent:-.25in;} |
| 316 |
|
@list l4:level8 |
| 317 |
|
{mso-level-tab-stop:4.0in; |
| 318 |
|
mso-level-number-position:left; |
| 319 |
|
text-indent:-.25in;} |
| 320 |
|
@list l4:level9 |
| 321 |
|
{mso-level-tab-stop:4.5in; |
| 322 |
|
mso-level-number-position:left; |
| 323 |
|
text-indent:-.25in;} |
| 324 |
|
@list l5 |
| 325 |
|
{mso-list-id:1085106306; |
| 326 |
mso-list-type:hybrid; |
mso-list-type:hybrid; |
| 327 |
mso-list-template-ids:1511950680 67698703 67698713 67698715 67698703 67698713 67698715 67698703 67698713 67698715;} |
mso-list-template-ids:1015583604 67698703 67698713 67698715 67698703 67698713 67698715 67698703 67698713 67698715;} |
| 328 |
@list l12:level1 |
@list l5:level1 |
| 329 |
{mso-level-tab-stop:.5in; |
{mso-level-tab-stop:.5in; |
| 330 |
mso-level-number-position:left; |
mso-level-number-position:left; |
| 331 |
text-indent:-.25in;} |
text-indent:-.25in;} |
| 332 |
@list l13 |
@list l5:level2 |
| 333 |
{mso-list-id:359431469; |
{mso-level-tab-stop:1.0in; |
| 334 |
|
mso-level-number-position:left; |
| 335 |
|
text-indent:-.25in;} |
| 336 |
|
@list l5:level3 |
| 337 |
|
{mso-level-tab-stop:1.5in; |
| 338 |
|
mso-level-number-position:left; |
| 339 |
|
text-indent:-.25in;} |
| 340 |
|
@list l5:level4 |
| 341 |
|
{mso-level-tab-stop:2.0in; |
| 342 |
|
mso-level-number-position:left; |
| 343 |
|
text-indent:-.25in;} |
| 344 |
|
@list l5:level5 |
| 345 |
|
{mso-level-tab-stop:2.5in; |
| 346 |
|
mso-level-number-position:left; |
| 347 |
|
text-indent:-.25in;} |
| 348 |
|
@list l5:level6 |
| 349 |
|
{mso-level-tab-stop:3.0in; |
| 350 |
|
mso-level-number-position:left; |
| 351 |
|
text-indent:-.25in;} |
| 352 |
|
@list l5:level7 |
| 353 |
|
{mso-level-tab-stop:3.5in; |
| 354 |
|
mso-level-number-position:left; |
| 355 |
|
text-indent:-.25in;} |
| 356 |
|
@list l5:level8 |
| 357 |
|
{mso-level-tab-stop:4.0in; |
| 358 |
|
mso-level-number-position:left; |
| 359 |
|
text-indent:-.25in;} |
| 360 |
|
@list l5:level9 |
| 361 |
|
{mso-level-tab-stop:4.5in; |
| 362 |
|
mso-level-number-position:left; |
| 363 |
|
text-indent:-.25in;} |
| 364 |
|
@list l6 |
| 365 |
|
{mso-list-id:1478297229; |
| 366 |
mso-list-type:hybrid; |
mso-list-type:hybrid; |
| 367 |
mso-list-template-ids:84734878 67698689 67698691 67698693 67698689 67698691 67698693 67698689 67698691 67698693;} |
mso-list-template-ids:-438127954 67698689 67698691 67698693 67698689 67698691 67698693 67698689 67698691 67698693;} |
| 368 |
@list l13:level1 |
@list l6:level1 |
| 369 |
{mso-level-number-format:bullet; |
{mso-level-number-format:bullet; |
| 370 |
mso-level-text:\F0B7; |
mso-level-text:\F0B7; |
| 371 |
mso-level-tab-stop:.5in; |
mso-level-tab-stop:.5in; |
| 372 |
mso-level-number-position:left; |
mso-level-number-position:left; |
| 373 |
text-indent:-.25in; |
text-indent:-.25in; |
| 374 |
font-family:Symbol;} |
font-family:Symbol;} |
| 375 |
@list l14 |
@list l6:level2 |
| 376 |
{mso-list-id:458649110; |
{mso-level-tab-stop:1.0in; |
|
mso-list-type:hybrid; |
|
|
mso-list-template-ids:-38738056 423934604 67698691 67698693 67698689 67698691 67698693 67698689 67698691 67698693;} |
|
|
@list l14:level1 |
|
|
{mso-level-start-at:0; |
|
|
mso-level-number-format:bullet; |
|
|
mso-level-text:-; |
|
|
mso-level-tab-stop:1.0in; |
|
| 377 |
mso-level-number-position:left; |
mso-level-number-position:left; |
| 378 |
margin-left:1.0in; |
text-indent:-.25in;} |
| 379 |
text-indent:-.25in; |
@list l6:level3 |
| 380 |
font-family:Arial; |
{mso-level-tab-stop:1.5in; |
|
mso-fareast-font-family:"Times New Roman";} |
|
|
@list l15 |
|
|
{mso-list-id:547566703; |
|
|
mso-list-type:hybrid; |
|
|
mso-list-template-ids:1798573620 67698703 67698713 67698715 67698703 67698713 67698715 67698703 67698713 67698715;} |
|
|
@list l15:level1 |
|
|
{mso-level-tab-stop:.5in; |
|
| 381 |
mso-level-number-position:left; |
mso-level-number-position:left; |
| 382 |
text-indent:-.25in;} |
text-indent:-.25in;} |
| 383 |
@list l16 |
@list l6:level4 |
| 384 |
{mso-list-id:752435528; |
{mso-level-tab-stop:2.0in; |
|
mso-list-type:hybrid; |
|
|
mso-list-template-ids:968014730 67698703 67698713 67698715 67698703 67698713 67698715 67698703 67698713 67698715;} |
|
|
@list l16:level1 |
|
|
{mso-level-tab-stop:.5in; |
|
| 385 |
mso-level-number-position:left; |
mso-level-number-position:left; |
| 386 |
text-indent:-.25in;} |
text-indent:-.25in;} |
| 387 |
@list l17 |
@list l6:level5 |
| 388 |
{mso-list-id:1072436292; |
{mso-level-tab-stop:2.5in; |
|
mso-list-type:hybrid; |
|
|
mso-list-template-ids:1681550614 423934604 67698691 67698693 67698689 67698691 67698693 67698689 67698691 67698693;} |
|
|
@list l17:level1 |
|
|
{mso-level-start-at:0; |
|
|
mso-level-number-format:bullet; |
|
|
mso-level-text:-; |
|
|
mso-level-tab-stop:.75in; |
|
| 389 |
mso-level-number-position:left; |
mso-level-number-position:left; |
| 390 |
margin-left:.75in; |
text-indent:-.25in;} |
| 391 |
text-indent:-.25in; |
@list l6:level6 |
| 392 |
font-family:Arial; |
{mso-level-tab-stop:3.0in; |
|
mso-fareast-font-family:"Times New Roman";} |
|
|
@list l17:level2 |
|
|
{mso-level-number-format:bullet; |
|
|
mso-level-text:o; |
|
|
mso-level-tab-stop:1.25in; |
|
| 393 |
mso-level-number-position:left; |
mso-level-number-position:left; |
| 394 |
margin-left:1.25in; |
text-indent:-.25in;} |
| 395 |
text-indent:-.25in; |
@list l6:level7 |
| 396 |
font-family:"Courier New";} |
{mso-level-tab-stop:3.5in; |
|
@list l18 |
|
|
{mso-list-id:1209411371; |
|
|
mso-list-type:hybrid; |
|
|
mso-list-template-ids:-1603923158 67698689 67698691 67698693 67698689 67698691 67698693 67698689 67698691 67698693;} |
|
|
@list l18:level1 |
|
|
{mso-level-number-format:bullet; |
|
|
mso-level-text:\F0B7; |
|
|
mso-level-tab-stop:.75in; |
|
| 397 |
mso-level-number-position:left; |
mso-level-number-position:left; |
| 398 |
margin-left:.75in; |
text-indent:-.25in;} |
| 399 |
text-indent:-.25in; |
@list l6:level8 |
| 400 |
font-family:Symbol;} |
{mso-level-tab-stop:4.0in; |
|
@list l19 |
|
|
{mso-list-id:1432318865; |
|
|
mso-list-type:hybrid; |
|
|
mso-list-template-ids:2137158298 423934604 67698691 67698693 67698689 67698691 67698693 67698689 67698691 67698693;} |
|
|
@list l19:level1 |
|
|
{mso-level-start-at:0; |
|
|
mso-level-number-format:bullet; |
|
|
mso-level-text:-; |
|
|
mso-level-tab-stop:.5in; |
|
| 401 |
mso-level-number-position:left; |
mso-level-number-position:left; |
| 402 |
text-indent:-.25in; |
text-indent:-.25in;} |
| 403 |
font-family:Arial; |
@list l6:level9 |
| 404 |
mso-fareast-font-family:"Times New Roman";} |
{mso-level-tab-stop:4.5in; |
| 405 |
@list l20 |
mso-level-number-position:left; |
| 406 |
{mso-list-id:1611356098; |
text-indent:-.25in;} |
| 407 |
|
@list l7 |
| 408 |
|
{mso-list-id:1644238654; |
| 409 |
|
mso-list-template-ids:-1891084734;} |
| 410 |
|
@list l8 |
| 411 |
|
{mso-list-id:1723091313; |
| 412 |
mso-list-type:hybrid; |
mso-list-type:hybrid; |
| 413 |
mso-list-template-ids:-854709908 67698703 67698713 67698715 67698703 67698713 67698715 67698703 67698713 67698715;} |
mso-list-template-ids:-1797201838 67698703 67698713 67698715 67698703 67698713 67698715 67698703 67698713 67698715;} |
| 414 |
@list l20:level1 |
@list l8:level1 |
| 415 |
{mso-level-tab-stop:.5in; |
{mso-level-tab-stop:.5in; |
| 416 |
mso-level-number-position:left; |
mso-level-number-position:left; |
| 417 |
text-indent:-.25in;} |
text-indent:-.25in;} |
| 418 |
@list l21 |
@list l8:level2 |
| 419 |
{mso-list-id:1614744623; |
{mso-level-tab-stop:1.0in; |
|
mso-list-type:hybrid; |
|
|
mso-list-template-ids:-1496942198 423934604 67698691 67698693 67698689 67698691 67698693 67698689 67698691 67698693;} |
|
|
@list l21:level1 |
|
|
{mso-level-start-at:0; |
|
|
mso-level-number-format:bullet; |
|
|
mso-level-text:-; |
|
|
mso-level-tab-stop:.5in; |
|
| 420 |
mso-level-number-position:left; |
mso-level-number-position:left; |
| 421 |
text-indent:-.25in; |
text-indent:-.25in;} |
| 422 |
font-family:Arial; |
@list l8:level3 |
| 423 |
mso-fareast-font-family:"Times New Roman";} |
{mso-level-tab-stop:1.5in; |
|
@list l21:level2 |
|
|
{mso-level-number-format:bullet; |
|
|
mso-level-text:o; |
|
|
mso-level-tab-stop:1.0in; |
|
| 424 |
mso-level-number-position:left; |
mso-level-number-position:left; |
| 425 |
text-indent:-.25in; |
text-indent:-.25in;} |
| 426 |
font-family:"Courier New";} |
@list l8:level4 |
| 427 |
@list l21:level3 |
{mso-level-tab-stop:2.0in; |
|
{mso-level-number-format:bullet; |
|
|
mso-level-text:\F0A7; |
|
|
mso-level-tab-stop:1.5in; |
|
| 428 |
mso-level-number-position:left; |
mso-level-number-position:left; |
| 429 |
text-indent:-.25in; |
text-indent:-.25in;} |
| 430 |
font-family:Wingdings;} |
@list l8:level5 |
| 431 |
@list l21:level4 |
{mso-level-tab-stop:2.5in; |
|
{mso-level-number-format:bullet; |
|
|
mso-level-text:\F0B7; |
|
|
mso-level-tab-stop:2.0in; |
|
| 432 |
mso-level-number-position:left; |
mso-level-number-position:left; |
| 433 |
text-indent:-.25in; |
text-indent:-.25in;} |
| 434 |
font-family:Symbol;} |
@list l8:level6 |
| 435 |
@list l22 |
{mso-level-tab-stop:3.0in; |
|
{mso-list-id:1693457207; |
|
|
mso-list-type:hybrid; |
|
|
mso-list-template-ids:-1668623746 67698703 67698691 67698693 67698689 67698691 67698693 67698689 67698691 67698693;} |
|
|
@list l22:level1 |
|
|
{mso-level-tab-stop:.5in; |
|
| 436 |
mso-level-number-position:left; |
mso-level-number-position:left; |
| 437 |
text-indent:-.25in;} |
text-indent:-.25in;} |
| 438 |
@list l22:level2 |
@list l8:level7 |
| 439 |
{mso-level-number-format:bullet; |
{mso-level-tab-stop:3.5in; |
|
mso-level-text:o; |
|
|
mso-level-tab-stop:1.0in; |
|
| 440 |
mso-level-number-position:left; |
mso-level-number-position:left; |
| 441 |
text-indent:-.25in; |
text-indent:-.25in;} |
| 442 |
font-family:"Courier New";} |
@list l8:level8 |
| 443 |
@list l22:level3 |
{mso-level-tab-stop:4.0in; |
|
{mso-level-number-format:bullet; |
|
|
mso-level-text:\F0A7; |
|
|
mso-level-tab-stop:1.5in; |
|
| 444 |
mso-level-number-position:left; |
mso-level-number-position:left; |
| 445 |
text-indent:-.25in; |
text-indent:-.25in;} |
| 446 |
font-family:Wingdings;} |
@list l8:level9 |
| 447 |
@list l22:level4 |
{mso-level-tab-stop:4.5in; |
|
{mso-level-number-format:bullet; |
|
|
mso-level-text:\F0B7; |
|
|
mso-level-tab-stop:2.0in; |
|
| 448 |
mso-level-number-position:left; |
mso-level-number-position:left; |
| 449 |
text-indent:-.25in; |
text-indent:-.25in;} |
| 450 |
font-family:Symbol;} |
@list l9 |
|
@list l23 |
|
| 451 |
{mso-list-id:1731031428; |
{mso-list-id:1731031428; |
| 452 |
mso-list-type:hybrid; |
mso-list-type:hybrid; |
| 453 |
mso-list-template-ids:1886447558 67698703 67698713 67698715 67698703 67698713 67698715 67698703 67698713 67698715;} |
mso-list-template-ids:1886447558 67698703 67698713 67698715 67698703 67698713 67698715 67698703 67698713 67698715;} |
| 454 |
@list l23:level1 |
@list l9:level1 |
| 455 |
{mso-level-tab-stop:39.0pt; |
{mso-level-tab-stop:39.0pt; |
| 456 |
mso-level-number-position:left; |
mso-level-number-position:left; |
| 457 |
margin-left:39.0pt; |
margin-left:39.0pt; |
| 458 |
text-indent:-.25in;} |
text-indent:-.25in;} |
| 459 |
@list l24 |
@list l9:level2 |
| 460 |
{mso-list-id:1832519519; |
{mso-level-tab-stop:1.0in; |
|
mso-list-type:hybrid; |
|
|
mso-list-template-ids:-658358596 423934604 67698691 67698693 67698689 67698691 67698693 67698689 67698691 67698693;} |
|
|
@list l24:level1 |
|
|
{mso-level-start-at:0; |
|
|
mso-level-number-format:bullet; |
|
|
mso-level-text:-; |
|
|
mso-level-tab-stop:.5in; |
|
| 461 |
mso-level-number-position:left; |
mso-level-number-position:left; |
| 462 |
text-indent:-.25in; |
text-indent:-.25in;} |
| 463 |
font-family:Arial; |
@list l9:level3 |
| 464 |
mso-fareast-font-family:"Times New Roman";} |
{mso-level-tab-stop:1.5in; |
|
@list l25 |
|
|
{mso-list-id:1853185266; |
|
|
mso-list-type:hybrid; |
|
|
mso-list-template-ids:403894856 423934604 67698691 67698693 67698689 67698691 67698693 67698689 67698691 67698693;} |
|
|
@list l25:level1 |
|
|
{mso-level-start-at:0; |
|
|
mso-level-number-format:bullet; |
|
|
mso-level-text:-; |
|
|
mso-level-tab-stop:.5in; |
|
| 465 |
mso-level-number-position:left; |
mso-level-number-position:left; |
| 466 |
text-indent:-.25in; |
text-indent:-.25in;} |
| 467 |
font-family:Arial; |
@list l9:level4 |
| 468 |
mso-fareast-font-family:"Times New Roman";} |
{mso-level-tab-stop:2.0in; |
|
@list l25:level2 |
|
|
{mso-level-number-format:bullet; |
|
|
mso-level-text:o; |
|
|
mso-level-tab-stop:1.0in; |
|
| 469 |
mso-level-number-position:left; |
mso-level-number-position:left; |
| 470 |
text-indent:-.25in; |
text-indent:-.25in;} |
| 471 |
font-family:"Courier New";} |
@list l9:level5 |
| 472 |
@list l26 |
{mso-level-tab-stop:2.5in; |
| 473 |
{mso-list-id:1938905931; |
mso-level-number-position:left; |
| 474 |
mso-list-type:hybrid; |
text-indent:-.25in;} |
| 475 |
mso-list-template-ids:1084264292 423934604 67698691 67698693 67698689 67698691 67698693 67698689 67698691 67698693;} |
@list l9:level6 |
| 476 |
@list l26:level1 |
{mso-level-tab-stop:3.0in; |
| 477 |
{mso-level-start-at:0; |
mso-level-number-position:left; |
| 478 |
mso-level-number-format:bullet; |
text-indent:-.25in;} |
| 479 |
mso-level-text:-; |
@list l9:level7 |
| 480 |
|
{mso-level-tab-stop:3.5in; |
| 481 |
|
mso-level-number-position:left; |
| 482 |
|
text-indent:-.25in;} |
| 483 |
|
@list l9:level8 |
| 484 |
|
{mso-level-tab-stop:4.0in; |
| 485 |
|
mso-level-number-position:left; |
| 486 |
|
text-indent:-.25in;} |
| 487 |
|
@list l9:level9 |
| 488 |
|
{mso-level-tab-stop:4.5in; |
| 489 |
|
mso-level-number-position:left; |
| 490 |
|
text-indent:-.25in;} |
| 491 |
|
@list l10 |
| 492 |
|
{mso-list-id:1830093817; |
| 493 |
|
mso-list-template-ids:672403872;} |
| 494 |
|
@list l11 |
| 495 |
|
{mso-list-id:1943487606; |
| 496 |
|
mso-list-template-ids:1313531012;} |
| 497 |
|
@list l11:level1 |
| 498 |
|
{mso-level-number-format:bullet; |
| 499 |
|
mso-level-text:\F0B7; |
| 500 |
mso-level-tab-stop:.5in; |
mso-level-tab-stop:.5in; |
| 501 |
mso-level-number-position:left; |
mso-level-number-position:left; |
| 502 |
text-indent:-.25in; |
text-indent:-.25in; |
| 503 |
font-family:Arial; |
mso-ansi-font-size:10.0pt; |
| 504 |
mso-fareast-font-family:"Times New Roman";} |
font-family:Symbol;} |
| 505 |
ol |
ol |
| 506 |
{margin-bottom:0in;} |
{margin-bottom:0in;} |
| 507 |
ul |
ul |
| 534 |
<h1>Generalized Undo Support in Eclipse</h1> |
<h1>Generalized Undo Support in Eclipse</h1> |
| 535 |
|
|
| 536 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Last |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Last |
| 537 |
updated:<span style='mso-spacerun:yes'> </span></span><st1:date Month="11" |
updated:<span style='mso-spacerun:yes'> </span></span><st1:date Month="12" |
| 538 |
Day="9" Year="2004"><span style='font-size:10.0pt;font-family:Arial'>Nov 9, |
Day="17" Year="2004"><span style='font-size:10.0pt;font-family:Arial'>Dec. 17, |
| 539 |
2004</span></st1:date><span style='font-size:10.0pt;font-family:Arial'><o:p></o:p></span></p> |
2004</span></st1:date><span style='font-size:10.0pt;font-family:Arial'><o:p></o:p></span></p> |
| 540 |
|
|
| 541 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Status:<span |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Status:<span |
| 542 |
style='mso-spacerun:yes'> </span>Under investigation (see bug </span><a |
style='mso-spacerun:yes'> </span>Proposal <o:p></o:p></span></p> |
| 543 |
|
|
| 544 |
|
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>(see also </span><a |
| 545 |
href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=37716">37716</a>)<span |
href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=37716">37716</a>)<span |
| 546 |
style='font-size:10.0pt;font-family:Arial'><o:p></o:p></span></p> |
style='font-size:10.0pt;font-family:Arial'><o:p></o:p></span></p> |
| 547 |
|
|
| 548 |
<h2>Problem Description<o:p></o:p></h2> |
<h2>Problem Description</h2> |
| 549 |
|
|
| 550 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>In R3.0.1 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>In R3.0.1 |
| 551 |
of the Eclipse SDK, there is no generalized support for undoing user actions.<span |
of the Eclipse SDK, there is no generalized support for undoing user |
| 552 |
style='mso-spacerun:yes'> </span>Each plug-in is left to implement its own |
actions.<span style='mso-spacerun:yes'> </span>Each plug-in is left to |
| 553 |
strategy for undo, if at all.<span style='mso-spacerun:yes'> </span>This |
implement its own strategy for undo, if at all.<span style='mso-spacerun:yes'> |
| 554 |
approach can cause many general problems as independently developed plug-ins implement |
</span>This approach can cause problems for both Eclipse users and plug-in |
| 555 |
their own undo strategies:<o:p></o:p></span></p> |
developers:<o:p></o:p></span></p> |
| 556 |
|
|
| 557 |
|
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><span |
| 558 |
|
style='mso-spacerun:yes'> </span><o:p></o:p></span></p> |
| 559 |
|
|
| 560 |
|
<ul style='margin-top:0in' type=disc> |
| 561 |
|
<li class=MsoNormal style='mso-list:l2 level1 lfo3;tab-stops:list .5in'><span |
| 562 |
|
style='font-size:10.0pt;font-family:Arial'>Undo and redo actions appear in |
| 563 |
|
different menus, causing user confusion and UI clutter<o:p></o:p></span></li> |
| 564 |
|
<li class=MsoNormal style='mso-list:l2 level1 lfo3;tab-stops:list .5in'><span |
| 565 |
|
style='font-size:10.0pt;font-family:Arial'>Undo and redo implementations |
| 566 |
|
may have different semantics.<o:p></o:p></span></li> |
| 567 |
|
<li class=MsoNormal style='mso-list:l2 level1 lfo3;tab-stops:list .5in'><span |
| 568 |
|
style='font-size:10.0pt;font-family:Arial'>Plug-ins that depend on other |
| 569 |
|
plug-ins which implement their own undo strategy are forced to choose |
| 570 |
|
between different implementations and possibly write integration code to |
| 571 |
|
allow the different frameworks to coexist.<o:p></o:p></span></li> |
| 572 |
|
</ul> |
| 573 |
|
|
| 574 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
| 575 |
|
|
| 576 |
<p class=MsoNormal style='margin-left:.5in;text-indent:-.25in;mso-list:l21 level1 lfo1; |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Further, |
| 577 |
tab-stops:list .5in'><![if !supportLists]><span style='font-size:10.0pt; |
the meaning of undo can be very different depending on what the user is |
| 578 |
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>-<span |
doing.<span style='mso-spacerun:yes'> </span>The most common type of undo is |
| 579 |
style='font:7.0pt "Times New Roman"'> |
text undo.<span style='mso-spacerun:yes'> </span>The user can undo lightweight |
| 580 |
</span></span></span><![endif]><span style='font-size:10.0pt;font-family:Arial'>Undo |
edit operations such as inserting, replacing, or deleting text.<span |
| 581 |
and redo actions appear in different menus.<o:p></o:p></span></p> |
style='mso-spacerun:yes'> </span>Other types of undo may involve more complex, |
| 582 |
|
heavyweight operations that affect an underlying model of many elements.<span |
| 583 |
<p class=MsoNormal style='margin-left:.5in;text-indent:-.25in;mso-list:l21 level1 lfo1; |
style='mso-spacerun:yes'> </span>For example, the JDT refactoring support |
| 584 |
tab-stops:list .5in'><![if !supportLists]><span style='font-size:10.0pt; |
provides undo support for refactoring operations that involve many Java |
| 585 |
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>-<span |
elements at different levels, such as Java packages, compilation units, |
| 586 |
style='font:7.0pt "Times New Roman"'> |
classes, and methods.<o:p></o:p></span></p> |
|
</span></span></span><![endif]><span style='font-size:10.0pt;font-family:Arial'>Undo |
|
|
and redo implementations can have different semantics.<span |
|
|
style='mso-spacerun:yes'> </span>Different approaches to undo by different |
|
|
plug-ins may confuse the user if they choose different semantics.<span |
|
|
style='mso-spacerun:yes'> </span>For example:<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='margin-left:1.0in;text-indent:-.25in;mso-list:l21 level2 lfo1; |
|
|
tab-stops:list 1.0in'><![if !supportLists]><span style='font-size:10.0pt; |
|
|
font-family:"Courier New";mso-fareast-font-family:"Courier New"'><span |
|
|
style='mso-list:Ignore'>o<span style='font:7.0pt "Times New Roman"'> |
|
|
</span></span></span><![endif]><span style='font-size:10.0pt;font-family:Arial'>Is |
|
|
undo strictly linear?<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='margin-left:1.0in;text-indent:-.25in;mso-list:l21 level2 lfo1; |
|
|
tab-stops:list 1.0in'><![if !supportLists]><span style='font-size:10.0pt; |
|
|
font-family:"Courier New";mso-fareast-font-family:"Courier New"'><span |
|
|
style='mso-list:Ignore'>o<span style='font:7.0pt "Times New Roman"'> |
|
|
</span></span></span><![endif]><span style='font-size:10.0pt;font-family:Arial'>If |
|
|
it is not linear, what techniques are used to undo an operation?<span |
|
|
style='mso-spacerun:yes'> </span>Implementation models for non-linear undo (rollback |
|
|
and perform the history again, dynamic reversal) can affect the user outcome.<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='margin-left:1.0in;text-indent:-.25in;mso-list:l21 level2 lfo1; |
|
|
tab-stops:list 1.0in'><![if !supportLists]><span style='font-size:10.0pt; |
|
|
font-family:"Courier New";mso-fareast-font-family:"Courier New"'><span |
|
|
style='mso-list:Ignore'>o<span style='font:7.0pt "Times New Roman"'> |
|
|
</span></span></span><![endif]><span style='font-size:10.0pt;font-family:Arial'>What |
|
|
is the scope of an undo?<span style='mso-spacerun:yes'> </span>Is it global to |
|
|
the system?<span style='mso-spacerun:yes'> </span>Is it local to the |
|
|
window?<span style='mso-spacerun:yes'> </span>Is it model-dependent?<span |
|
|
style='mso-spacerun:yes'> </span><o:p></o:p></span></p> |
|
| 587 |
|
|
| 588 |
<p class=MsoNormal style='margin-left:.5in;text-indent:-.25in;mso-list:l21 level1 lfo1; |
<h2>Operations Framework</h2> |
| 589 |
tab-stops:list .5in'><![if !supportLists]><span style='font-size:10.0pt; |
|
| 590 |
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>-<span |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>The |
| 591 |
style='font:7.0pt "Times New Roman"'> |
proposed framework defines an interface for describing work, called an |
| 592 |
</span></span></span><![endif]><span style='font-size:10.0pt;font-family:Arial'>Plug-ins |
“operation” (IOperation), that can be executed, undone, and redone.<span |
| 593 |
that want to add undo support may have to choose between different undo |
style='mso-spacerun:yes'> </span>Operations are created, executed, and added |
| 594 |
strategies and implementations provided by their required plug-ins, or worse |
to an operations history (IOperationHistory).<span style='mso-spacerun:yes'> |
| 595 |
yet, implement yet another strategy.<o:p></o:p></span></p> |
</span>Operations which are comprised of distinct steps are represented as |
| 596 |
|
compound operations.<span style='mso-spacerun:yes'> </span>Compound operations |
| 597 |
<h3>Challenges with generalized undo support<o:p></o:p></h3> |
must be executed, undone, or redone as a unit, and can never be partially |
| 598 |
|
undone.<span style='mso-spacerun:yes'> </span><o:p></o:p></span></p> |
|
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>While |
|
|
implementation of a centralized undo mechanism should be straightforward, it |
|
|
has not been provided in previous releases due to problems in defining the |
|
|
proper undo semantics across different plug-ins.<span |
|
|
style='mso-spacerun:yes'> </span>The challenge in defining consistent, predictable |
|
|
undo semantics can best be understood by looking at the two different undo |
|
|
models provided in the R3.0.1 release of the base Eclipse SDK.<span |
|
|
style='mso-spacerun:yes'> </span><o:p></o:p></span></p> |
|
| 599 |
|
|
| 600 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
| 601 |
|
|
| 602 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>The SDK |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Operations |
| 603 |
currently contains two undo implementations and user commands:<o:p></o:p></span></p> |
can be assigned one or more contexts (IOperationContext) to which they |
| 604 |
|
apply.<span style='mso-spacerun:yes'> </span>An operation<span |
| 605 |
|
style='mso-spacerun:yes'> </span>context describes the context in which the |
| 606 |
|
user is working when an operation is performed, undone, or redone.<span |
| 607 |
|
style='mso-spacerun:yes'> </span>Contexts can be used by workbench parts to |
| 608 |
|
filter the operations history, so that only those operations that have been |
| 609 |
|
assigned the part’s context are available for undo/redo when that part is |
| 610 |
|
active.<o:p></o:p></span></p> |
| 611 |
|
|
| 612 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
| 613 |
|
|
| 614 |
<p class=MsoNormal style='margin-left:.5in;text-indent:-.25in;mso-list:l26 level1 lfo2; |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>The |
| 615 |
tab-stops:list .5in'><![if !supportLists]><span style='font-size:10.0pt; |
interface for operation contexts is left very general so that operation |
| 616 |
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>-<span |
implementers may choose the appropriate representation for their contexts.<span |
| 617 |
style='font:7.0pt "Times New Roman"'> |
style='mso-spacerun:yes'> </span>In some cases, a part-oriented context may be |
| 618 |
</span></span></span><![endif]><span style='font-size:10.0pt;font-family:Arial'>Text |
appropriate. For example, a text editor’s context is related to the editor |
| 619 |
undo (Edit>Undo) provides a linear undo model for text-level |
itself and its life-cycle is similar to that of the editor.<span |
| 620 |
operations.<span style='mso-spacerun:yes'> </span>That is, textual insert/replace/delete |
style='mso-spacerun:yes'> </span>The navigator’s context is closely related to |
| 621 |
operations can be undone in the reverse order in which they are applied.<span |
the workspace model objects, and the context related to the workspace has a |
| 622 |
style='mso-spacerun:yes'> </span><o:p></o:p></span></p> |
life cycle to similar to that of the workspace itself.<o:p></o:p></span></p> |
| 623 |
|
|
| 624 |
<p class=MsoNormal style='margin-left:.5in;text-indent:-.25in;mso-list:l21 level1 lfo1; |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
| 625 |
tab-stops:list .5in'><![if !supportLists]><span style='font-size:10.0pt; |
|
| 626 |
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>-<span |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Contexts |
| 627 |
style='font:7.0pt "Times New Roman"'> |
can be assigned to operations in multiple ways:<o:p></o:p></span></p> |
|
</span></span></span><![endif]><span class=SpellE><span style='font-size:10.0pt; |
|
|
font-family:Arial'>Refactoring</span></span><span style='font-size:10.0pt; |
|
|
font-family:Arial'> undo (<span class=SpellE>Refactor</span>>Undo) allows an |
|
|
undo of the last <span class=SpellE>refactoring</span> operation, but only when |
|
|
the workspace has not been otherwise modified since the last <span |
|
|
class=SpellE>refactoring</span>.<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>In |
|
|
discussing the appropriate semantics for workbench undo, it is useful to |
|
|
introduce terminology that is independent of any particular implementation for |
|
|
undo support.<o:p></o:p></span></p> |
|
|
|
|
|
<h3>Undo contexts </h3> |
|
|
|
|
|
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Undo |
|
|
implementations must provide a history of operations performed by the user and |
|
|
some knowledge of the “context” for these operations.<span |
|
|
style='mso-spacerun:yes'> </span>For example, the text editor undo operates |
|
|
within the context of a single document, while <span class=SpellE>refactoring</span> |
|
|
undo operates within the context of some workspace resources.<span |
|
|
style='mso-spacerun:yes'> </span><o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>The context |
|
|
for an operation helps determine where the undo for that operation is |
|
|
available.<span style='mso-spacerun:yes'> </span>When the contexts for different |
|
|
operations are completely separate, the semantics for undoing an operation from |
|
|
either context are easily understood.<span style='mso-spacerun:yes'> |
|
|
</span>Undoing an operation from one context does not affect the operation |
|
|
history from the other context. <o:p></o:p></span></p> |
|
|
|
|
|
<h3>Undo scopes </h3> |
|
|
|
|
|
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Even when |
|
|
completely separate undo contexts exist, the scope of the operation history and |
|
|
resulting undo operation must be defined.<span style='mso-spacerun:yes'> |
|
|
</span>There are a few different alternatives:<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='margin-left:.5in;text-indent:-.25in;mso-list:l21 level1 lfo1; |
|
|
tab-stops:list .5in'><![if !supportLists]><span style='font-size:10.0pt; |
|
|
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>-<span |
|
|
style='font:7.0pt "Times New Roman"'> |
|
|
</span></span></span><![endif]><span style='font-size:10.0pt;font-family:Arial'>The |
|
|
UI that manipulates each separate undo context provides its own undo command.<span |
|
|
style='mso-spacerun:yes'> </span>This is done in R3.0.1 with Edit>Undo and <span |
|
|
class=SpellE>Refactoring</span>>Undo.<span style='mso-spacerun:yes'> |
|
|
</span>This does not scale well, but makes it clear which context is to be |
|
|
undone by forcing the user to explicitly choose the context for the undo.<span |
|
|
style='mso-spacerun:yes'> </span>We call this an <b style='mso-bidi-font-weight: |
|
|
normal'>explicit local undo scope</b>.<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='margin-left:.5in;text-indent:-.25in;mso-list:l21 level1 lfo1; |
|
|
tab-stops:list .5in'><![if !supportLists]><span style='font-size:10.0pt; |
|
|
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>-<span |
|
|
style='font:7.0pt "Times New Roman"'> |
|
|
</span></span></span><![endif]><span style='font-size:10.0pt;font-family:Arial'>A |
|
|
unified undo command exists and its meaning is interpreted according to some |
|
|
current context (such as the active part or the currently edited model).<span |
|
|
style='mso-spacerun:yes'> </span>The unified command only ever operates on the |
|
|
current context.<span style='mso-spacerun:yes'> </span>This is analogous to |
|
|
retargeted global actions in the Eclipse workbench.<span |
|
|
style='mso-spacerun:yes'> </span>We call this <b style='mso-bidi-font-weight: |
|
|
normal'>implicit local undo scope</b>.<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='margin-left:.5in;text-indent:-.25in;mso-list:l21 level1 lfo1; |
|
|
tab-stops:list .5in'><![if !supportLists]><span style='font-size:10.0pt; |
|
|
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>-<span |
|
|
style='font:7.0pt "Times New Roman"'> |
|
|
</span></span></span><![endif]><span style='font-size:10.0pt;font-family:Arial'>A |
|
|
unified undo command exists and its meaning is global for all operations |
|
|
performed in the system.<span style='mso-spacerun:yes'> </span>The history |
|
|
list and default operation to be undone have no relationship to the user’s |
|
|
current context.<span style='mso-spacerun:yes'> </span>We call this <b |
|
|
style='mso-bidi-font-weight:normal'>global undo scope</b>.<o:p></o:p></span></p> |
|
| 628 |
|
|
| 629 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
| 630 |
|
|
| 631 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>The |
<p class=MsoNormal style='margin-left:39.0pt;text-indent:-.25in;mso-list:l9 level1 lfo5; |
| 632 |
appropriate scope to be used depends on what the user is doing.<span |
tab-stops:list 39.0pt'><![if !supportLists]><span style='font-size:10.0pt; |
| 633 |
style='mso-spacerun:yes'> </span>When the operations performed by a user are sequential |
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>1.<span |
| 634 |
steps in a larger task, a global scope may be appropriate.<span |
style='font:7.0pt "Times New Roman"'> </span></span></span><![endif]><span |
| 635 |
style='mso-spacerun:yes'> </span>When a user is performing separate tasks |
style='font-size:10.0pt;font-family:Arial'>The context can be assigned |
| 636 |
while working in separate views, a more localized scope is appropriate.<span |
initially when the operation is created.<span style='mso-spacerun:yes'> |
| 637 |
style='mso-spacerun:yes'> </span>The decision is largely subjective and often |
</span>For example, text operations are triggered by typing in the editor, and |
| 638 |
cannot be predicted by the system. <a style='mso-footnote-id:ftn1' href="#_ftn1" |
the editor can assign its context to the operation before adding it to the |
| 639 |
name="_ftnref1" title=""><span class=MsoFootnoteReference><span |
history.<span style='mso-spacerun:yes'> </span><o:p></o:p></span></p> |
| 640 |
style='mso-special-character:footnote'><![if !supportFootnotes]><span |
|
| 641 |
class=MsoFootnoteReference><span style='font-size:10.0pt;font-family:Arial; |
<p class=MsoNormal style='margin-left:39.0pt;text-indent:-.25in;mso-list:l9 level1 lfo5; |
| 642 |
mso-fareast-font-family:"Times New Roman";mso-ansi-language:EN-US;mso-fareast-language: |
tab-stops:list 39.0pt'><![if !supportLists]><span style='font-size:10.0pt; |
| 643 |
EN-US;mso-bidi-language:AR-SA'>[1]</span></span><![endif]></span></span></a><o:p></o:p></span></p> |
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>2.<span |
| 644 |
|
style='font:7.0pt "Times New Roman"'> </span></span></span><![endif]><span |
| 645 |
<h3>Shared undo contexts<o:p></o:p></h3> |
style='font-size:10.0pt;font-family:Arial'>A listener interface on the |
| 646 |
|
operations history allows listeners to detect when an operation is added to the |
| 647 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Unfortunately, |
history.<span style='mso-spacerun:yes'> </span>Listeners can decide if their |
| 648 |
the SDK model for undo is more complicated.<span style='mso-spacerun:yes'> |
context should be added to the operation.<span style='mso-spacerun:yes'> |
|
</span>The contexts for edit and <span class=SpellE>refactoring</span> undo are |
|
|
not completely separate.<span style='mso-spacerun:yes'> </span>The user can |
|
|
trigger <span class=SpellE>refactoring</span> changes from the editor |
|
|
itself.<span style='mso-spacerun:yes'> </span>These changes can manipulate |
|
|
both the document being edited and other workspace resources.<span |
|
|
style='mso-spacerun:yes'> </span>Further, these changes occur alongside |
|
|
localized text editing changes, creating an operation history with multiple |
|
|
contexts that are initiated from a single part.<span style='mso-spacerun:yes'> |
|
| 649 |
</span><o:p></o:p></span></p> |
</span><o:p></o:p></span></p> |
| 650 |
|
|
| 651 |
|
<p class=MsoNormal style='margin-left:21.0pt'><span style='font-size:10.0pt; |
| 652 |
|
font-family:Arial'><o:p> </o:p></span></p> |
| 653 |
|
|
| 654 |
|
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>An |
| 655 |
|
operation may have more than one context.<span style='mso-spacerun:yes'> |
| 656 |
|
</span>For example, an operation may affect many elements in the workspace, |
| 657 |
|
including one that is currently open in an editor.<span |
| 658 |
|
style='mso-spacerun:yes'> </span>That operation could be assigned two |
| 659 |
|
independent contexts, so that it can be undone from both the editor and the |
| 660 |
|
view manipulating the model.<span style='mso-spacerun:yes'> </span><o:p></o:p></span></p> |
| 661 |
|
|
| 662 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
| 663 |
|
|
| 664 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Even when a |
<h2>Levels of Integration and Migration</h2> |
| 665 |
local undo scope is employed, there are different possibilities for |
|
| 666 |
interpreting “undo” when a <span class=SpellE>refactoring</span> operation is |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Many |
| 667 |
triggered from an editor:<o:p></o:p></span></p> |
plug-ins have already invested heavily in building objects that describe |
| 668 |
|
undoable user commands or operations.<span style='mso-spacerun:yes'> </span>It |
| 669 |
|
is not expected that all plug-ins will adopt the framework completely, given |
| 670 |
|
the individual schedules and other constraints for each plug-in.<span |
| 671 |
|
style='mso-spacerun:yes'> </span>However, the integration can be achieved in |
| 672 |
|
phases that will immediately provide value to dependent plug-ins.<span |
| 673 |
|
style='mso-spacerun:yes'> </span>The following adoption strategy is strongly |
| 674 |
|
encouraged:<o:p></o:p></span></p> |
| 675 |
|
|
| 676 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
| 677 |
|
|
| 678 |
<ol style='margin-top:0in' start=1 type=1> |
<ol style='margin-top:0in' start=1 type=1> |
| 679 |
<li class=MsoNormal style='mso-list:l22 level1 lfo3;tab-stops:list .5in'><span |
<li class=MsoNormal style='mso-list:l8 level1 lfo8;tab-stops:list .5in'><span |
| 680 |
style='font-size:10.0pt;font-family:Arial'>Edit>Undo causes reversal of |
style='font-size:10.0pt;font-family:Arial'>Existing command/undo |
| 681 |
the <span class=SpellE>refactoring</span> operation that was triggered |
frameworks can implement the IOperation interface on their existing |
| 682 |
inside the editor.<o:p></o:p></span></li> |
command objects, while still maintaining their individual strategies for |
| 683 |
<li class=MsoNormal style='mso-list:l22 level1 lfo3;tab-stops:list .5in'><span |
managing undo stacks or histories.<span style='mso-spacerun:yes'> |
| 684 |
style='font-size:10.0pt;font-family:Arial'>Edit>Undo causes reversal of |
</span>If there is a substantial investment in an existing model-based |
| 685 |
only the editor’s text-related changes that were caused by the <span |
operation or command framework, wrappers could be used to map IOperation |
| 686 |
class=SpellE>refactoring</span> operation.<span style='mso-spacerun:yes'> |
protocol to the existing protocol.<span style='mso-spacerun:yes'> |
| 687 |
</span>Thus, the text editing caused by the <span class=SpellE>refactor</span> |
</span>The commands/operations need not be assigned a context or added to |
| 688 |
is undone, but the <span class=SpellE>refactor</span> itself is not undone |
a common operation history.<span style='mso-spacerun:yes'> </span>This |
| 689 |
(this happens in R3.0.1).<o:p></o:p></span></li> |
level of integration allows command hierarchies built in different |
| 690 |
<li class=MsoNormal style='mso-list:l22 level1 lfo3;tab-stops:list .5in'><span |
frameworks to be treated the same by plug-ins that depend upon these different |
| 691 |
style='font-size:10.0pt;font-family:Arial'>Edit>Undo is unaware of the <span |
frameworks.<span style='mso-spacerun:yes'> </span>Clients of existing |
| 692 |
class=SpellE>refactoring</span> operation since it affected a context |
command frameworks may then use the workbench operation history, assign |
| 693 |
larger than the editor itself.<span style='mso-spacerun:yes'> </span>The |
contexts to operations as needed, and even add operations to the history, |
| 694 |
text operation that occurred before the <span class=SpellE>refactor</span> |
while still using commands built on earlier frameworks.<o:p></o:p></span></li> |
| 695 |
is undone. <o:p></o:p></span></li> |
<li class=MsoNormal style='mso-list:l8 level1 lfo8;tab-stops:list .5in'><span |
| 696 |
|
style='font-size:10.0pt;font-family:Arial'>Existing command/undo |
| 697 |
|
frameworks may use the listener interfaces provided by the operations |
| 698 |
|
history to listen for operations that are of interest.<span |
| 699 |
|
style='mso-spacerun:yes'> </span>These commands may be wrapped or |
| 700 |
|
otherwise recorded so that they can be undone from privately maintained |
| 701 |
|
undo implementations.<span style='mso-spacerun:yes'> </span>This level of |
| 702 |
|
integration allows views and editors to appear more tightly integrated |
| 703 |
|
with the operations framework, since workbench operations of interest can |
| 704 |
|
be undone or redone from private undo implementations.<o:p></o:p></span></li> |
| 705 |
|
<li class=MsoNormal style='mso-list:l8 level1 lfo8;tab-stops:list .5in'><span |
| 706 |
|
style='font-size:10.0pt;font-family:Arial'>Full integration is achieved by |
| 707 |
|
using the workbench operation history to record the undo and redo history |
| 708 |
|
as operations occur.<span style='mso-spacerun:yes'> </span>Once all |
| 709 |
|
plug-ins share an operation history, clients will be able to use unified |
| 710 |
|
listeners and handlers to track execution of operations, undo, and redo |
| 711 |
|
them.<span style='mso-spacerun:yes'> </span><o:p></o:p></span></li> |
| 712 |
</ol> |
</ol> |
| 713 |
|
|
| 714 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
| 715 |
|
|
| 716 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Examining |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Framework |
| 717 |
scenarios and the desired behavior shows that any one (or more) of the three |
interfaces will be defined in the org.eclipse.core.operations package.<span |
| 718 |
alternatives are desirable at different times, depending on what the user is |
style='mso-spacerun:yes'> </span>This package will be contained in a plug-in |
| 719 |
trying to achieve.<span style='mso-spacerun:yes'> </span>Appendix A collects |
that has no dependencies on the Eclipse runtime, so that raw JFace users may |
| 720 |
various <span class=SpellE>refactoring</span> and edit scenarios to help |
make use of it.<span style='mso-spacerun:yes'> </span>(The exact plug-in |
| 721 |
demonstrate the challenge.<o:p></o:p></span></p> |
containing the framework package is not defined at this time, as these packages |
| 722 |
|
may be combined with other packages that provide similar headless |
| 723 |
|
infrastructure.)<o:p></o:p></span></p> |
| 724 |
|
|
| 725 |
|
<h2>Framework interfaces</h2> |
| 726 |
|
|
| 727 |
|
<h3>IOperation</h3> |
| 728 |
|
|
| 729 |
|
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>IOperation |
| 730 |
|
defines an operation that can be executed, undone, and redone.<span |
| 731 |
|
style='mso-spacerun:yes'> </span>Operations typically have fully defined parameters. |
| 732 |
|
That is, they are usually created after the user has been queried for any input |
| 733 |
|
needed to define the operation.<o:p></o:p></span></p> |
| 734 |
|
|
| 735 |
<h3>Linear vs. selective undo<o:p></o:p></h3> |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
| 736 |
|
|
| 737 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>The |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Operations |
| 738 |
appearance of a simple Edit>Undo command in the UI typically implies a |
determine their ability to execute, undo, or redo according to the current |
| 739 |
linear undo.<span style='mso-spacerun:yes'> </span>That is, the most recent operation |
state of the application. They do not make decisions about their validity based |
| 740 |
executed is undone.<span style='mso-spacerun:yes'> </span>Descriptive undo |
on where they occur in the operation history. That is left to the particular |
| 741 |
labels (such as “Undo Typing” or “Undo Rename”) help to remind the user of the |
operation history.<o:p></o:p></span></p> |
|
last “undoable” operation.<o:p></o:p></span></p> |
|
| 742 |
|
|
| 743 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
| 744 |
|
|
| 745 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>As we’ve |
<pre>public void addContext(IOperationContext context)</pre> |
|
shown in discussing scopes and contexts, a strictly linear global undo is not |
|
|
the ideal behavior when working across contexts.<span |
|
|
style='mso-spacerun:yes'> </span>Once an attempt is made to choose the |
|
|
“appropriate” operation to be undone in the user’s current context, it’s |
|
|
possible that the chosen operation is not the most recently executed operation.<span |
|
|
style='mso-spacerun:yes'> </span>Decisions must be made about how to handle |
|
|
more recently executed operations.<span style='mso-spacerun:yes'> </span>A |
|
|
strictly linear model would force more recent operations to be undone before |
|
|
allowing the chosen operation to be undone.<o:p></o:p></span></p> |
|
| 746 |
|
|
| 747 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><span |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Add |
| 748 |
style='mso-spacerun:yes'> </span><o:p></o:p></span></p> |
the specified context to the operation. If the context is already present, do |
| 749 |
|
not add it again. <o:p></o:p></span></p> |
| 750 |
|
|
| 751 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>In a |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span |
| 752 |
selective undo approach, users are given an opportunity to view the history |
style='font-size:10.0pt'> <o:p></o:p></span></p> |
|
list and select the operation to be undone.<span style='mso-spacerun:yes'> |
|
|
</span>Operations that can be undone in the current state of the application |
|
|
are available for undo at any time, even if there are more recent operations in |
|
|
the history.<span style='mso-spacerun:yes'> </span><o:p></o:p></span></p> |
|
| 753 |
|
|
| 754 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>context</span></code><span |
| 755 |
|
style='font-size:10.0pt'> - - the context to be added<o:p></o:p></span></p> |
| 756 |
|
|
| 757 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>The |
<pre><a name="removeContext(org.eclipse.core.operation"></a>public void removeContext(IOperationContext context)</pre> |
|
workbench support should minimally be a hybrid of these approaches.<span |
|
|
style='mso-spacerun:yes'> </span>When the operation appropriate for one |
|
|
context is not the most recently executed one, then the user (by prompt or by |
|
|
preference) should have input into the decision to roll back any more recent operations |
|
|
or perform the undo selectively and retain the rest of the history list.<o:p></o:p></span></p> |
|
| 758 |
|
|
| 759 |
<h2>Proposed Undo Support<o:p></o:p></h2> |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Remove |
| 760 |
|
the specified context from the operation. This method has no effect if the |
| 761 |
|
context is not present. <o:p></o:p></span></p> |
| 762 |
|
|
| 763 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>While the |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span |
| 764 |
discussion and scenarios surrounding scopes and contexts have focused on the |
style='font-size:10.0pt'> <o:p></o:p></span></p> |
|
“hard cases,” it should be realized that most users will seek out “undo” in the |
|
|
simple cases.<span style='mso-spacerun:yes'> </span>Single context, strictly |
|
|
linear undo, particularly in text editing, is provided in most popular |
|
|
applications.<span style='mso-spacerun:yes'> </span>The availability of a more |
|
|
selective undo for the “hard cases” should not hinder the expected behavior of |
|
|
the simple cases. <o:p></o:p></span></p> |
|
| 765 |
|
|
| 766 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>context</span></code><span |
| 767 |
|
style='font-size:10.0pt'> - - the context to be removed<o:p></o:p></span></p> |
| 768 |
|
|
| 769 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Support for |
<pre><a name="hasContext(org.eclipse.core.operations.I"></a>public boolean <b>hasContext</b>(IOperationContext context)</pre> |
|
undo should be “pay as you go,” in terms of efficiency, burden on the user, and |
|
|
burden on the implementer.<span style='mso-spacerun:yes'> </span>Validation of |
|
|
operations in the history list against the current state of the application |
|
|
should be on demand, rather than forcing operation objects to watch the current |
|
|
state of the application and react to changes (even when the user might never |
|
|
choose “undo.”)<o:p></o:p></span></p> |
|
| 770 |
|
|
| 771 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Returns |
| 772 |
|
whether the operation has the specified context. <o:p></o:p></span></p> |
| 773 |
|
|
| 774 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Undo |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span |
| 775 |
support should not assume the presence of a user interface.<span |
style='font-size:10.0pt'> <o:p></o:p></span></p> |
|
style='mso-spacerun:yes'> </span>The operations history and associated |
|
|
interfaces can be defined independent of the UI.<o:p></o:p></span></p> |
|
| 776 |
|
|
| 777 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>context</span></code><span |
| 778 |
|
style='font-size:10.0pt'> - - the context in question <o:p></o:p></span></p> |
| 779 |
|
|
| 780 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>With these |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span |
| 781 |
goals in mind, the following implementation is proposed:<o:p></o:p></span></p> |
style='font-size:10.0pt'> <o:p></o:p></span></p> |
| 782 |
|
|
| 783 |
<h3>Operations Framework</h3> |
<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>true</span></code><span |
| 784 |
|
style='font-size:10.0pt'> if the context is present, </span><code><span |
| 785 |
|
style='font-size:10.0pt'>false</span></code><span style='font-size:10.0pt'> if |
| 786 |
|
it is not.<o:p></o:p></span></p> |
| 787 |
|
|
| 788 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>A framework |
<pre><a name="getContexts()"></a>public IOperationContext [] <b>getContexts</b>()</pre> |
|
for defining executable, undoable operations (<span class=SpellE>IOperation</span>) |
|
|
will be provided in a core package, <span class=SpellE>org.eclipse.core.operations</span>.<span |
|
|
style='mso-spacerun:yes'> </span>As actions are run, an object describing the |
|
|
operation to be performed is created, executed, and added to an operations history |
|
|
(<span class=SpellE>IOperationHistory</span>).<span style='mso-spacerun:yes'> |
|
|
</span>Operations which are comprised of distinct steps are represented as |
|
|
compound operations.<span style='mso-spacerun:yes'> </span>Compound operations |
|
|
must be executed as a unit, and can never be partially undone.<span |
|
|
style='mso-spacerun:yes'> </span><o:p></o:p></span></p> |
|
| 789 |
|
|
| 790 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Returns |
| 791 |
|
the array of contexts that have been assigned to the operation. <o:p></o:p></span></p> |
| 792 |
|
|
| 793 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Operations |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span |
| 794 |
can be assigned one or more contexts (<span class=SpellE>IOperationContext</span>) |
style='font-size:10.0pt'> <o:p></o:p></span></p> |
|
to which they apply.<span style='mso-spacerun:yes'> </span>The interface for operation |
|
|
contexts is left very general so that operation implementers may choose the |
|
|
appropriate representation for their contexts.<span style='mso-spacerun:yes'> |
|
|
</span>In some cases, a part-oriented context may be appropriate (an editor’s |
|
|
undo context is the editor part itself).<span style='mso-spacerun:yes'> |
|
|
</span>In other cases, a model object may serve as the context (the navigator’s |
|
|
context is the workspace). The interface leaves this to the discretion of the |
|
|
implementer and requires only that equality of contexts can be |
|
|
established.<span style='mso-spacerun:yes'> </span>User-appropriate labels and |
|
|
descriptions for operation contexts are required so that any filtered operation |
|
|
history views can appropriately label the contexts that are filtering the view.<o:p></o:p></span></p> |
|
| 795 |
|
|
| 796 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the |
| 797 |
|
array of contexts<o:p></o:p></span></p> |
| 798 |
|
|
| 799 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Contexts |
<pre><a name="canExecute()"></a>public boolean <b>canExecute</b>()</pre> |
|
can be assigned in multiple ways:<o:p></o:p></span></p> |
|
| 800 |
|
|
| 801 |
<p class=MsoNormal style='margin-left:39.0pt;text-indent:-.25in;mso-list:l23 level1 lfo24; |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Returns |
| 802 |
tab-stops:list 39.0pt'><![if !supportLists]><span style='font-size:10.0pt; |
whether the operation can be executed in its current state. <o:p></o:p></span></p> |
|
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>1.<span |
|
|
style='font:7.0pt "Times New Roman"'> </span></span></span><![endif]><span |
|
|
style='font-size:10.0pt;font-family:Arial'>When the triggering object knows the |
|
|
context of the operation, the context can be assigned up front.<span |
|
|
style='mso-spacerun:yes'> </span>For example, text operations are triggered by |
|
|
typing in the editor, and the editor can assign its context to the operation |
|
|
before adding it to the history.<span style='mso-spacerun:yes'> </span><o:p></o:p></span></p> |
|
| 803 |
|
|
| 804 |
<p class=MsoNormal style='margin-left:39.0pt;text-indent:-.25in;mso-list:l23 level1 lfo24; |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span |
| 805 |
tab-stops:list 39.0pt'><![if !supportLists]><span style='font-size:10.0pt; |
style='font-size:10.0pt'> <o:p></o:p></span></p> |
|
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>2.<span |
|
|
style='font:7.0pt "Times New Roman"'> </span></span></span><![endif]><span |
|
|
style='font-size:10.0pt;font-family:Arial'>Depending on the structure of the |
|
|
code, the object that creates the operation object may not know what context is |
|
|
appropriate, or if other contexts should be included.<span |
|
|
style='mso-spacerun:yes'> </span>In these cases, a listener can be added to |
|
|
the operations history.<span style='mso-spacerun:yes'> </span>When an operation |
|
|
is added to the history, listeners can decide if their context should be added |
|
|
to the operation.<span style='mso-spacerun:yes'> </span><o:p></o:p></span></p> |
|
| 806 |
|
|
| 807 |
<p class=MsoNormal style='margin-left:21.0pt'><span style='font-size:10.0pt; |
<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>true</span></code><span |
| 808 |
font-family:Arial'><o:p> </o:p></span></p> |
style='font-size:10.0pt'> if the operation can be executed; </span><code><span |
| 809 |
|
style='font-size:10.0pt'>false</span></code><span style='font-size:10.0pt'> |
| 810 |
|
otherwise.<o:p></o:p></span></p> |
| 811 |
|
|
| 812 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Representing |
<pre><a name="canRedo()"></a>public boolean <b>canRedo</b>()</pre> |
|
the contexts for an operation as a collection (empty graph) assumes that there |
|
|
is no inherent relationship between operation contexts.<span |
|
|
style='mso-spacerun:yes'> </span>This allows the most flexibility in defining |
|
|
contexts.<span style='mso-spacerun:yes'> </span>For example, an editor may perform |
|
|
an operation that affects both the editor’s document and the workspace at |
|
|
large.<span style='mso-spacerun:yes'> </span>These will be considered two |
|
|
independent contexts and assigned to the operation.<span |
|
|
style='mso-spacerun:yes'> </span>One could argue that the context for the |
|
|
document is simply a refinement of the workspace context, and that a |
|
|
hierarchical relationship between those contexts should exist.<span |
|
|
style='mso-spacerun:yes'> </span>Without more use cases, we avoid establishing |
|
|
any relationship between contexts at this time<o:p></o:p></span></p> |
|
| 813 |
|
|
| 814 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Returns |
| 815 |
|
whether the operation can be redone in its current state. <o:p></o:p></span></p> |
| 816 |
|
|
| 817 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Operation contexts |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span |
| 818 |
that are used when manipulating well-known models should be accessible by |
style='font-size:10.0pt'> <o:p></o:p></span></p> |
|
API.<span style='mso-spacerun:yes'> </span>This can be done in multiple ways:<o:p></o:p></span></p> |
|
| 819 |
|
|
| 820 |
<ol style='margin-top:0in' start=1 type=1> |
<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>true</span></code><span |
| 821 |
<li class=MsoNormal style='mso-list:l20 level1 lfo25;tab-stops:list .5in'><span |
style='font-size:10.0pt'> if the operation can be redone; </span><code><span |
| 822 |
style='font-size:10.0pt;font-family:Arial'>API for obtaining a context can |
style='font-size:10.0pt'>false</span></code><span style='font-size:10.0pt'> |
| 823 |
be added in the same place where the associated model can be |
otherwise.<o:p></o:p></span></p> |
|
obtained.<span style='mso-spacerun:yes'> </span>For example, an editor |
|
|
can provide both the document and the context for performing operations on |
|
|
the document as API.<o:p></o:p></span></li> |
|
|
<li class=MsoNormal style='mso-list:l20 level1 lfo25;tab-stops:list .5in'><span |
|
|
style='font-size:10.0pt;font-family:Arial'>Contexts that are related |
|
|
directly to certain preexisting platform objects can be obtained using an |
|
|
adapter on that object.<span style='mso-spacerun:yes'> </span>For |
|
|
example, the workbench could add an operation context adapter factory for |
|
|
the workspace.<span style='mso-spacerun:yes'> </span>Clients could |
|
|
retrieve this adapter using context=<span class=SpellE>workspace.getAdapter</span>(<span |
|
|
class=SpellE>IOperationContext.class</span>);<o:p></o:p></span></li> |
|
|
</ol> |
|
| 824 |
|
|
| 825 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<pre><a name="canUndo()"></a>public boolean <b>canUndo</b>()</pre> |
| 826 |
|
|
| 827 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>The |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Returns |
| 828 |
following interfaces represent the operation, the operation history, and the operation |
whether the operation can be undone in its current state. <o:p></o:p></span></p> |
|
context.<o:p></o:p></span></p> |
|
| 829 |
|
|
| 830 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span |
| 831 |
|
style='font-size:10.0pt'> <o:p></o:p></span></p> |
| 832 |
|
|
| 833 |
<p class=MsoNormal style='tab-stops:.5in 189.0pt'><span style='font-size:10.0pt; |
<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>true</span></code><span |
| 834 |
font-family:Arial'>public interface <span class=SpellE>IOperation</span> {<o:p></o:p></span></p> |
style='font-size:10.0pt'> if the operation can be undone; </span><code><span |
| 835 |
|
style='font-size:10.0pt'>false</span></code><span style='font-size:10.0pt'> |
| 836 |
|
otherwise.<o:p></o:p></span></p> |
| 837 |
|
|
| 838 |
<p class=MsoNormal style='tab-stops:.5in 189.0pt'><span style='font-size:10.0pt; |
<pre><a name="execute(org.eclipse.core.runtime.IProgre"></a>public org.eclipse.core.runtime.IStatus <b>execute</b>(org.eclipse.core.runtime.IProgressMonitor monitor)</pre> |
|
font-family:Arial'>void <span class=SpellE>addContext</span>(<span |
|
|
class=SpellE>IOperationContext</span>);<span style='mso-tab-count:1'> </span>// |
|
|
add the context to the operation’s contexts<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='tab-stops:.5in 189.0pt'><span class=SpellE><span |
|
|
style='font-size:10.0pt;font-family:Arial'>boolean</span></span><span |
|
|
style='font-size:10.0pt;font-family:Arial'> <span class=SpellE>hasContext</span>(<span |
|
|
class=SpellE>IOperationContext</span>);<span style='mso-tab-count:1'> </span>//answer |
|
|
whether the receiver’s contexts contain the context<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='tab-stops:.5in 189.0pt'><span style='font-size:10.0pt; |
|
|
font-family:Arial'>List <span class=SpellE>getContexts</span>();<span |
|
|
style='mso-tab-count:1'> </span>// answer |
|
|
the list of contexts assigned to the receiver.<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='tab-stops:.5in 189.0pt'><span class=SpellE><span |
|
|
style='font-size:10.0pt;font-family:Arial'>IStatus</span></span><span |
|
|
style='font-size:10.0pt;font-family:Arial'> <span class=SpellE>canExecute</span>();<span |
|
|
style='mso-tab-count:1'> </span>// answer whether |
|
|
the receiver can be executed<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='tab-stops:.5in 189.0pt'><span class=SpellE><span |
|
|
style='font-size:10.0pt;font-family:Arial'>IStatus</span></span><span |
|
|
style='font-size:10.0pt;font-family:Arial'> <span class=SpellE>canRedo</span>();<span |
|
|
style='mso-tab-count:1'> </span>// answer |
|
|
whether the receiver can be redone<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='tab-stops:.5in 189.0pt'><span class=SpellE><span |
|
|
style='font-size:10.0pt;font-family:Arial'>IStatus</span></span><span |
|
|
style='font-size:10.0pt;font-family:Arial'> <span class=SpellE>canUndo</span>();<span |
|
|
style='mso-tab-count:1'> </span>// answer |
|
|
whether the receiver can be undone<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='tab-stops:.5in 189.0pt'><span style='font-size:10.0pt; |
|
|
font-family:Arial'>void execute(<span class=SpellE>IProgressMonitor</span>);<span |
|
|
style='mso-tab-count:1'> </span>// execute the operation <o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='tab-stops:.5in 189.0pt'><span style='font-size:10.0pt; |
|
|
font-family:Arial'>void redo(<span class=SpellE>IProgressMonitor</span>);<span |
|
|
style='mso-tab-count:1'> </span>// redo the operation<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='tab-stops:.5in 189.0pt'><span style='font-size:10.0pt; |
|
|
font-family:Arial'>void undo(<span class=SpellE>IProgressMonitor</span>);<span |
|
|
style='mso-tab-count:1'> </span>// undo the operation<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='tab-stops:.5in 189.0pt'><span style='font-size:10.0pt; |
|
|
font-family:Arial'>void dispose();<span style='mso-tab-count:1'> </span>// |
|
|
the operation is no longer needed<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='tab-stops:.5in 189.0pt'><span style='font-size:10.0pt; |
|
|
font-family:Arial'>String <span class=SpellE>getLabel</span>();<span |
|
|
style='mso-tab-count:1'> </span>// provide |
|
|
a label to name this operation for the user<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='tab-stops:.5in 189.0pt'><span style='font-size:10.0pt; |
|
|
font-family:Arial'>String <span class=SpellE>getDescription</span>();<span |
|
|
style='mso-tab-count:1'> </span>// provide a |
|
|
description of this operation for the user<o:p></o:p></span></p> |
|
| 839 |
|
|
| 840 |
<p class=MsoNormal style='tab-stops:.5in 189.0pt'><span style='font-size:10.0pt; |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Execute |
| 841 |
font-family:Arial'>}<o:p></o:p></span></p> |
the operation. This method should only be called the first time that an |
| 842 |
|
operation is executed. <o:p></o:p></span></p> |
| 843 |
|
|
| 844 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><span |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span |
| 845 |
style='mso-tab-count:1'> </span><o:p></o:p></span></p> |
style='font-size:10.0pt'> <o:p></o:p></span></p> |
| 846 |
|
|
| 847 |
<p class=MsoNormal style='tab-stops:.5in .75in 207.0pt 3.5in 297.0pt 4.75in'><span |
<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>monitor</span></code><span |
| 848 |
style='font-size:10.0pt;font-family:Arial'>public interface <span class=SpellE>IOperationHistory</span> |
style='font-size:10.0pt'> - <o:p></o:p></span></p> |
|
{<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='tab-stops:.5in .75in 207.0pt 3.5in 297.0pt 4.75in'><span |
|
|
style='font-size:10.0pt;font-family:Arial'>void add(<span class=SpellE>IOperation</span>);<span |
|
|
style='mso-tab-count:1'> </span>// add |
|
|
the specified operation to the history<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='tab-stops:.5in .75in 207.0pt 3.5in 297.0pt 4.75in'><span |
|
|
style='font-size:10.0pt;font-family:Arial'>void redo(<span class=SpellE>IOperationContext</span>, |
|
|
<span class=SpellE>IProgressMonitor</span>);<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='tab-stops:.5in .75in 207.0pt 3.5in 297.0pt 4.75in'><span |
|
|
style='font-size:10.0pt;font-family:Arial'><span style='mso-tab-count:1'> </span>// |
|
|
perform the redo operation for the given context<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='tab-stops:.5in .75in 207.0pt 3.5in 297.0pt 4.75in'><span |
|
|
style='font-size:10.0pt;font-family:Arial'>void undo(<span class=SpellE>IOperationContext</span>, |
|
|
<span class=SpellE>IProgressMonitor</span>);<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='tab-stops:.5in .75in 207.0pt 3.5in 297.0pt 4.75in'><span |
|
|
style='font-size:10.0pt;font-family:Arial'><span style='mso-tab-count:1'> </span>// |
|
|
perform the undo operation appropriate for the given context.<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='tab-stops:.5in .75in 207.0pt 3.5in 297.0pt 4.75in'><span |
|
|
class=SpellE><span style='font-size:10.0pt;font-family:Arial'>IStatus</span></span><span |
|
|
style='font-size:10.0pt;font-family:Arial'> <span class=SpellE>canRedoIn</span>(<span |
|
|
class=SpellE>IOperationContext</span>);<span style='mso-tab-count:1'> </span>// |
|
|
answer whether redo is available in the given context<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='tab-stops:.5in .75in 207.0pt 3.5in 297.0pt 4.75in'><span |
|
|
class=SpellE><span style='font-size:10.0pt;font-family:Arial'>IStatus</span></span><span |
|
|
style='font-size:10.0pt;font-family:Arial'> <span class=SpellE>canUndoIn</span>(<span |
|
|
class=SpellE>IOperationContext</span>);<span style='mso-tab-count:1'> </span>// |
|
|
answer whether undo is available in the given context<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='tab-stops:.5in .75in 207.0pt 3.5in 297.0pt 4.75in'><span |
|
|
style='font-size:10.0pt;font-family:Arial'>void <span class=SpellE>addOperationHistoryListener</span>(<span |
|
|
class=SpellE>IOperationHistoryListener</span>);<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='tab-stops:.5in .75in 207.0pt 3.5in 297.0pt 4.75in'><span |
|
|
style='font-size:10.0pt;font-family:Arial'><span style='mso-tab-count:1'> </span>// |
|
|
add a listener for changes to the operation history<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='tab-stops:.5in .75in 207.0pt 3.5in 297.0pt 4.75in'><span |
|
|
style='font-size:10.0pt;font-family:Arial'>void <span class=SpellE>removeOperationHistoryListener</span>(<span |
|
|
class=SpellE>IOperationHistoryListener</span>);<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='tab-stops:.5in .75in 207.0pt 3.5in 297.0pt 4.75in'><span |
|
|
style='font-size:10.0pt;font-family:Arial'><span style='mso-tab-count:1'> </span>// |
|
|
remove the specified history listener from the receiver.<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='tab-stops:.5in .75in 207.0pt 3.5in 297.0pt 4.75in'><span |
|
|
class=SpellE><span style='font-size:10.0pt;font-family:Arial'>IOperation</span></span><span |
|
|
style='font-size:10.0pt;font-family:Arial'> <span class=SpellE>getRedoFor</span>(<span |
|
|
class=SpellE>IOperationContext</span>);<span style='mso-tab-count:1'> </span>// |
|
|
get the redo operation for the given context<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='tab-stops:.5in .75in 207.0pt 3.5in 297.0pt 4.75in'><span |
|
|
class=SpellE><span style='font-size:10.0pt;font-family:Arial'>IOperation</span></span><span |
|
|
style='font-size:10.0pt;font-family:Arial'> [] <span class=SpellE>getRedoHistoryFor</span>(<span |
|
|
class=SpellE>IOperationContext</span>);<span style='mso-spacerun:yes'> </span>// |
|
|
answer the redo history list for the given context<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='tab-stops:.5in .75in 207.0pt 3.5in 297.0pt 4.75in'><span |
|
|
class=SpellE><span style='font-size:10.0pt;font-family:Arial'>IOperation</span></span><span |
|
|
style='font-size:10.0pt;font-family:Arial'> <span class=SpellE>getUndoFor</span>(<span |
|
|
class=SpellE>IOperationContext</span>);<span style='mso-tab-count:1'> </span>// |
|
|
answer the undo operation for the given context<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='tab-stops:.5in .75in 207.0pt 3.5in 297.0pt 4.75in'><span |
|
|
class=SpellE><span style='font-size:10.0pt;font-family:Arial'>IOperation</span></span><span |
|
|
style='font-size:10.0pt;font-family:Arial'> [] <span class=SpellE>getUndoHistoryFor</span>(<span |
|
|
class=SpellE>IOperationContext</span>);<span style='mso-spacerun:yes'> </span>// |
|
|
answer the undo history list for the given context<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='tab-stops:.5in .75in 207.0pt 3.5in 297.0pt 4.75in'><span |
|
|
style='font-size:10.0pt;font-family:Arial'>void <span class=SpellE>disposeAll</span>(<span |
|
|
class=SpellE>IOperationContext</span>);<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='tab-stops:.5in .75in 207.0pt 3.5in 297.0pt 4.75in'><span |
|
|
style='font-size:10.0pt;font-family:Arial'><span style='mso-tab-count:1'> </span>// |
|
|
Remove all operations that have only the specified context.<span |
|
|
style='mso-spacerun:yes'> </span>Implementers must<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='tab-stops:.5in .75in 207.0pt 3.5in 297.0pt 4.75in'><span |
|
|
style='font-size:10.0pt;font-family:Arial'><span style='mso-tab-count:1'> </span>// |
|
|
determine how to handle operations that have additional contexts.<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='tab-stops:.5in .75in 207.0pt 3.5in 297.0pt 4.75in'><span |
|
|
style='font-size:10.0pt;font-family:Arial'>void <span class=SpellE>setLimit</span>(<span |
|
|
class=SpellE>int</span>);<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='tab-stops:.5in .75in 207.0pt 3.5in 297.0pt 4.75in'><span |
|
|
style='font-size:10.0pt;font-family:Arial'><span style='mso-tab-count:1'> </span>// |
|
|
set a limit on the operation history.<span style='mso-spacerun:yes'> |
|
|
</span>When the limit is reached, the oldest operation <o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='tab-stops:.5in .75in 207.0pt 3.5in 297.0pt 4.75in'><span |
|
|
style='font-size:10.0pt;font-family:Arial'><span style='mso-tab-count:1'> </span>// |
|
|
will be disposed to make room for new operations.<o:p></o:p></span></p> |
|
| 849 |
|
|
| 850 |
<p class=MsoNormal style='tab-stops:.75in 207.0pt'><span style='font-size:10.0pt; |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span |
| 851 |
font-family:Arial'>}<o:p></o:p></span></p> |
style='font-size:10.0pt'> <o:p></o:p></span></p> |
| 852 |
|
|
| 853 |
<p class=MsoNormal style='tab-stops:.75in 207.0pt'><span style='font-size:10.0pt; |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the |
| 854 |
font-family:Arial'><o:p> </o:p></span></p> |
IStatus of the execution. The status severity should be set to </span><code><span |
| 855 |
|
style='font-size:10.0pt'>OK</span></code><span style='font-size:10.0pt'> if the |
| 856 |
|
operation was successful, and </span><code><span style='font-size:10.0pt'>ERROR</span></code><span |
| 857 |
|
style='font-size:10.0pt'> if it was not. Any other status is assumed to |
| 858 |
|
represent an incompletion of the execution.<o:p></o:p></span></p> |
| 859 |
|
|
| 860 |
<p class=MsoNormal style='tab-stops:207.0pt'><span style='font-size:10.0pt; |
<pre><a name="redo(org.eclipse.core.runtime.IProgressM"></a>public org.eclipse.core.runtime.IStatus <b>redo</b>(org.eclipse.core.runtime.IProgressMonitor monitor)</pre> |
|
font-family:Arial'>public interface <span class=SpellE>IOperationHistoryListener</span> |
|
|
{<o:p></o:p></span></p> |
|
| 861 |
|
|
| 862 |
<p class=MsoNormal style='tab-stops:207.0pt'><span style='font-size:10.0pt; |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Redo |
| 863 |
font-family:Arial'>void <span class=SpellE>operationAdded</span>(<span |
the operation. This method should only be called after an operation has been |
| 864 |
class=SpellE>IOperation</span>);<span style='mso-tab-count:1'> </span>// |
undone. <o:p></o:p></span></p> |
|
an operation has been added to the history<o:p></o:p></span></p> |
|
| 865 |
|
|
| 866 |
<p class=MsoNormal style='tab-stops:207.0pt'><span style='font-size:10.0pt; |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span |
| 867 |
font-family:Arial'>void <span class=SpellE>aboutToUndo</span>(<span |
style='font-size:10.0pt'> <o:p></o:p></span></p> |
|
class=SpellE>IOperation</span>);<span style='mso-tab-count:1'> </span>// |
|
|
the operation is about to be undone<o:p></o:p></span></p> |
|
| 868 |
|
|
| 869 |
<p class=MsoNormal style='tab-stops:207.0pt'><span style='font-size:10.0pt; |
<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>monitor</span></code><span |
| 870 |
font-family:Arial'>void undone(<span class=SpellE>IOperation</span>);<span |
style='font-size:10.0pt'> - <o:p></o:p></span></p> |
|
style='mso-tab-count:1'> </span>// the |
|
|
operation was undone<o:p></o:p></span></p> |
|
| 871 |
|
|
| 872 |
<p class=MsoNormal style='tab-stops:207.0pt'><span style='font-size:10.0pt; |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span |
| 873 |
font-family:Arial'>void <span class=SpellE>aboutToRedo</span>(<span |
style='font-size:10.0pt'> <o:p></o:p></span></p> |
|
class=SpellE>IOperation</span>);<span style='mso-tab-count:1'> </span>// |
|
|
the operation is about to be redone<o:p></o:p></span></p> |
|
| 874 |
|
|
| 875 |
<p class=MsoNormal style='tab-stops:207.0pt'><span style='font-size:10.0pt; |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the |
| 876 |
font-family:Arial'>void redone(<span class=SpellE>IOperation</span>);<span |
IStatus of the redo. The status severity should be set to </span><code><span |
| 877 |
style='mso-tab-count:1'> </span>// the |
style='font-size:10.0pt'>OK</span></code><span style='font-size:10.0pt'> if the |
| 878 |
operation was redone<o:p></o:p></span></p> |
redo was successful, and </span><code><span style='font-size:10.0pt'>ERROR</span></code><span |
| 879 |
|
style='font-size:10.0pt'> if it was not. Any other status is assumed to |
| 880 |
|
represent an incompletion of the redo.<o:p></o:p></span></p> |
| 881 |
|
|
| 882 |
<p class=MsoNormal style='tab-stops:207.0pt'><span style='font-size:10.0pt; |
<pre>public org.eclipse.core.runtime.IStatus <b>undo</b>(org.eclipse.core.runtime.IProgressMonitor monitor)</pre> |
|
font-family:Arial'>}<o:p></o:p></span></p> |
|
| 883 |
|
|
| 884 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Undo |
| 885 |
|
the operation. This method should only be called after an operation has been |
| 886 |
|
executed. <o:p></o:p></span></p> |
| 887 |
|
|
| 888 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>public |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span |
| 889 |
interface <span class=SpellE>IOperationContext</span> {<o:p></o:p></span></p> |
style='font-size:10.0pt'> <o:p></o:p></span></p> |
| 890 |
|
|
| 891 |
<p class=MsoNormal><span class=SpellE><span style='font-size:10.0pt;font-family: |
<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>monitor</span></code><span |
| 892 |
Arial'>IOperationApproval</span></span><span style='font-size:10.0pt; |
style='font-size:10.0pt'> - <o:p></o:p></span></p> |
|
font-family:Arial'> <span class=SpellE>getOperationApproval</span>();<o:p></o:p></span></p> |
|
| 893 |
|
|
| 894 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>String <span |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span |
| 895 |
class=SpellE>getDescription</span>();<o:p></o:p></span></p> |
style='font-size:10.0pt'> <o:p></o:p></span></p> |
| 896 |
|
|
| 897 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>String <span |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the |
| 898 |
class=SpellE>getLabel</span>();<o:p></o:p></span></p> |
IStatus of the undo. The status severity should be set to </span><code><span |
| 899 |
|
style='font-size:10.0pt'>OK</span></code><span style='font-size:10.0pt'> if the |
| 900 |
|
redo was successful, and </span><code><span style='font-size:10.0pt'>ERROR</span></code><span |
| 901 |
|
style='font-size:10.0pt'> if it was not. Any other status is assumed to |
| 902 |
|
represent an incompletion of the undo.<o:p></o:p></span></p> |
| 903 |
|
|
| 904 |
<p class=MsoNormal><span class=SpellE><span style='font-size:10.0pt;font-family: |
<pre>public void <b>dispose</b>()</pre> |
|
Arial'>boolean</span></span><span style='font-size:10.0pt;font-family:Arial'> |
|
|
equals(<span class=SpellE>IOperationContext</span>);<o:p></o:p></span></p> |
|
| 905 |
|
|
| 906 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>}<o:p></o:p></span></p> |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Dispose |
| 907 |
|
of the operation. This method is used when the operation is no longer kept in |
| 908 |
|
the history. Implementers of this method typically unregister any listeners. <o:p></o:p></span></p> |
| 909 |
|
|
| 910 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<pre>public java.lang.String <b>getLabel</b>()</pre> |
| 911 |
|
|
| 912 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>public |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Return |
| 913 |
interface <span class=SpellE>IOperationApproval</span> {<o:p></o:p></span></p> |
the label that should be used to show the name of the operation to the user. |
| 914 |
|
This label is typically appended to the "Undo" or "Redo" |
| 915 |
|
menu entry. <o:p></o:p></span></p> |
| 916 |
|
|
| 917 |
<p class=MsoNormal><span class=SpellE><span style='font-size:10.0pt;font-family: |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span |
| 918 |
Arial'>boolean</span></span><span style='font-size:10.0pt;font-family:Arial'> <span |
style='font-size:10.0pt'> <o:p></o:p></span></p> |
|
class=SpellE>proceedUndoing</span>(<span class=SpellE>IOperation</span>);<o:p></o:p></span></p> |
|
| 919 |
|
|
| 920 |
<p class=MsoNormal><span class=SpellE><span style='font-size:10.0pt;font-family: |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the |
| 921 |
Arial'>boolean</span></span><span style='font-size:10.0pt;font-family:Arial'> <span |
label<o:p></o:p></span></p> |
|
class=SpellE>proceedRedoing</span>(<span class=SpellE>IOperation</span>);<o:p></o:p></span></p> |
|
| 922 |
|
|
| 923 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>}<o:p></o:p></span></p> |
<pre>public java.lang.String <b>getDescription</b>()</pre> |
| 924 |
|
|
| 925 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Return |
| 926 |
|
the description that should be used to further describe this operation to the |
| 927 |
|
user. The description is used in history lists when the user requests more |
| 928 |
|
information about an operation. <o:p></o:p></span></p> |
| 929 |
|
|
| 930 |
|
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span |
| 931 |
|
style='font-size:10.0pt'> <o:p></o:p></span></p> |
| 932 |
|
|
| 933 |
|
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the |
| 934 |
|
description<o:p></o:p></span></p> |
| 935 |
|
|
| 936 |
|
<h3>IOperationHistory</h3> |
| 937 |
|
|
| 938 |
|
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>IOperationHistory |
| 939 |
|
tracks a history of operations that can be undone or redone. Operations are |
| 940 |
|
added to the history once they have been initially executed. Clients may choose |
| 941 |
|
whether to have the operations history perform the initial execution or simply |
| 942 |
|
add the operation to the history. Once operations are added to the history, the |
| 943 |
|
methods canRedo() and canUndo() are used to determine whether there is an |
| 944 |
|
operation available for undo and redo in a given operation context.<span |
| 945 |
|
style='mso-spacerun:yes'> </span>The context-based protocol implies that there |
| 946 |
|
is only one operation that can be undone or redone at a given time in a given |
| 947 |
|
context. This is typical of a linear undo model, when only the most recently |
| 948 |
|
executed operation is available for undo. When this protocol is used, a linear |
| 949 |
|
model is enforced by the history. It is up to clients to determine how to |
| 950 |
|
maintain a history that is invalid or stale. For example, when the most recent |
| 951 |
|
operation for a context cannot be performed, clients may wish to flush the |
| 952 |
|
history for that context.<o:p></o:p></span></p> |
| 953 |
|
|
| 954 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
| 955 |
|
|
| 956 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>An |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Additional |
| 957 |
operation is responsible for validating its ability to execute and undo against |
protocol allows direct undo and redo of a specified operation, regardless of |
| 958 |
the current state of the application.<span style='mso-spacerun:yes'> |
its position in the history. When a more flexible undo model is supported, |
| 959 |
</span>Validation may be requested even when an operation is not the most |
these methods can be implemented to undo and redo directly specified |
| 960 |
recently executed operation (or most recently undone operation).<span |
operations. If an implementer of IOperationHistory does not allow direct undo |
| 961 |
style='mso-spacerun:yes'> </span>This is important since operations in |
and redo, these methods can return a status indicating that it is not allowed.<o:p></o:p></span></p> |
|
unrelated contexts may coexist in the same history unaware of one another’s |
|
|
existence.<span style='mso-spacerun:yes'> </span><o:p></o:p></span></p> |
|
| 962 |
|
|
| 963 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
| 964 |
|
|
| 965 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>As |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Listeners |
| 966 |
operations are executed, they are added to the operation history.<span |
(IOperationHistoryListener) can listen for notifications about changes in the |
| 967 |
style='mso-spacerun:yes'> </span>Note that the operation history does not necessarily |
history (operations added or removed), and for notification before and after |
| 968 |
perform the initial execution, but rather assumes the operation is already |
any operation is executed, undone or redone. Notification of operation |
| 969 |
executed before it is added to the history.<span style='mso-spacerun:yes'> |
execution only occurs when clients direct the history to execute the operation. |
| 970 |
</span>This is necessary for text editing operations, where the operations are |
If the operation is added after it is executed, there can be no notification of |
| 971 |
happening as the user types and the recording/batching of operations for the |
its execution.<o:p></o:p></span></p> |
|
history occur afterwards.<span style='mso-spacerun:yes'> </span><o:p></o:p></span></p> |
|
| 972 |
|
|
| 973 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
| 974 |
|
|
| 975 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>The operation |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>IOperationApprover |
| 976 |
history is responsible for implementing the application’s undo model, and the |
defines an interface for approving an undo or redo before it occurs. This is |
| 977 |
decisions about handling multiple contexts.<span style='mso-spacerun:yes'> |
useful for injecting policy-decisions into the model - whether direct undo and |
| 978 |
</span>If an application chooses to implement a strictly linear, global undo, |
redo are supported, or warning the user about certain kinds of operations. It |
| 979 |
then its implementation of <span class=SpellE>IOperationHistory</span> can |
can also be used when objects have state related to the operation and need to |
| 980 |
ensure that requests to perform undo or redo in a particular context will fail |
determine whether an undo or redo will cause any conflicts with their local |
| 981 |
if the most recent operation does not have that context.<o:p></o:p></span></p> |
state.<o:p></o:p></span></p> |
| 982 |
|
|
| 983 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
| 984 |
|
|
| 985 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>More |
<pre>public void <b>add</b>(IOperation operation)</pre> |
|
flexible undo models may be implemented with the assistance of the <span |
|
|
class=SpellE>IOperationApproval</span> that is assigned to an operation context.<span |
|
|
style='mso-spacerun:yes'> </span>This interface allows other contexts to be |
|
|
consulted when an operation is to be executed or undone.<span |
|
|
style='mso-spacerun:yes'> </span>The undo model defined by the operation |
|
|
history determines when to consult the <span class=SpellE>IOperationApproval</span>.<span |
|
|
style='mso-spacerun:yes'> </span>Possible implementations will be discussed in |
|
|
more detail in the workbench scenarios.<span style='mso-spacerun:yes'> </span><o:p></o:p></span></p> |
|
| 986 |
|
|
| 987 |
<h3>Workbench Undo Semantics</h3> |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Add |
| 988 |
|
the specified operation to the history without executing it. The operation |
| 989 |
|
should have already been executed by the time it is added to the history. |
| 990 |
|
Listeners will be notified that the operation was added to the history. <o:p></o:p></span></p> |
| 991 |
|
|
| 992 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>The |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span |
| 993 |
workbench will adopt a hybrid undo approach that allows selective undo across |
style='font-size:10.0pt'> <o:p></o:p></span></p> |
|
multiple contexts.<span style='mso-spacerun:yes'> </span>The workbench will |
|
|
allow undo/redo of any valid operation in the history, <i style='mso-bidi-font-style: |
|
|
normal'>as long as there are no more recent operations in the history that |
|
|
share a context with the operation to be executed.</i><span |
|
|
style='mso-spacerun:yes'> </span><span style='mso-spacerun:yes'> </span>If the |
|
|
operation to be undone/redone has contexts that are also present in operations appearing |
|
|
later in the history, then the <span class=SpellE>IOperationApproval</span> for |
|
|
the contexts that have the conflicts will be consulted.<span |
|
|
style='mso-spacerun:yes'> </span><o:p></o:p></span></p> |
|
| 994 |
|
|
| 995 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>operation</span></code><span |
| 996 |
|
style='font-size:10.0pt'> - - the operation to be added to the history<o:p></o:p></span></p> |
| 997 |
|
|
| 998 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>A concrete |
<pre>public org.eclipse.core.runtime.IStatus <b>execute</b>(IOperation operation,</pre><pre><span style='mso-spacerun:yes'> </span>org.eclipse.core.runtime.IProgressMonitor monitor)</pre> |
|
example will help explain this.<span style='mso-spacerun:yes'> </span><o:p></o:p></span></p> |
|
| 999 |
|
|
| 1000 |
<p class=MsoNormal style='margin-left:.5in;text-indent:-.25in;mso-list:l21 level1 lfo1; |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Execute |
| 1001 |
tab-stops:list .5in'><![if !supportLists]><span style='font-size:10.0pt; |
the specified operation and add it to the operations history if successful. This |
| 1002 |
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>-<span |
method is used by clients who wish operation history listeners to receive |
| 1003 |
style='font:7.0pt "Times New Roman"'> |
notifications before and after the execution of the operation. Listeners will |
| 1004 |
</span></span></span><![endif]><span style='font-size:10.0pt;font-family:Arial'>The |
be notified before ( </span><code><span style='font-size:10.0pt'>aboutToExecute</span></code><span |
| 1005 |
user makes local edits in editor A.<o:p></o:p></span></p> |
style='font-size:10.0pt'>) and after (</span><code><span style='font-size:10.0pt'>done</span></code><span |
| 1006 |
|
style='font-size:10.0pt'> or </span><code><span style='font-size:10.0pt'>operationNotOK</span></code><span |
| 1007 |
<p class=MsoNormal style='margin-left:.5in;text-indent:-.25in;mso-list:l21 level1 lfo1; |
style='font-size:10.0pt'>). If the operation successfully executes, an |
| 1008 |
tab-stops:list .5in'><![if !supportLists]><span style='font-size:10.0pt; |
additional notification that the operation has been added to the history (</span><code><span |
| 1009 |
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>-<span |
style='font-size:10.0pt'>operationAdded</span></code><span style='font-size: |
| 1010 |
style='font:7.0pt "Times New Roman"'> |
10.0pt'>) will be sent. <o:p></o:p></span></p> |
|
</span></span></span><![endif]><span style='font-size:10.0pt;font-family:Arial'>The |
|
|
user initiates a <span class=SpellE>refactoring</span> operation whose context |
|
|
is “A” and “workspace.”<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='margin-left:.5in;text-indent:-.25in;mso-list:l21 level1 lfo1; |
|
|
tab-stops:list .5in'><![if !supportLists]><span style='font-size:10.0pt; |
|
|
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>-<span |
|
|
style='font:7.0pt "Times New Roman"'> |
|
|
</span></span></span><![endif]><span style='font-size:10.0pt;font-family:Arial'>The |
|
|
user makes additional local edits to editor A.<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='margin-left:.5in;text-indent:-.25in;mso-list:l21 level1 lfo1; |
|
|
tab-stops:list .5in'><![if !supportLists]><span style='font-size:10.0pt; |
|
|
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>-<span |
|
|
style='font:7.0pt "Times New Roman"'> |
|
|
</span></span></span><![endif]><span style='font-size:10.0pt;font-family:Arial'>The |
|
|
user goes to the navigator and selects Undo.<o:p></o:p></span></p> |
|
| 1011 |
|
|
| 1012 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span |
| 1013 |
|
style='font-size:10.0pt'> <o:p></o:p></span></p> |
| 1014 |
|
|
| 1015 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>In the |
<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>operation</span></code><span |
| 1016 |
proposed implementation, the navigator would request an undo for the context |
style='font-size:10.0pt'> - - the operation to be executed and then added to |
| 1017 |
“workspace.”<span style='mso-spacerun:yes'> </span>The <span class=SpellE>refactoring</span> |
the history <o:p></o:p></span></p> |
|
operation triggered in the editor is the most recent operation that has the |
|
|
workspace context, but it also contains context “A.”<span |
|
|
style='mso-spacerun:yes'> </span>Since subsequent operations in the history |
|
|
also have context “A,”, the <span class=SpellE>IOperationApproval</span> for |
|
|
context “A” is consulted as to whether the undo should proceed.<span |
|
|
style='mso-spacerun:yes'> </span>The <span class=SpellE>IOperationApproval</span> |
|
|
<span style='mso-spacerun:yes'> </span>supplied by context “A” could do one of |
|
|
the following:<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='margin-left:.5in;text-indent:-.25in;mso-list:l21 level1 lfo1; |
|
|
tab-stops:list .5in'><![if !supportLists]><span style='font-size:10.0pt; |
|
|
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>-<span |
|
|
style='font:7.0pt "Times New Roman"'> |
|
|
</span></span></span><![endif]><span style='font-size:10.0pt;font-family:Arial'>allow |
|
|
the undo to proceed, leaving the local changes to “A” in the undo history.<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='margin-left:.5in;text-indent:-.25in;mso-list:l21 level1 lfo1; |
|
|
tab-stops:list .5in'><![if !supportLists]><span style='font-size:10.0pt; |
|
|
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>-<span |
|
|
style='font:7.0pt "Times New Roman"'> |
|
|
</span></span></span><![endif]><span style='font-size:10.0pt;font-family:Arial'>quietly |
|
|
undo the subsequent local changes to “A” and then allow the original undo to |
|
|
proceed.<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='margin-left:.5in;text-indent:-.25in;mso-list:l21 level1 lfo1; |
|
|
tab-stops:list .5in'><![if !supportLists]><span style='font-size:10.0pt; |
|
|
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>-<span |
|
|
style='font:7.0pt "Times New Roman"'> |
|
|
</span></span></span><![endif]><span style='font-size:10.0pt;font-family:Arial'>switch |
|
|
to the editor and non-quietly undo the local changes to “A” before allowing the |
|
|
original undo to proceed.<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='margin-left:.5in;text-indent:-.25in;mso-list:l21 level1 lfo1; |
|
|
tab-stops:list .5in'><![if !supportLists]><span style='font-size:10.0pt; |
|
|
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>-<span |
|
|
style='font:7.0pt "Times New Roman"'> |
|
|
</span></span></span><![endif]><span style='font-size:10.0pt;font-family:Arial'>prompt |
|
|
the user for the preferred action.<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='margin-left:.5in;text-indent:-.25in;mso-list:l21 level1 lfo1; |
|
|
tab-stops:list .5in'><![if !supportLists]><span style='font-size:10.0pt; |
|
|
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>-<span |
|
|
style='font:7.0pt "Times New Roman"'> |
|
|
</span></span></span><![endif]><span style='font-size:10.0pt;font-family:Arial'>provide |
|
|
a user preference that drives the behavior of the scenario.<o:p></o:p></span></p> |
|
|
|
|
|
<h4>Workbench IDE undo contexts<o:p></o:p></h4> |
|
| 1018 |
|
|
| 1019 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span |
| 1020 |
|
style='font-size:10.0pt'> <o:p></o:p></span></p> |
| 1021 |
|
|
| 1022 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>To support |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the |
| 1023 |
the existing workbench undo scenarios, there will be two kinds of contexts |
IStatus indicating whether the execution succeeded. The severity code in the |
| 1024 |
defined in the workbench IDE.<span style='mso-spacerun:yes'> </span><o:p></o:p></span></p> |
returned status describes whether the operation succeeded and whether it was |
| 1025 |
|
added to the history. </span><code><span style='font-size:10.0pt'>OK</span></code><span |
| 1026 |
|
style='font-size:10.0pt'> severity indicates that the execute operation was |
| 1027 |
|
successful and that the operation has been added to the history. Listeners will |
| 1028 |
|
receive the </span><code><span style='font-size:10.0pt'>done</span></code><span |
| 1029 |
|
style='font-size:10.0pt'> notification. </span><code><span style='font-size: |
| 1030 |
|
10.0pt'>CANCEL</span></code><span style='font-size:10.0pt'> severity indicates |
| 1031 |
|
that the user cancelled the operation and that the operation was not added to |
| 1032 |
|
the history. </span><code><span style='font-size:10.0pt'>ERROR</span></code><span |
| 1033 |
|
style='font-size:10.0pt'> severity indicates that the operation did not |
| 1034 |
|
successfully execute and that it was not added to the history. Any other |
| 1035 |
|
severity code is not specifically interpreted by the history, and the operation |
| 1036 |
|
will not be added to the history. For all severities other than </span><code><span |
| 1037 |
|
style='font-size:10.0pt'>OK</span></code><span style='font-size:10.0pt'>, |
| 1038 |
|
listeners will receive the </span><code><span style='font-size:10.0pt'>operationNotOK</span></code><span |
| 1039 |
|
style='font-size:10.0pt'> notification instead of the </span><code><span |
| 1040 |
|
style='font-size:10.0pt'>done</span></code><span style='font-size:10.0pt'> |
| 1041 |
|
notification.<o:p></o:p></span></p> |
| 1042 |
|
|
| 1043 |
<ol style='margin-top:0in' start=1 type=1> |
<pre>public void <b>remove</b>(IOperation operation)</pre> |
|
<li class=MsoNormal style='mso-list:l10 level1 lfo26;tab-stops:list .5in'><span |
|
|
style='font-size:10.0pt;font-family:Arial'>The “workspace” context will be |
|
|
used to represent changes that affect resources in the workspace.<span |
|
|
style='mso-spacerun:yes'> </span><span class=SpellE>Refactoring</span> |
|
|
operations will use this context.<span style='mso-spacerun:yes'> |
|
|
</span>Additional actions that affect the workspace (such as delete and |
|
|
create resources) would use this context.<span style='mso-spacerun:yes'> |
|
|
</span>Views that manipulate the workspace, such as the navigator and |
|
|
package explorer, will use this context when creating operations and |
|
|
querying for the current “undo operation.”<span style='mso-spacerun:yes'> |
|
|
</span>Views or editors that may be affected by workspace operations can |
|
|
add a listener to the operation history and add their context as needed to |
|
|
operations that have been added to the history.<span |
|
|
style='mso-spacerun:yes'> </span><span style='mso-spacerun:yes'> </span>The |
|
|
workspace context implementation is not defined at this time, but it |
|
|
should be accessible by API.<span style='mso-spacerun:yes'> </span><o:p></o:p></span></li> |
|
|
<li class=MsoNormal style='mso-list:l10 level1 lfo26;tab-stops:list .5in'><span |
|
|
style='font-size:10.0pt;font-family:Arial'>Editors will define a context |
|
|
that represents their particular editing session.<span |
|
|
style='mso-spacerun:yes'> </span><span style='mso-spacerun:yes'> </span>That |
|
|
is, the context will be unique per editor, but editors may in fact share |
|
|
the context implementation class.<span style='mso-spacerun:yes'> |
|
|
</span>Workspace-affecting operations, such as <span class=SpellE>refactoring</span> |
|
|
operations, that are triggered from an editor will be considered to occur |
|
|
in the context of both the editor and the workspace.<span |
|
|
style='mso-spacerun:yes'> </span>This allows <span class=SpellE>refactoring</span> |
|
|
operations to coexist with text editing operations in the editor’s operation |
|
|
history and also be accessible from the operation history of other views |
|
|
that support the workspace context, such as the navigator. The editor’s |
|
|
context can be added using the listener as described above.<o:p></o:p></span></li> |
|
|
</ol> |
|
| 1044 |
|
|
| 1045 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Remove |
| 1046 |
|
the specified operation from the history. Listeners will be notified of the |
| 1047 |
|
removal of the operation. This method is used by clients who want to flush a |
| 1048 |
|
particular subset of the history. <o:p></o:p></span></p> |
| 1049 |
|
|
| 1050 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Further |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span |
| 1051 |
definition of contexts and the supported operations are required:<o:p></o:p></span></p> |
style='font-size:10.0pt'> <o:p></o:p></span></p> |
| 1052 |
|
|
| 1053 |
<p class=MsoNormal style='margin-left:.5in;text-indent:-.25in;mso-list:l21 level1 lfo1; |
<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>operation</span></code><span |
| 1054 |
tab-stops:list .5in'><![if !supportLists]><span style='font-size:10.0pt; |
style='font-size:10.0pt'> - - the operation to be removed from the history<o:p></o:p></span></p> |
|
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>-<span |
|
|
style='font:7.0pt "Times New Roman"'> |
|
|
</span></span></span><![endif]><span style='font-size:10.0pt;font-family:Arial'>The |
|
|
complete set of workspace operations (besides <span class=SpellE>refactoring</span>) |
|
|
that should be undoable must be defined.<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='margin-left:.5in;text-indent:-.25in;mso-list:l21 level1 lfo1; |
|
|
tab-stops:list .5in'><![if !supportLists]><span style='font-size:10.0pt; |
|
|
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>-<span |
|
|
style='font:7.0pt "Times New Roman"'> |
|
|
</span></span></span><![endif]><span style='font-size:10.0pt;font-family:Arial'>Any |
|
|
additional contexts required by the SDK (Team?<span style='mso-spacerun:yes'> |
|
|
</span>Debug?) must be defined.<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='margin-left:.5in;text-indent:-.25in;mso-list:l21 level1 lfo1; |
|
|
tab-stops:list .5in'><![if !supportLists]><span style='font-size:10.0pt; |
|
|
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>-<span |
|
|
style='font:7.0pt "Times New Roman"'> |
|
|
</span></span></span><![endif]><span style='font-size:10.0pt;font-family:Arial'>The |
|
|
operation contexts for the major views in the SDK must be defined.<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='margin-left:.5in;text-indent:-.25in;mso-list:l21 level1 lfo1; |
|
|
tab-stops:list .5in'><![if !supportLists]><span style='font-size:10.0pt; |
|
|
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>-<span |
|
|
style='font:7.0pt "Times New Roman"'> |
|
|
</span></span></span><![endif]><span style='font-size:10.0pt;font-family:Arial'>The |
|
|
semantics for assigning multiple contexts must be defined.<span |
|
|
style='mso-spacerun:yes'> </span>For example, do <span class=SpellE>refactoring</span> |
|
|
operations that affect an open editor (but were triggered elsewhere) carry the |
|
|
context of that editor? <span style='mso-spacerun:yes'> </span>Should the |
|
|
editor decide this by listening for new operations that are added to the |
|
|
history? <o:p></o:p></span></p> |
|
| 1055 |
|
|
| 1056 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<pre>public org.eclipse.core.runtime.IStatus <b>redo</b>(IOperationContext context,</pre><pre><span style='mso-spacerun:yes'> </span>org.eclipse.core.runtime.IProgressMonitor monitor)</pre> |
| 1057 |
|
|
| 1058 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>The |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Redo |
| 1059 |
following are working assumptions about the undo operations:<o:p></o:p></span></p> |
the most recently undone operation in the given context <o:p></o:p></span></p> |
| 1060 |
|
|
| 1061 |
<p class=MsoNormal style='margin-left:.5in;text-indent:-.25in;mso-list:l21 level1 lfo1; |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span |
| 1062 |
tab-stops:list .5in'><![if !supportLists]><span style='font-size:10.0pt; |
style='font-size:10.0pt'> <o:p></o:p></span></p> |
|
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>-<span |
|
|
style='font:7.0pt "Times New Roman"'> |
|
|
</span></span></span><![endif]><span style='font-size:10.0pt;font-family:Arial'>There |
|
|
is no relationship between a perspective and an operation context, since |
|
|
switching perspectives will change the active part, and thus may or may not |
|
|
affect the current context.<o:p></o:p></span></p> |
|
| 1063 |
|
|
| 1064 |
<p class=MsoNormal style='margin-left:.5in;text-indent:-.25in;mso-list:l21 level1 lfo1; |
<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>context</span></code><span |
| 1065 |
tab-stops:list .5in'><![if !supportLists]><span style='font-size:10.0pt; |
style='font-size:10.0pt'> - - the context to be redone, or null if the context |
| 1066 |
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>-<span |
does not matter <o:p></o:p></span></p> |
|
style='font:7.0pt "Times New Roman"'> |
|
|
</span></span></span><![endif]><span style='font-size:10.0pt;font-family:Arial'>Actions |
|
|
that only change the presentation in the workbench (open a view, switch |
|
|
perspectives, change the sort order) are not considered to be operations since |
|
|
they are<span style='mso-spacerun:yes'> </span>easily undone and redone |
|
|
through the same window mechanics.<o:p></o:p></span></p> |
|
| 1067 |
|
|
| 1068 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>monitor</span></code><span |
| 1069 |
|
style='font-size:10.0pt'> - - the progress monitor to be used for the redo, or |
| 1070 |
|
null if no progress monitor is provided. <o:p></o:p></span></p> |
| 1071 |
|
|
| 1072 |
<h4>Workbench UI for Undo/Redo<o:p></o:p></h4> |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span |
| 1073 |
|
style='font-size:10.0pt'> <o:p></o:p></span></p> |
| 1074 |
|
|
| 1075 |
<h5>Minimal support</h5> |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the |
| 1076 |
|
IStatus indicating whether the redo succeeded. The severity code in the |
| 1077 |
|
returned status describes whether the operation succeeded and whether it |
| 1078 |
|
remains in the history. </span><code><span style='font-size:10.0pt'>OK</span></code><span |
| 1079 |
|
style='font-size:10.0pt'> severity indicates that the redo operation was |
| 1080 |
|
successful and that the operation has been placed on the undo history. |
| 1081 |
|
Listeners will receive the </span><code><span style='font-size:10.0pt'>redone</span></code><span |
| 1082 |
|
style='font-size:10.0pt'> notification. </span><code><span style='font-size: |
| 1083 |
|
10.0pt'>CANCEL</span></code><span style='font-size:10.0pt'> severity indicates |
| 1084 |
|
that the user cancelled the operation and that the operation remains in the |
| 1085 |
|
redo history. </span><code><span style='font-size:10.0pt'>ERROR</span></code><span |
| 1086 |
|
style='font-size:10.0pt'> severity indicates that the operation could not |
| 1087 |
|
successfully be redone and that it has been removed from the history. Listeners |
| 1088 |
|
will also be notified that the operation was removed. Any other severity code |
| 1089 |
|
is not specifically interpreted by the history, and is simply passed back to |
| 1090 |
|
the caller. For all severities other than </span><code><span style='font-size: |
| 1091 |
|
10.0pt'>OK</span></code><span style='font-size:10.0pt'>, listeners will receive |
| 1092 |
|
the </span><code><span style='font-size:10.0pt'>operationNotOK</span></code><span |
| 1093 |
|
style='font-size:10.0pt'> notification instead of the </span><code><span |
| 1094 |
|
style='font-size:10.0pt'>redone</span></code><span style='font-size:10.0pt'> |
| 1095 |
|
notification.<o:p></o:p></span></p> |
| 1096 |
|
|
| 1097 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>The Edit>Undo |
<pre>public org.eclipse.core.runtime.IStatus <b>redoOperation</b>(IOperation operation,</pre><pre><span style='mso-spacerun:yes'> </span>org.eclipse.core.runtime.IProgressMonitor monitor)</pre> |
|
and Edit>Redo commands should be retargeted by most of the major views (list |
|
|
of views TBD).<span style='mso-spacerun:yes'> </span>If a view retargets |
|
|
Undo/Redo, then it knows what operation contexts it supports, and it uses these |
|
|
contexts to retrieve the available undo operation.<o:p></o:p></span></p> |
|
| 1098 |
|
|
| 1099 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Redo |
| 1100 |
|
the specified operation <o:p></o:p></span></p> |
| 1101 |
|
|
| 1102 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Edit>Undo |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span |
| 1103 |
is enabled based on the active part.<span style='mso-spacerun:yes'> </span><o:p></o:p></span></p> |
style='font-size:10.0pt'> <o:p></o:p></span></p> |
| 1104 |
|
|
| 1105 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><span |
<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>operation</span></code><span |
| 1106 |
style='mso-tab-count:1'> </span><span class=SpellE>IStatus</span> |
style='font-size:10.0pt'> - - the operation to be redone <o:p></o:p></span></p> |
|
status = <span class=SpellE>operationHistory.canUndoIn</span>(<span |
|
|
class=SpellE>myContext</span>);<o:p></o:p></span></p> |
|
| 1107 |
|
|
| 1108 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><span |
<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>monitor</span></code><span |
| 1109 |
style='mso-tab-count:1'> </span>// up to the active part to define |
style='font-size:10.0pt'> - - the progress monitor to be used for the redo, or |
| 1110 |
behavior for anything between OK and FATAL.<o:p></o:p></span></p> |
null if no progress monitor is provided <o:p></o:p></span></p> |
| 1111 |
|
|
| 1112 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span |
| 1113 |
|
style='font-size:10.0pt'> <o:p></o:p></span></p> |
| 1114 |
|
|
| 1115 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>The label |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the |
| 1116 |
for the undo action should be appended with a description of the operation.<o:p></o:p></span></p> |
IStatus indicating whether the redo succeeded. The severity code in the |
| 1117 |
|
returned status describes whether the operation succeeded and whether it |
| 1118 |
|
remains in the history. </span><code><span style='font-size:10.0pt'>OK</span></code><span |
| 1119 |
|
style='font-size:10.0pt'> severity indicates that the redo operation was |
| 1120 |
|
successful and that the operation has been placed on the undo history. |
| 1121 |
|
Listeners will receive the </span><code><span style='font-size:10.0pt'>redone</span></code><span |
| 1122 |
|
style='font-size:10.0pt'> notification. </span><code><span style='font-size: |
| 1123 |
|
10.0pt'>CANCEL</span></code><span style='font-size:10.0pt'> severity indicates |
| 1124 |
|
that the user cancelled the operation and that the operation remains in the |
| 1125 |
|
redo history. </span><code><span style='font-size:10.0pt'>ERROR</span></code><span |
| 1126 |
|
style='font-size:10.0pt'> severity indicates that the operation could not |
| 1127 |
|
successfully be redone. The operation will remain at its current location in |
| 1128 |
|
the history, and callers must explicitly remove it if desired. Any other |
| 1129 |
|
severity code is not interpreted by the history, and is simply passed back to |
| 1130 |
|
the caller. For all severities other than </span><code><span style='font-size: |
| 1131 |
|
10.0pt'>OK</span></code><span style='font-size:10.0pt'>, listeners will receive |
| 1132 |
|
the </span><code><span style='font-size:10.0pt'>operationNotOK</span></code><span |
| 1133 |
|
style='font-size:10.0pt'> notification instead of the </span><code><span |
| 1134 |
|
style='font-size:10.0pt'>redone</span></code><span style='font-size:10.0pt'> |
| 1135 |
|
notification.<o:p></o:p></span></p> |
| 1136 |
|
|
| 1137 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><span |
<pre>public org.eclipse.core.runtime.IStatus <b>undo</b>(IOperationContext context,</pre><pre><span style='mso-spacerun:yes'> </span>org.eclipse.core.runtime.IProgressMonitor monitor)</pre> |
|
style='mso-tab-count:1'> </span><span class=SpellE>operationToUndo</span> |
|
|
= <span class=SpellE>operationHistory.getUndoFor</span>(<span class=SpellE>myContext</span>);<o:p></o:p></span></p> |
|
| 1138 |
|
|
| 1139 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><span |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Undo |
| 1140 |
style='mso-tab-count:1'> </span>label = “Undo “+ <span class=SpellE>operationToUndo.label</span>();<o:p></o:p></span></p> |
the most recently undone operation in the given context <o:p></o:p></span></p> |
| 1141 |
|
|
| 1142 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span |
| 1143 |
|
style='font-size:10.0pt'> <o:p></o:p></span></p> |
| 1144 |
|
|
| 1145 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Undo and |
<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>context</span></code><span |
| 1146 |
Redo on the toolbar include a drop down that shows the operation history.<span |
style='font-size:10.0pt'> - - the context to be undone, or null if the context |
| 1147 |
style='mso-spacerun:yes'> </span>This history depends on the current part’s |
does not matter <o:p></o:p></span></p> |
|
context.<o:p></o:p></span></p> |
|
| 1148 |
|
|
| 1149 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><span |
<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>monitor</span></code><span |
| 1150 |
style='mso-tab-count:1'> </span><span class=SpellE>operationHistory.getUndoHistoryFor</span>(<span |
style='font-size:10.0pt'> - - the progress monitor to be used for the undo, or |
| 1151 |
class=SpellE>myContext</span>);<o:p></o:p></span></p> |
null if no progress monitor is provided. <o:p></o:p></span></p> |
| 1152 |
|
|
| 1153 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>The drop |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span |
| 1154 |
down permits range selection of operations from the top down (see MS Word and |
style='font-size:10.0pt'> <o:p></o:p></span></p> |
|
other applications).<span style='mso-spacerun:yes'> </span>This UI implies a |
|
|
linear undo within any particular set of contexts.<o:p></o:p></span></p> |
|
| 1155 |
|
|
| 1156 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the |
| 1157 |
|
IStatus indicating whether the undo succeeded. The severity code in the |
| 1158 |
|
returned status describes whether the operation succeeded and whether it |
| 1159 |
|
remains in the history. </span><code><span style='font-size:10.0pt'>OK</span></code><span |
| 1160 |
|
style='font-size:10.0pt'> severity indicates that the undo operation was |
| 1161 |
|
successful and that the operation has been placed on the redo history. |
| 1162 |
|
Listeners will receive the </span><code><span style='font-size:10.0pt'>undone</span></code><span |
| 1163 |
|
style='font-size:10.0pt'> notification. </span><code><span style='font-size: |
| 1164 |
|
10.0pt'>CANCEL</span></code><span style='font-size:10.0pt'> severity indicates |
| 1165 |
|
that the user cancelled the operation and that the operation remains in the |
| 1166 |
|
undo history. </span><code><span style='font-size:10.0pt'>ERROR</span></code><span |
| 1167 |
|
style='font-size:10.0pt'> severity indicates that the operation could not |
| 1168 |
|
successfully be undone and that it has been removed from the history. Listeners |
| 1169 |
|
will be notified that the operation was removed. Any other severity code is not |
| 1170 |
|
interpreted by the history, and is simply passed back to the caller. For all |
| 1171 |
|
severities other than </span><code><span style='font-size:10.0pt'>OK</span></code><span |
| 1172 |
|
style='font-size:10.0pt'>, listeners will receive the </span><code><span |
| 1173 |
|
style='font-size:10.0pt'>operationNotOK</span></code><span style='font-size: |
| 1174 |
|
10.0pt'> notification instead of the </span><code><span style='font-size:10.0pt'>undone</span></code><span |
| 1175 |
|
style='font-size:10.0pt'> notification.<o:p></o:p></span></p> |
| 1176 |
|
|
| 1177 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>The UI for |
<pre>public org.eclipse.core.runtime.IStatus <b>undoOperation</b>(IOperation operation,</pre><pre><span style='mso-spacerun:yes'> </span><span style='mso-spacerun:yes'> </span>org.eclipse.core.runtime.IProgressMonitor monitor)</pre> |
|
handling special cases should be determined.<span style='mso-spacerun:yes'> |
|
|
</span>Consider the following scenarios:<o:p></o:p></span></p> |
|
| 1178 |
|
|
| 1179 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Undo |
| 1180 |
|
the specified operation <o:p></o:p></span></p> |
| 1181 |
|
|
| 1182 |
<p class=MsoNormal><b style='mso-bidi-font-weight:normal'><span |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span |
| 1183 |
style='font-size:10.0pt;font-family:Arial'>Scenario #1:</span></b><span |
style='font-size:10.0pt'> <o:p></o:p></span></p> |
|
style='font-size:10.0pt;font-family:Arial'><span style='mso-spacerun:yes'> |
|
|
</span>Mixed contexts in an editor, undo from another view<o:p></o:p></span></p> |
|
| 1184 |
|
|
| 1185 |
<p class=MsoNormal style='margin-left:.5in;text-indent:-.25in;mso-list:l21 level1 lfo1; |
<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>operation</span></code><span |
| 1186 |
tab-stops:list .5in'><![if !supportLists]><span style='font-size:10.0pt; |
style='font-size:10.0pt'> - - the operation to be undone <o:p></o:p></span></p> |
|
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>-<span |
|
|
style='font:7.0pt "Times New Roman"'> |
|
|
</span></span></span><![endif]><span style='font-size:10.0pt;font-family:Arial'>The |
|
|
user makes local edits in editor A.<o:p></o:p></span></p> |
|
| 1187 |
|
|
| 1188 |
<p class=MsoNormal style='margin-left:.5in;text-indent:-.25in;mso-list:l21 level1 lfo1; |
<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>monitor</span></code><span |
| 1189 |
tab-stops:list .5in'><![if !supportLists]><span style='font-size:10.0pt; |
style='font-size:10.0pt'> - - the progress monitor to be used for the undo, or |
| 1190 |
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>-<span |
null if no progress monitor is provided <o:p></o:p></span></p> |
|
style='font:7.0pt "Times New Roman"'> |
|
|
</span></span></span><![endif]><span style='font-size:10.0pt;font-family:Arial'>The |
|
|
user initiates a <span class=SpellE>refactoring</span> operation whose context |
|
|
is “A” and “workspace.”<o:p></o:p></span></p> |
|
| 1191 |
|
|
| 1192 |
<p class=MsoNormal style='margin-left:.5in;text-indent:-.25in;mso-list:l21 level1 lfo1; |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span |
| 1193 |
tab-stops:list .5in'><![if !supportLists]><span style='font-size:10.0pt; |
style='font-size:10.0pt'> <o:p></o:p></span></p> |
|
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>-<span |
|
|
style='font:7.0pt "Times New Roman"'> |
|
|
</span></span></span><![endif]><span style='font-size:10.0pt;font-family:Arial'>The |
|
|
user makes additional local edits to editor A.<o:p></o:p></span></p> |
|
| 1194 |
|
|
| 1195 |
<p class=MsoNormal style='margin-left:.5in;text-indent:-.25in;mso-list:l21 level1 lfo1; |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the |
| 1196 |
tab-stops:list .5in'><![if !supportLists]><span style='font-size:10.0pt; |
IStatus indicating whether the undo succeeded. The severity code in the |
| 1197 |
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>-<span |
returned status describes whether the operation succeeded and whether it |
| 1198 |
style='font:7.0pt "Times New Roman"'> |
remains in the history. </span><code><span style='font-size:10.0pt'>OK</span></code><span |
| 1199 |
</span></span></span><![endif]><span style='font-size:10.0pt;font-family:Arial'>The |
style='font-size:10.0pt'> severity indicates that the undo operation was |
| 1200 |
user goes to the navigator and selects Undo.<o:p></o:p></span></p> |
successful and that the operation has been placed on the redo history. |
| 1201 |
|
Listeners will receive the </span><code><span style='font-size:10.0pt'>undone</span></code><span |
| 1202 |
|
style='font-size:10.0pt'> notification. </span><code><span style='font-size: |
| 1203 |
|
10.0pt'>CANCEL</span></code><span style='font-size:10.0pt'> severity indicates |
| 1204 |
|
that the user cancelled the operation and that the operation remains in the |
| 1205 |
|
undo history. </span><code><span style='font-size:10.0pt'>ERROR</span></code><span |
| 1206 |
|
style='font-size:10.0pt'> severity indicates that the operation could not |
| 1207 |
|
successfully be undone. The operation will remain at its current location in |
| 1208 |
|
the history, and callers must explicitly remove it if desired. Any other |
| 1209 |
|
severity code is not interpreted by the history, and is simply passed back to |
| 1210 |
|
the caller. For all severities other than </span><code><span style='font-size: |
| 1211 |
|
10.0pt'>OK</span></code><span style='font-size:10.0pt'>, listeners will receive |
| 1212 |
|
the </span><code><span style='font-size:10.0pt'>operationNotOK</span></code><span |
| 1213 |
|
style='font-size:10.0pt'> notification instead of the </span><code><span |
| 1214 |
|
style='font-size:10.0pt'>undone</span></code><span style='font-size:10.0pt'> |
| 1215 |
|
notification.<o:p></o:p></span></p> |
| 1216 |
|
|
| 1217 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<pre>public boolean <b>canRedo</b>(IOperationContext context)</pre> |
| 1218 |
|
|
| 1219 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>The <span |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Return |
| 1220 |
class=SpellE>IOperationApproval</span> for the editor’s context can implement |
whether there is a redoable operation available in the given context. <o:p></o:p></span></p> |
|
UI for handling this case if desired.<span style='mso-spacerun:yes'> |
|
|
</span>Possible options include:<o:p></o:p></span></p> |
|
| 1221 |
|
|
| 1222 |
<p class=MsoNormal style='margin-left:.5in;text-indent:-.25in;mso-list:l21 level1 lfo1; |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span |
| 1223 |
tab-stops:list .5in'><![if !supportLists]><span style='font-size:10.0pt; |
style='font-size:10.0pt'> <o:p></o:p></span></p> |
|
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>-<span |
|
|
style='font:7.0pt "Times New Roman"'> |
|
|
</span></span></span><![endif]><span style='font-size:10.0pt;font-family:Arial'>warn |
|
|
the user about the local changes in A and ask whether to undo them or leave |
|
|
them<o:p></o:p></span></p> |
|
| 1224 |
|
|
| 1225 |
<p class=MsoNormal style='margin-left:.5in;text-indent:-.25in;mso-list:l21 level1 lfo1; |
<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>context</span></code><span |
| 1226 |
tab-stops:list .5in'><![if !supportLists]><span style='font-size:10.0pt; |
style='font-size:10.0pt'> - - the context to be checked, or null for any |
| 1227 |
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>-<span |
context <o:p></o:p></span></p> |
|
style='font:7.0pt "Times New Roman"'> |
|
|
</span></span></span><![endif]><span style='font-size:10.0pt;font-family:Arial'>provide |
|
|
a user preference that drives the behavior of the scenario.<o:p></o:p></span></p> |
|
| 1228 |
|
|
| 1229 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span |
| 1230 |
|
style='font-size:10.0pt'> <o:p></o:p></span></p> |
| 1231 |
|
|
| 1232 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>The exact |
<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>true</span></code><span |
| 1233 |
solution will be prototyped and may involve both a first-time prompt and |
style='font-size:10.0pt'> if there is a redoable operation, </span><code><span |
| 1234 |
subsequent preference (“Don’t ask me again”).<o:p></o:p></span></p> |
style='font-size:10.0pt'>false</span></code><span style='font-size:10.0pt'> |
| 1235 |
|
otherwise.<o:p></o:p></span></p> |
| 1236 |
|
|
| 1237 |
<p class=MsoNormal><o:p> </o:p></p> |
<pre>public boolean <b>canUndo</b>(IOperationContext context)</pre> |
| 1238 |
|
|
| 1239 |
<p class=MsoNormal><b style='mso-bidi-font-weight:normal'><span |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Return |
| 1240 |
style='font-size:10.0pt;font-family:Arial'>Scenario #2</span></b><span |
whether there is an undoable operation available in the given context <o:p></o:p></span></p> |
|
style='font-size:10.0pt;font-family:Arial'>:<span style='mso-spacerun:yes'> |
|
|
</span>Editor undo triggers a non-local operation<o:p></o:p></span></p> |
|
| 1241 |
|
|
| 1242 |
<p class=MsoNormal style='margin-left:.5in;text-indent:-.25in;mso-list:l21 level1 lfo1; |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span |
| 1243 |
tab-stops:list .5in'><![if !supportLists]><span style='font-size:10.0pt; |
style='font-size:10.0pt'> <o:p></o:p></span></p> |
|
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>-<span |
|
|
style='font:7.0pt "Times New Roman"'> |
|
|
</span></span></span><![endif]><span style='font-size:10.0pt;font-family:Arial'>The |
|
|
user makes local edits in editor A.<o:p></o:p></span></p> |
|
| 1244 |
|
|
| 1245 |
<p class=MsoNormal style='margin-left:.5in;text-indent:-.25in;mso-list:l21 level1 lfo1; |
<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>context</span></code><span |
| 1246 |
tab-stops:list .5in'><![if !supportLists]><span style='font-size:10.0pt; |
style='font-size:10.0pt'> - - the context to be checked, or null to represent |
| 1247 |
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>-<span |
any context <o:p></o:p></span></p> |
|
style='font:7.0pt "Times New Roman"'> |
|
|
</span></span></span><![endif]><span style='font-size:10.0pt;font-family:Arial'>The |
|
|
user initiates a <span class=SpellE>refactoring</span> operation whose context |
|
|
is “A” and “workspace.”<o:p></o:p></span></p> |
|
| 1248 |
|
|
| 1249 |
<p class=MsoNormal style='margin-left:.5in;text-indent:-.25in;mso-list:l21 level1 lfo1; |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span |
| 1250 |
tab-stops:list .5in'><![if !supportLists]><span style='font-size:10.0pt; |
style='font-size:10.0pt'> <o:p></o:p></span></p> |
|
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>-<span |
|
|
style='font:7.0pt "Times New Roman"'> |
|
|
</span></span></span><![endif]><span style='font-size:10.0pt;font-family:Arial'>The |
|
|
user makes additional local edits to editor A.<o:p></o:p></span></p> |
|
| 1251 |
|
|
| 1252 |
<p class=MsoNormal style='margin-left:.5in;text-indent:-.25in;mso-list:l21 level1 lfo1; |
<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>true</span></code><span |
| 1253 |
tab-stops:list .5in'><![if !supportLists]><span style='font-size:10.0pt; |
style='font-size:10.0pt'> if there is an undoable operation, </span><code><span |
| 1254 |
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>-<span |
style='font-size:10.0pt'>false</span></code><span style='font-size:10.0pt'> |
| 1255 |
style='font:7.0pt "Times New Roman"'> |
otherwise.<o:p></o:p></span></p> |
|
</span></span></span><![endif]><span style='font-size:10.0pt;font-family:Arial'>The |
|
|
user selects undo repeatedly from the editor<o:p></o:p></span></p> |
|
| 1256 |
|
|
| 1257 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<pre>public void <b>addOperationApprover</b>(IOperationApprover approver)</pre> |
| 1258 |
|
|
| 1259 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Most operations |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Add |
| 1260 |
in the editor’s context affect only the editor.<span style='mso-spacerun:yes'> |
the specified approver to the operation history. <o:p></o:p></span></p> |
|
</span>The <span class=SpellE>refactoring</span> operation affects not only the |
|
|
editor, but other objects in the workspace.<span style='mso-spacerun:yes'> |
|
|
</span>It might surprise the user for the <span class=SpellE>refactoring</span> |
|
|
to be undone.<span style='mso-spacerun:yes'> </span>The editor could implement |
|
|
a warning dialog when it detects that the proposed undo operation has |
|
|
additional contexts.<span style='mso-spacerun:yes'> </span><o:p></o:p></span></p> |
|
| 1261 |
|
|
| 1262 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span |
| 1263 |
|
style='font-size:10.0pt'> <o:p></o:p></span></p> |
| 1264 |
|
|
| 1265 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>If the <span |
<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>approver</span></code><span |
| 1266 |
class=SpellE>refactoring</span> had been triggered elsewhere (say, editor “B” |
style='font-size:10.0pt'> - - the IOperationApprover that will be consulted |
| 1267 |
or the navigator), but resulted in changes to editor “A,” it is even more |
before any operation in the history is undone or redone<o:p></o:p></span></p> |
|
important that the user be warned about the operation invoked by the undo |
|
|
command.<span style='mso-spacerun:yes'> </span><o:p></o:p></span></p> |
|
| 1268 |
|
|
| 1269 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<pre>public void <b>addOperationHistoryListener</b>(IOperationHistoryListener listener)</pre> |
| 1270 |
|
|
| 1271 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>The<span |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Add |
| 1272 |
style='mso-spacerun:yes'> </span>solution for this scenario will be prototyped |
the specified listener to the operation history. <o:p></o:p></span></p> |
|
and may involve both a warning and subsequent preference.<span |
|
|
style='mso-spacerun:yes'> </span>For example, a prompt could provide the label |
|
|
and description of the operation and warn that it affects other views.<span |
|
|
style='mso-spacerun:yes'> </span>The user could choose whether to proceed, and |
|
|
the choice could be remembered in a preference.<o:p></o:p></span></p> |
|
| 1273 |
|
|
| 1274 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span |
| 1275 |
|
style='font-size:10.0pt'> <o:p></o:p></span></p> |
| 1276 |
|
|
| 1277 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>It appears |
<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>listener</span></code><span |
| 1278 |
that the proposed framework allows detection of these cases and hooks for |
style='font-size:10.0pt'> - - the IOperationHistoryListener to receive |
| 1279 |
supplying the necessary UI.<o:p></o:p></span></p> |
notifications about changes in the history or operations that are executed, |
| 1280 |
|
undone, or redone<o:p></o:p></span></p> |
| 1281 |
|
|
| 1282 |
<h5>Advanced support</h5> |
<pre>public void <b>removeOperationApprover</b>(IOperationApprover approver)</pre> |
| 1283 |
|
|
| 1284 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>More |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Remove |
| 1285 |
selective undo approaches can be supported by the framework, but the ability to |
the specified operation approver from the operation history. <o:p></o:p></span></p> |
|
support them in the workbench depends upon the implementation of the individual |
|
|
operations and their ability to be undone independently.<span |
|
|
style='mso-spacerun:yes'> </span>The priority is TBD.<span |
|
|
style='mso-spacerun:yes'> </span>Ideas include:<o:p></o:p></span></p> |
|
| 1286 |
|
|
| 1287 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span |
| 1288 |
|
style='font-size:10.0pt'> <o:p></o:p></span></p> |
| 1289 |
|
|
| 1290 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Additional menu |
<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>approver</span></code><span |
| 1291 |
commands show the operation history.<o:p></o:p></span></p> |
style='font-size:10.0pt'> - - the IOperationApprover to be removed<o:p></o:p></span></p> |
| 1292 |
|
|
| 1293 |
<p class=MsoNormal style='text-indent:.5in'><span style='font-size:10.0pt; |
<pre>public void <b>removeOperationHistoryListener</b>(IOperationHistoryListener listener)</pre> |
|
font-family:Arial'>Edit>Undo… shows the undo operation history based on the |
|
|
active part’s context.<o:p></o:p></span></p> |
|
| 1294 |
|
|
| 1295 |
<p class=MsoNormal style='text-indent:.5in'><span style='font-size:10.0pt; |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Remove |
| 1296 |
font-family:Arial'>Edit>Redo… shows the redo operation history based on the |
the specified listener from the operation history. <o:p></o:p></span></p> |
|
active part’s context.<o:p></o:p></span></p> |
|
| 1297 |
|
|
| 1298 |
<p class=MsoNormal style='text-indent:.5in'><span style='font-size:10.0pt; |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span |
| 1299 |
font-family:Arial'><span style='mso-tab-count:1'> </span><span |
style='font-size:10.0pt'> <o:p></o:p></span></p> |
|
class=SpellE>operationHistory.getUndoHistoryFor</span>(<span class=SpellE>myContext</span>);<o:p></o:p></span></p> |
|
| 1300 |
|
|
| 1301 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>listener</span></code><span |
| 1302 |
|
style='font-size:10.0pt'> - - The IOperationHistoryListener to be removed<o:p></o:p></span></p> |
| 1303 |
|
|
| 1304 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>The operation |
<pre>public IOperation <b>getRedoOperation</b>(IOperationContext context)</pre> |
|
history can be shown in a view or dialog.<span style='mso-spacerun:yes'> |
|
|
</span>Operations that are valid can be selected (one at a time) and undone (or |
|
|
redone) regardless of sequential order.<span style='mso-spacerun:yes'> </span>Multiple |
|
|
selections are not allowed since the validation state for an operation might |
|
|
change as other operations are undone.<o:p></o:p></span></p> |
|
| 1305 |
|
|
| 1306 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Get |
| 1307 |
|
the operation that will next be redone in the given context. This method is |
| 1308 |
|
used to retrieve the label or description as needed for the "Redo" |
| 1309 |
|
menu. <o:p></o:p></span></p> |
| 1310 |
|
|
| 1311 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>The operation |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span |
| 1312 |
history view could allow changing of the filtering.<span |
style='font-size:10.0pt'> <o:p></o:p></span></p> |
|
style='mso-spacerun:yes'> </span>While the default filtering could depend on |
|
|
the active part’s context, the user could be shown the available contexts and |
|
|
choose one or more contexts (or none at all) that affect the filtering of the |
|
|
list.<span style='mso-spacerun:yes'> </span><o:p></o:p></span></p> |
|
| 1313 |
|
|
| 1314 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>context</span></code><span |
| 1315 |
|
style='font-size:10.0pt'> - - the context for the redo, or null if the context |
| 1316 |
|
does not matter <o:p></o:p></span></p> |
| 1317 |
|
|
| 1318 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Note that |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span |
| 1319 |
the UI for the advanced cases can be implemented independently from the operations, |
style='font-size:10.0pt'> <o:p></o:p></span></p> |
|
and may be useful for testing the framework.<o:p></o:p></span></p> |
|
| 1320 |
|
|
| 1321 |
<h3>Compatibility Issues</h3> |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the |
| 1322 |
|
operation to be redone or </span><code><span style='font-size:10.0pt'>null</span></code><span |
| 1323 |
|
style='font-size:10.0pt'> if there is no valid operation available.<o:p></o:p></span></p> |
| 1324 |
|
|
| 1325 |
<h4><span class=SpellE>JFace</span> Text</h4> |
<pre>public IOperation [] <b>getRedoHistory</b>(IOperationContext context)</pre> |
| 1326 |
|
|
| 1327 |
<p class=MsoNormal><span class=SpellE><span style='font-size:10.0pt;font-family: |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Get |
| 1328 |
Arial'>JFace</span></span><span style='font-size:10.0pt;font-family:Arial'> text |
the array of operations in the redo history for a given context. The operations |
| 1329 |
currently has API for retrieving an <span class=SpellE>IUndoManager</span> from |
are in the order that they would be redone if successive "Redo" |
| 1330 |
a text viewer.<span style='mso-spacerun:yes'> </span>The undo manager is |
commands were invoked. <o:p></o:p></span></p> |
|
connected to a text viewer and watches the changes that happen in the |
|
|
viewer.<span style='mso-spacerun:yes'> </span>As editing actions occurs, |
|
|
commands (<span class=SpellE>TextCommand</span>) are created and then |
|
|
“committed” to a command stack.<span style='mso-spacerun:yes'> </span><o:p></o:p></span></p> |
|
| 1331 |
|
|
| 1332 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span |
| 1333 |
|
style='font-size:10.0pt'> <o:p></o:p></span></p> |
| 1334 |
|
|
| 1335 |
<p class=MsoNormal><span class=SpellE><span style='font-size:10.0pt;font-family: |
<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>context</span></code><span |
| 1336 |
Arial'>TextCommand</span></span><span style='font-size:10.0pt;font-family:Arial'> |
style='font-size:10.0pt'> - - the context for the redo, or null if the entire |
| 1337 |
could be changed to implement <span class=SpellE>IOperation</span>.<span |
history is requested <o:p></o:p></span></p> |
|
style='mso-spacerun:yes'> </span>The mapping from <span class=SpellE>IOperation</span> |
|
|
to <span class=SpellE>TextCommand</span> protocol is straightforward.<span |
|
|
style='mso-spacerun:yes'> </span>Currently the <span class=SpellE>TextCommand</span> |
|
|
directly pushes itself onto a local command stack of a viewer when a set of pending |
|
|
changes are committed.<span style='mso-spacerun:yes'> </span>Instead, it would |
|
|
need to set its context to one appropriate for the text viewer and add itself |
|
|
to the workbench operation history.<span style='mso-spacerun:yes'> </span><span |
|
|
style='mso-spacerun:yes'> </span><o:p></o:p></span></p> |
|
| 1338 |
|
|
| 1339 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span |
| 1340 |
|
style='font-size:10.0pt'> <o:p></o:p></span></p> |
| 1341 |
|
|
| 1342 |
<p class=MsoNormal><span class=SpellE><span style='font-size:10.0pt;font-family: |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the |
| 1343 |
Arial'>IUndoManager</span></span><span style='font-size:10.0pt;font-family: |
array of operations in the history<o:p></o:p></span></p> |
|
Arial'> API could be mapped as follows:<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal><b style='mso-bidi-font-weight:normal'><span |
|
|
style='font-size:10.0pt;font-family:Arial'>connect(<span class=SpellE>ITextViewer</span>) |
|
|
<o:p></o:p></span></b></p> |
|
|
|
|
|
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Creates a |
|
|
context (<span class=SpellE>myContext</span>) appropriate for representing this |
|
|
document’s operations<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal><b style='mso-bidi-font-weight:normal'><span |
|
|
style='font-size:10.0pt;font-family:Arial'>disconnect(<span class=SpellE>ITextViewer</span>) |
|
|
<o:p></o:p></span></b></p> |
|
|
|
|
|
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Performs |
|
|
necessary disconnect behavior and clears the operation history of operations involving |
|
|
the viewer.<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='margin-left:.5in'><span class=SpellE><span |
|
|
style='font-size:10.0pt;font-family:Arial'>operationHistory.disposeAll</span></span><span |
|
|
style='font-size:10.0pt;font-family:Arial'>(<span class=SpellE>myContext</span>);<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal><span class=SpellE><b style='mso-bidi-font-weight:normal'><span |
|
|
style='font-size:10.0pt;font-family:Arial'>beginCompoundChange</span></b></span><b |
|
|
style='mso-bidi-font-weight:normal'><span style='font-size:10.0pt;font-family: |
|
|
Arial'>() <o:p></o:p></span></b></p> |
|
|
|
|
|
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Creates a <span |
|
|
class=SpellE>CompoundOperation</span> and stores subsequent <span class=SpellE>TextCommands</span> |
|
|
in this operation.<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal><span class=SpellE><b style='mso-bidi-font-weight:normal'><span |
|
|
style='font-size:10.0pt;font-family:Arial'>endCompoundChange</span></b></span><b |
|
|
style='mso-bidi-font-weight:normal'><span style='font-size:10.0pt;font-family: |
|
|
Arial'><o:p></o:p></span></b></p> |
|
| 1344 |
|
|
| 1345 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Adds the current |
<pre>public IOperation <b>getUndoOperation</b>(IOperationContext context)</pre> |
|
compound operation to the operation history.<o:p></o:p></span></p> |
|
| 1346 |
|
|
| 1347 |
<p class=MsoNormal><b style='mso-bidi-font-weight:normal'><span |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Get the |
| 1348 |
style='font-size:10.0pt;font-family:Arial'>reset()<o:p></o:p></span></b></p> |
operation that will next be undone in the given context. This method is used to |
| 1349 |
|
retrieve the label or description as needed for the "Undo" menu. <o:p></o:p></span></p> |
| 1350 |
|
|
| 1351 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Clears the operation |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span |
| 1352 |
history of operations involving the viewer.<o:p></o:p></span></p> |
style='font-size:10.0pt'> <o:p></o:p></span></p> |
| 1353 |
|
|
| 1354 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><span |
<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>context</span></code><span |
| 1355 |
style='mso-tab-count:1'> </span><span class=SpellE>operationHistory.disposeAll</span>(<span |
style='font-size:10.0pt'> - - the context for the undo, or null if the context |
| 1356 |
class=SpellE>myContext</span>);<o:p></o:p></span></p> |
does not matter <o:p></o:p></span></p> |
| 1357 |
|
|
| 1358 |
<p class=MsoNormal><span class=SpellE><b style='mso-bidi-font-weight:normal'><span |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span |
| 1359 |
style='font-size:10.0pt;font-family:Arial'>setMaximumUndoLevel</span></b></span><b |
style='font-size:10.0pt'> <o:p></o:p></span></p> |
|
style='mso-bidi-font-weight:normal'><span style='font-size:10.0pt;font-family: |
|
|
Arial'>(<span class=SpellE>int</span>) – TBD<o:p></o:p></span></b></p> |
|
| 1360 |
|
|
| 1361 |
<p class=MsoNormal><b style='mso-bidi-font-weight:normal'><span |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the operation |
| 1362 |
style='font-size:10.0pt;font-family:Arial'>undoable() <o:p></o:p></span></b></p> |
to be undone or </span><code><span style='font-size:10.0pt'>null</span></code><span |
| 1363 |
|
style='font-size:10.0pt'> if there is no operation available.<o:p></o:p></span></p> |
| 1364 |
|
|
| 1365 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Maps as |
<pre>public IOperation [] <b>getUndoHistory</b>(IOperationContext context)</pre> |
|
follows:<o:p></o:p></span></p> |
|
| 1366 |
|
|
| 1367 |
<p class=MsoNormal style='text-indent:.5in'><span style='font-size:10.0pt; |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Get |
| 1368 |
font-family:Arial'>status = <span class=SpellE>operationHistory.canUndoIn</span>(<span |
the array of operations that can be undone in the specified context. The |
| 1369 |
class=SpellE>myContext</span>);<o:p></o:p></span></p> |
operations are in the order that they would be undone if successive |
| 1370 |
|
"Undo" commands were invoked. <o:p></o:p></span></p> |
|
<p class=MsoNormal style='text-indent:.5in'><span style='font-size:10.0pt; |
|
|
font-family:Arial'>return <span class=SpellE>status.isOK</span>();<span |
|
|
style='mso-spacerun:yes'> </span>// may require further checking of other |
|
|
cases<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal><span class=SpellE><b style='mso-bidi-font-weight:normal'><span |
|
|
style='font-size:10.0pt;font-family:Arial'>redoable</span></b></span><b |
|
|
style='mso-bidi-font-weight:normal'><span style='font-size:10.0pt;font-family: |
|
|
Arial'>() <o:p></o:p></span></b></p> |
|
| 1371 |
|
|
| 1372 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Maps as |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span |
| 1373 |
follows:<o:p></o:p></span></p> |
style='font-size:10.0pt'> <o:p></o:p></span></p> |
| 1374 |
|
|
| 1375 |
<p class=MsoNormal style='text-indent:.5in'><span style='font-size:10.0pt; |
<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>context</span></code><span |
| 1376 |
font-family:Arial'>status = <span class=SpellE>operationHistory.canRedoIn</span>(<span |
style='font-size:10.0pt'> - - the context for the undo, or null if the entire |
| 1377 |
class=SpellE>myContext</span>);<o:p></o:p></span></p> |
history is requested <o:p></o:p></span></p> |
| 1378 |
|
|
| 1379 |
<p class=MsoNormal style='text-indent:.5in'><span style='font-size:10.0pt; |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span |
| 1380 |
font-family:Arial'>return <span class=SpellE>status.isOK</span>();<span |
style='font-size:10.0pt'> <o:p></o:p></span></p> |
|
style='mso-spacerun:yes'> </span>// may require further checking of other |
|
|
cases<o:p></o:p></span></p> |
|
| 1381 |
|
|
| 1382 |
<p class=MsoNormal><b style='mso-bidi-font-weight:normal'><span |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the |
| 1383 |
style='font-size:10.0pt;font-family:Arial'>undo()<o:p></o:p></span></b></p> |
array of operations in the history<o:p></o:p></span></p> |
| 1384 |
|
|
| 1385 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Use <span |
<pre>public void <b>dispose</b>(IOperationContext context,</pre><pre><span style='mso-spacerun:yes'> </span><span style='mso-spacerun:yes'> </span>boolean flushUndo,</pre><pre><span style='mso-spacerun:yes'> </span>boolean flushRedo)</pre> |
|
class=SpellE>operationHistory.performUndoFor</span>(<span class=SpellE>myContext</span>) |
|
|
instead of managing its own stack.<o:p></o:p></span></p> |
|
| 1386 |
|
|
| 1387 |
<p class=MsoNormal><b style='mso-bidi-font-weight:normal'><span |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Dispose |
| 1388 |
style='font-size:10.0pt;font-family:Arial'>redo()<o:p></o:p></span></b></p> |
of the specified context in the history. All operations that have only the |
| 1389 |
|
given context will be disposed. References to the context in operations that |
| 1390 |
|
have more than one context will also be removed. <o:p></o:p></span></p> |
| 1391 |
|
|
| 1392 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Use <span |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span |
| 1393 |
class=SpellE>operationHistory.performRedoFor</span>(<span class=SpellE>myContext</span>) |
style='font-size:10.0pt'> <o:p></o:p></span></p> |
|
instead of managing its own stack.<o:p></o:p></span></p> |
|
| 1394 |
|
|
| 1395 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>context</span></code><span |
| 1396 |
|
style='font-size:10.0pt'> - - the context to be disposed, or null if all |
| 1397 |
|
contexts are to be disposed <o:p></o:p></span></p> |
| 1398 |
|
|
| 1399 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>The <span |
<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>flushUndo</span></code><span |
| 1400 |
class=SpellE>TextCommand</span> class is private, so no API mapping is |
style='font-size:10.0pt'> - - </span><code><span style='font-size:10.0pt'>true</span></code><span |
| 1401 |
discussed here.<span style='mso-spacerun:yes'> </span>However, its protocol is |
style='font-size:10.0pt'> if the context should be flushed from the undo |
| 1402 |
very similar to <span class=SpellE>IOperation</span> and the |
history, </span><code><span style='font-size:10.0pt'>false</span></code><span |
| 1403 |
reimplementation/mapping is straightforward.<o:p></o:p></span></p> |
style='font-size:10.0pt'> if it should not <o:p></o:p></span></p> |
| 1404 |
|
|
| 1405 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>flushRedo</span></code><span |
| 1406 |
|
style='font-size:10.0pt'> - - </span><code><span style='font-size:10.0pt'>true</span></code><span |
| 1407 |
|
style='font-size:10.0pt'> if the context should be flushed from the redo |
| 1408 |
|
history, </span><code><span style='font-size:10.0pt'>false</span></code><span |
| 1409 |
|
style='font-size:10.0pt'> if it should not.<o:p></o:p></span></p> |
| 1410 |
|
|
| 1411 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Issues:<span |
<pre>public int <b>getLimit</b>()</pre> |
|
style='mso-spacerun:yes'> </span><o:p></o:p></span></p> |
|
| 1412 |
|
|
| 1413 |
<p class=MsoNormal style='margin-left:.5in;text-indent:-.25in;mso-list:l21 level1 lfo1; |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Return |
| 1414 |
tab-stops:list .5in'><![if !supportLists]><span style='font-size:10.0pt; |
the specified limit on the undo and redo history. <o:p></o:p></span></p> |
|
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>-<span |
|
|
style='font:7.0pt "Times New Roman"'> |
|
|
</span></span></span><![endif]><span style='font-size:10.0pt;font-family:Arial'>As |
|
|
discussed throughout this document, additional operations (such as compound operations |
|
|
or <span class=SpellE>refactoring</span> operations) might appear in the text |
|
|
viewer’s context, and therefore in its <span class=SpellE>IUndoManager</span>.<span |
|
|
style='mso-spacerun:yes'> </span>The implementation should be checked for any |
|
|
assumptions that the current operation is a <span class=SpellE>TextCommand</span>.<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='margin-left:.5in;text-indent:-.25in;mso-list:l21 level1 lfo1; |
|
|
tab-stops:list .5in'><![if !supportLists]><span style='font-size:10.0pt; |
|
|
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>-<span |
|
|
style='font:7.0pt "Times New Roman"'> |
|
|
</span></span></span><![endif]><span class=SpellE><span style='font-size:10.0pt; |
|
|
font-family:Arial'>IUndoManager</span></span><span style='font-size:10.0pt; |
|
|
font-family:Arial'> currently keeps a local history limit.<span |
|
|
style='mso-spacerun:yes'> </span>How do we handle this?<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='margin-left:.75in;text-indent:-.25in;mso-list:l17 level1 lfo20; |
|
|
tab-stops:list .75in'><![if !supportLists]><span style='font-size:10.0pt; |
|
|
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>-<span |
|
|
style='font:7.0pt "Times New Roman"'> |
|
|
</span></span></span><![endif]><span style='font-size:10.0pt;font-family:Arial'>allow |
|
|
local history limits per context (seems complicated)<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='margin-left:.75in;text-indent:-.25in;mso-list:l17 level1 lfo20; |
|
|
tab-stops:list .75in'><![if !supportLists]><span style='font-size:10.0pt; |
|
|
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>-<span |
|
|
style='font:7.0pt "Times New Roman"'> |
|
|
</span></span></span><![endif]><span style='font-size:10.0pt;font-family:Arial'>ignore |
|
|
this part of the API in the new world<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='margin-left:.75in;text-indent:-.25in;mso-list:l17 level1 lfo20; |
|
|
tab-stops:list .75in'><![if !supportLists]><span style='font-size:10.0pt; |
|
|
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>-<span |
|
|
style='font:7.0pt "Times New Roman"'> |
|
|
</span></span></span><![endif]><span style='font-size:10.0pt;font-family:Arial'>decide |
|
|
how to affect the global history limit based on the local limit<o:p></o:p></span></p> |
|
|
|
|
|
<h4><span class=SpellE>Refactoring</span> </h4> |
|
|
|
|
|
<p class=MsoNormal><span class=SpellE><span style='font-size:10.0pt;font-family: |
|
|
Arial'>Refactoring</span></span><span style='font-size:10.0pt;font-family:Arial'> |
|
|
undo is currently implemented with change objects,<span |
|
|
style='mso-spacerun:yes'> </span>Change objects record workspace changes |
|
|
initiated by <span class=SpellE>refactoring</span> operations.<span |
|
|
style='mso-spacerun:yes'> </span>When a <span class=SpellE>refactoring</span> |
|
|
change is performed, it can optionally return another change that could be used |
|
|
to undo the change just executed.<span style='mso-spacerun:yes'> </span>The |
|
|
undo change is placed in <span class=SpellE>refactoring’s</span> <span |
|
|
class=SpellE>IUndoManager</span>.<span style='mso-spacerun:yes'> |
|
|
</span>Changes can be performed, but any undo or redo causes a new change to be |
|
|
created vs. having each change know how to undo and redo itself. <o:p></o:p></span></p> |
|
| 1415 |
|
|
| 1416 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span |
| 1417 |
|
style='font-size:10.0pt'> <o:p></o:p></span></p> |
| 1418 |
|
|
| 1419 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>While this |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>limit<o:p></o:p></span></p> |
|
approach simplifies the protocol for an operation, it has not been used in the |
|
|
proposed framework for several reasons:<o:p></o:p></span></p> |
|
| 1420 |
|
|
| 1421 |
<ol style='margin-top:0in' start=1 type=1> |
<pre>public void <b>setLimit</b>(int limit)</pre> |
|
<li class=MsoNormal style='mso-list:l12 level1 lfo27;tab-stops:list .5in'><span |
|
|
style='font-size:10.0pt;font-family:Arial'>It is not compatible with the |
|
|
implementation used by text, EMF, or GEF. <o:p></o:p></span></li> |
|
|
<li class=MsoNormal style='mso-list:l12 level1 lfo27;tab-stops:list .5in'><span |
|
|
style='font-size:10.0pt;font-family:Arial'>It causes additional operations |
|
|
to be created before an undo is ever requested.<span |
|
|
style='mso-spacerun:yes'> </span>This violates the goal of “pay as you |
|
|
go.”<o:p></o:p></span></li> |
|
|
</ol> |
|
| 1422 |
|
|
| 1423 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Set |
| 1424 |
|
the limit on the undo and redo history. <o:p></o:p></span></p> |
| 1425 |
|
|
| 1426 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Additional |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span |
| 1427 |
protocol is provided for initializing data needed to do a live validation for |
style='font-size:10.0pt'> <o:p></o:p></span></p> |
|
execution.<span style='mso-spacerun:yes'> </span>Validation can be done with |
|
|
this cached information or on the fly.<o:p></o:p></span></p> |
|
| 1428 |
|
|
| 1429 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>limit</span></code><span |
| 1430 |
|
style='font-size:10.0pt'> - - the maximum number of operations that should be |
| 1431 |
|
kept in the history<o:p></o:p></span></p> |
| 1432 |
|
|
| 1433 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Protocol is |
<h3>IOperationContext</h3> |
|
also provided to return the object modified by a change (<span class=SpellE>getModifiedElement</span>()).<o:p></o:p></span></p> |
|
| 1434 |
|
|
| 1435 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<pre>public java.lang.String <b>getLabel</b>()</pre> |
| 1436 |
|
|
| 1437 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>The Change |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Get |
| 1438 |
API could be mapped as follows.<span style='mso-spacerun:yes'> </span>Note |
the label that should be used to describe the context in any views. Contexts may |
| 1439 |
that much of the protocol could be provided in an abstract “<span class=SpellE>RefactoringOperation</span>” |
be shown when filtered operation histories are shown to the user. <o:p></o:p></span></p> |
|
or perhaps in a more generic “<span class=SpellE>WorkspaceOperation</span>.”<span |
|
|
style='mso-spacerun:yes'> </span>However we do not promote these concepts to |
|
|
the framework since different kinds of operations have different needs for |
|
|
caching model objects, validation state, etc.<span style='mso-spacerun:yes'> |
|
|
</span><o:p></o:p></span></p> |
|
| 1440 |
|
|
| 1441 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span |
| 1442 |
|
style='font-size:10.0pt'> <o:p></o:p></span></p> |
| 1443 |
|
|
| 1444 |
<p class=MsoNormal><span class=SpellE><b style='mso-bidi-font-weight:normal'><span |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the |
| 1445 |
style='font-size:10.0pt;font-family:Arial'>getModifiedElement</span></b></span><b |
label for the context.<o:p></o:p></span></p> |
|
style='mso-bidi-font-weight:normal'><span style='font-size:10.0pt;font-family: |
|
|
Arial'>() <o:p></o:p></span></b></p> |
|
|
|
|
|
<p class=MsoNormal><span class=SpellE><b style='mso-bidi-font-weight:normal'><span |
|
|
style='font-size:10.0pt;font-family:Arial'>getAdapter</span></b></span><b |
|
|
style='mso-bidi-font-weight:normal'><span style='font-size:10.0pt;font-family: |
|
|
Arial'>(Class)<o:p></o:p></span></b></p> |
|
|
|
|
|
<p class=MsoNormal><span class=SpellE><span style='font-size:10.0pt;font-family: |
|
|
Arial'>Refactoring</span></span><span style='font-size:10.0pt;font-family:Arial'> |
|
|
changes need to know which model element is modified by the change.<span |
|
|
style='mso-spacerun:yes'> </span>They must also implement <span class=SpellE>IAdaptable</span>.<span |
|
|
style='mso-spacerun:yes'> </span>This protocol can be provided in an abstract <span |
|
|
class=SpellE>RefactoringOperation</span> and interpreted by individual |
|
|
subclasses as done today.<span style='mso-spacerun:yes'> </span>This protocol |
|
|
might in fact be suitable for all workspace-affecting operations.<span |
|
|
style='mso-spacerun:yes'> </span><o:p></o:p></span></p> |
|
| 1446 |
|
|
| 1447 |
<p class=MsoNormal><span class=SpellE><b style='mso-bidi-font-weight:normal'><span |
<pre>public IContextOperationApprover <b>getOperationApprover</b>()</pre> |
|
style='font-size:10.0pt;font-family:Arial'>getParent</span></b></span><b |
|
|
style='mso-bidi-font-weight:normal'><span style='font-size:10.0pt;font-family: |
|
|
Arial'>()<o:p></o:p></span></b></p> |
|
|
|
|
|
<p class=MsoNormal><span class=SpellE><b style='mso-bidi-font-weight:normal'><span |
|
|
style='font-size:10.0pt;font-family:Arial'>setParent</span></b></span><b |
|
|
style='mso-bidi-font-weight:normal'><span style='font-size:10.0pt;font-family: |
|
|
Arial'>(Change)<o:p></o:p></span></b></p> |
|
|
|
|
|
<p class=MsoNormal><span class=SpellE><b style='mso-bidi-font-weight:normal'><span |
|
|
style='font-size:10.0pt;font-family:Arial'>isEnabled</span></b></span><b |
|
|
style='mso-bidi-font-weight:normal'><span style='font-size:10.0pt;font-family: |
|
|
Arial'>()<o:p></o:p></span></b></p> |
|
|
|
|
|
<p class=MsoNormal><span class=SpellE><b style='mso-bidi-font-weight:normal'><span |
|
|
style='font-size:10.0pt;font-family:Arial'>setEnabled</span></b></span><b |
|
|
style='mso-bidi-font-weight:normal'><span style='font-size:10.0pt;font-family: |
|
|
Arial'>(<span class=SpellE>boolean</span>)<o:p></o:p></span></b></p> |
|
| 1448 |
|
|
| 1449 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>The |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Get |
| 1450 |
associated fields and protocol can be defined in an abstract class. <o:p></o:p></span></p> |
the operation approver that is used to approve undo or redo operations |
| 1451 |
|
involving this context. A null context signifies that no special approval is |
| 1452 |
|
necessary. <o:p></o:p></span></p> |
| 1453 |
|
|
| 1454 |
<p class=MsoNormal><span class=SpellE><b style='mso-bidi-font-weight:normal'><span |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span |
| 1455 |
style='font-size:10.0pt;font-family:Arial'>initializeValidationData</span></b></span><b |
style='font-size:10.0pt'> <o:p></o:p></span></p> |
|
style='mso-bidi-font-weight:normal'><span style='font-size:10.0pt;font-family: |
|
|
Arial'>(</span></b><span class=SpellE><span style='font-size:10.0pt;font-family: |
|
|
Arial'>IProgressMonitor</span></span><b style='mso-bidi-font-weight:normal'><span |
|
|
style='font-size:10.0pt;font-family:Arial'>)<o:p></o:p></span></b></p> |
|
|
|
|
|
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>This hook |
|
|
allows changes to cache local validation data, or to hook up listeners to the |
|
|
model and listen for changes that may invalidate the change.<span |
|
|
style='mso-spacerun:yes'> </span>This protocol could be provided in the |
|
|
abstract <span class=SpellE>refactoring</span> class. <o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal><b style='mso-bidi-font-weight:normal'><span |
|
|
style='font-size:10.0pt;font-family:Arial'>dispose()<o:p></o:p></span></b></p> |
|
|
|
|
|
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Maps |
|
|
directly.<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal><span class=SpellE><b style='mso-bidi-font-weight:normal'><span |
|
|
style='font-size:10.0pt;font-family:Arial'>getName</span></b></span><b |
|
|
style='mso-bidi-font-weight:normal'><span style='font-size:10.0pt;font-family: |
|
|
Arial'>()<o:p></o:p></span></b></p> |
|
|
|
|
|
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Maps to <span |
|
|
class=SpellE>operation.getLabel</span><o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal><span class=SpellE><b style='mso-bidi-font-weight:normal'><span |
|
|
style='font-size:10.0pt;font-family:Arial'>isValid</span></b></span><b |
|
|
style='mso-bidi-font-weight:normal'><span style='font-size:10.0pt;font-family: |
|
|
Arial'>(<span class=SpellE>IProgressMonitor</span>)<o:p></o:p></span></b></p> |
|
|
|
|
|
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Maps to <span |
|
|
class=SpellE>canUndo</span>(), <span class=SpellE>canRedo</span>(), and <span |
|
|
class=SpellE>canExecute</span>().<span style='mso-spacerun:yes'> </span>See |
|
|
discussion below.<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal><b style='mso-bidi-font-weight:normal'><span |
|
|
style='font-size:10.0pt;font-family:Arial'>perform(<span class=SpellE>IProgressMonitor</span>)<o:p></o:p></span></b></p> |
|
|
|
|
|
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Maps to undo(<span |
|
|
class=SpellE>IProgressMonitor</span>), redo(<span class=SpellE>IProgressMonitor</span>) |
|
|
and <span class=SpellE>canExecute</span>(<span class=SpellE>IProgressMonitor</span>).<span |
|
|
style='mso-spacerun:yes'> </span>See discussion below.<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Issues<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='margin-left:.75in;text-indent:-.25in;mso-list:l17 level1 lfo20; |
|
|
tab-stops:list .75in'><![if !supportLists]><span style='font-size:10.0pt; |
|
|
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>-<span |
|
|
style='font:7.0pt "Times New Roman"'> |
|
|
</span></span></span><![endif]><span class=SpellE><span style='font-size:10.0pt; |
|
|
font-family:Arial'>Refactoring</span></span><span style='font-size:10.0pt; |
|
|
font-family:Arial'> change objects do not support direct undo() or redo().<span |
|
|
style='mso-spacerun:yes'> </span>Rather, a change that supports undo() returns |
|
|
a new change that “undoes” it whenever it is executed.<span |
|
|
style='mso-spacerun:yes'> </span>The code for <span class=SpellE>refactoring</span> |
|
|
changes would have to be <span class=SpellE>refactored</span> in one of these |
|
|
ways:<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='margin-left:1.25in;text-indent:-.25in;mso-list:l17 level2 lfo20; |
|
|
tab-stops:list 1.25in'><![if !supportLists]><span style='font-size:10.0pt; |
|
|
font-family:"Courier New";mso-fareast-font-family:"Courier New"'><span |
|
|
style='mso-list:Ignore'>o<span style='font:7.0pt "Times New Roman"'> |
|
|
</span></span></span><![endif]><span style='font-size:10.0pt;font-family:Arial'>Eliminate |
|
|
the creation of the undo change and move this work into an undo() method.<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='margin-left:1.25in;text-indent:-.25in;mso-list:l17 level2 lfo20; |
|
|
tab-stops:list 1.25in'><![if !supportLists]><span style='font-size:10.0pt; |
|
|
font-family:"Courier New";mso-fareast-font-family:"Courier New"'><span |
|
|
style='mso-list:Ignore'>o<span style='font:7.0pt "Times New Roman"'> |
|
|
</span></span></span><![endif]><span style='font-size:10.0pt;font-family:Arial'>Continue |
|
|
to create the undo change when performing a change, but instead of returning |
|
|
it, cache it in the change itself.<span style='mso-spacerun:yes'> </span>Undo |
|
|
protocol checks for the presence of this change and uses it for any undo |
|
|
validation or execution requests.<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal style='margin-left:.75in;text-indent:-.25in;mso-list:l17 level1 lfo20; |
|
|
tab-stops:list .75in'><![if !supportLists]><span style='font-size:10.0pt; |
|
|
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>-<span |
|
|
style='font:7.0pt "Times New Roman"'> |
|
|
</span></span></span><![endif]><span style='font-size:10.0pt;font-family:Arial'>Validation |
|
|
of <span class=SpellE>refactoring</span> changes is assumed to be expensive, so |
|
|
a progress monitor is provided in validation protocol.<span |
|
|
style='mso-spacerun:yes'> </span>This concept is not promoted to the framework |
|
|
since validity is checked when building the undo menu command.<span |
|
|
style='mso-spacerun:yes'> </span>Is the progress monitor absolutely necessary |
|
|
for validation vs. execution?<o:p></o:p></span></p> |
|
| 1456 |
|
|
| 1457 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><span |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the |
| 1458 |
style='mso-spacerun:yes'> </span><o:p></o:p></span></p> |
operation approver for the context.<o:p></o:p></span></p> |
| 1459 |
|
|
| 1460 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>It is |
<pre>public boolean <b>acceptOperation</b>(IOperation operation)</pre> |
|
likely that many views and editors in the workbench IDE will be aware of this special |
|
|
kind of <span class=SpellE>IOperation</span>.<span style='mso-spacerun:yes'> |
|
|
</span>An additional interface, <span class=SpellE>IWorkspaceOperation</span>, |
|
|
may evolve as <span class=SpellE>refactoring</span> changes are adapted to the |
|
|
new operations framework.<span style='mso-spacerun:yes'> </span>Patterns |
|
|
surrounding the workspace operation will develop, particularly involving |
|
|
operation contexts.<span style='mso-spacerun:yes'> </span>For example, views |
|
|
and editors (such as text editors) that are workspace-aware could listen to the |
|
|
operations history.<span style='mso-spacerun:yes'> </span>As new workspace |
|
|
operations are added to the history, the modified element can be queried by the |
|
|
listener.<span style='mso-spacerun:yes'> </span>The listener can add its |
|
|
operation context to the operation if desired.<span style='mso-spacerun:yes'> |
|
|
</span><o:p></o:p></span></p> |
|
| 1461 |
|
|
| 1462 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Return |
| 1463 |
|
a boolean that indicates whether this context should be assigned to the specified |
| 1464 |
|
operation. This method should be overridden by contexts that have complex rules |
| 1465 |
|
for whether they should be assigned to an operation. Simple contexts generally |
| 1466 |
|
answer true. <o:p></o:p></span></p> |
| 1467 |
|
|
| 1468 |
|
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span |
| 1469 |
|
style='font-size:10.0pt'> <o:p></o:p></span></p> |
| 1470 |
|
|
| 1471 |
|
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>a |
| 1472 |
|
boolean indicating whether this context should be assigned to the operation.<o:p></o:p></span></p> |
| 1473 |
|
|
| 1474 |
|
<pre>public boolean <b>equals</b>(IOperationContext context)</pre> |
| 1475 |
|
|
| 1476 |
|
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Return |
| 1477 |
|
whether this context is equal to the specified context. <o:p></o:p></span></p> |
| 1478 |
|
|
| 1479 |
|
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span |
| 1480 |
|
style='font-size:10.0pt'> <o:p></o:p></span></p> |
| 1481 |
|
|
| 1482 |
<h4>GEF</h4> |
<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>context</span></code><span |
| 1483 |
|
style='font-size:10.0pt'> - <o:p></o:p></span></p> |
| 1484 |
|
|
| 1485 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>GEF |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span |
| 1486 |
supplies a Command framework and a <span class=SpellE>CommandStack</span> which |
style='font-size:10.0pt'> <o:p></o:p></span></p> |
| 1487 |
manages an internal undo and redo stack.<span style='mso-spacerun:yes'> |
|
| 1488 |
</span>Commands are pushed onto the stack when they are executed by the stack.<span |
<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>true</span></code><span |
| 1489 |
style='mso-spacerun:yes'> </span>Most GEF command protocol can be mapped to |
style='font-size:10.0pt'> if the contexts are equal, </span><code><span |
| 1490 |
the proposed operation protocol.<span style='mso-spacerun:yes'> </span>The GEF |
style='font-size:10.0pt'>false</span></code><span style='font-size:10.0pt'> |
| 1491 |
commands are very similar to <span class=SpellE>IOperation</span> without the |
otherwise.<o:p></o:p></span></p> |
|
notion of contexts.<span style='mso-spacerun:yes'> </span><o:p></o:p></span></p> |
|
| 1492 |
|
|
| 1493 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
| 1494 |
|
|
| 1495 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Issues for |
<h3>IOperationApprover</h3> |
| 1496 |
GEF arise in the differences between <span class=SpellE>GEF’s</span> command |
|
| 1497 |
stack and the proposed operation history.<span style='mso-spacerun:yes'> |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>IOperationApprover |
| 1498 |
</span>We assume that GEF intends for GEF commands to coexist with other |
defines an interface for approving the undo or redo of a particular operation |
| 1499 |
workbench operations in a shared undo history.<span style='mso-spacerun:yes'> |
within an operation history. Operations that are candidates for undo or redo |
| 1500 |
</span>If so, then the command stack must be replaced by the operation |
have already been validated against their current state and according to the |
| 1501 |
history.<span style='mso-spacerun:yes'> </span>Issues include:<o:p></o:p></span></p> |
rules of the history.<o:p></o:p></span></p> |
| 1502 |
|
|
| 1503 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
| 1504 |
|
|
| 1505 |
<p class=MsoNormal><span class=SpellE><b style='mso-bidi-font-weight:normal'><span |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>By the time |
| 1506 |
style='font-size:10.0pt;font-family:Arial'>isDirty</span></b></span><b |
an IOperationApprover is consulted, the undo has already been requested. |
| 1507 |
style='mso-bidi-font-weight:normal'><span style='font-size:10.0pt;font-family: |
Approvers should true if the operation should proceed, and false if it should |
| 1508 |
Arial'>()<o:p></o:p></span></b></p> |
not. When an operation is rejected, it is expected that the object rejecting |
| 1509 |
|
the operation has already consulted the user if necessary or otherwise provided |
| 1510 |
<p class=MsoNormal><span class=SpellE><b style='mso-bidi-font-weight:normal'><span |
any necessary information to the user about the rejection.<o:p></o:p></span></p> |
|
style='font-size:10.0pt;font-family:Arial'>markSaveLocation</span></b></span><b |
|
|
style='mso-bidi-font-weight:normal'><span style='font-size:10.0pt;font-family: |
|
|
Arial'>()<o:p></o:p></span></b></p> |
|
|
|
|
|
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>GEF |
|
|
supports a marker (<span class=SpellE>saveLocation</span>) that becomes dirty |
|
|
if any commands are added after the mark is made.<span |
|
|
style='mso-spacerun:yes'> </span>If this concept is still needed in light of |
|
|
the new framework, then GEF might have to mark the location inside its own |
|
|
commands or using a dummy marker command.<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal><b style='mso-bidi-font-weight:normal'><span |
|
|
style='font-size:10.0pt;font-family:Arial'>execute(Command)<o:p></o:p></span></b></p> |
|
|
|
|
|
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>The GEF |
|
|
command stack executes commands on behalf of the client and adds them to the |
|
|
stack, while the operation history does not do the execution on behalf of the |
|
|
client.<span style='mso-spacerun:yes'> </span>GEF clients that create GEF |
|
|
commands would alter the pattern “<span class=SpellE>commandStack.execute</span>(<span |
|
|
class=SpellE>someCommand</span>)” to instead use “<span class=SpellE>someCommand.execute</span>(null); |
|
|
<span class=SpellE>operationHistory.add</span>(<span class=SpellE>someCommand</span>)”<span |
|
|
style='mso-spacerun:yes'> </span><o:p></o:p></span></p> |
|
| 1511 |
|
|
| 1512 |
<p class=MsoNormal><span class=SpellE><b style='mso-bidi-font-weight:normal'><span |
<pre>public org.eclipse.core.runtime.IStatus <b>proceedUndoing</b>(IOperation operation, IOperationHistory history)</pre> |
|
style='font-size:10.0pt;font-family:Arial'>addCommandStackListener</span></b></span><b |
|
|
style='mso-bidi-font-weight:normal'><span style='font-size:10.0pt;font-family: |
|
|
Arial'>(<span class=SpellE>CommandStackListener</span>)<o:p></o:p></span></b></p> |
|
|
|
|
|
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>GEF is |
|
|
evolving its <span class=SpellE>CommandListener</span> interface in R3.1 to |
|
|
include additional notification.<span style='mso-spacerun:yes'> </span>This |
|
|
must be reconciled with the proposed support in <span class=SpellE>IOperationHistoryListener</span> |
|
|
and the ability to further validate commands using <span class=SpellE>IOperationApproval</span>.<span |
|
|
style='mso-spacerun:yes'> </span><o:p></o:p></span></p> |
|
| 1513 |
|
|
| 1514 |
<h4>EMF/WTP</h4> |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Return |
| 1515 |
|
a status indicating whether the specified operation should be undone. Any |
| 1516 |
|
status that does not have severity </span><code><span style='font-size:10.0pt'>IStatus.OK</span></code><span |
| 1517 |
|
style='font-size:10.0pt'> will not be approved. Implementers should not assume |
| 1518 |
|
that the undo will be performed when the status is </span><code><span |
| 1519 |
|
style='font-size:10.0pt'>OK</span></code><span style='font-size:10.0pt'>, since |
| 1520 |
|
other operation approvers can veto the undo. <o:p></o:p></span></p> |
| 1521 |
|
|
| 1522 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>The EMF |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span |
| 1523 |
command framework is very similar to the GEF support and has similar issues to |
style='font-size:10.0pt'> <o:p></o:p></span></p> |
|
those described above.<span style='mso-spacerun:yes'> </span>Additional issues |
|
|
arise for:<o:p></o:p></span></p> |
|
| 1524 |
|
|
| 1525 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>operation</span></code><span |
| 1526 |
|
style='font-size:10.0pt'> - - the operation to be undone <o:p></o:p></span></p> |
| 1527 |
|
|
| 1528 |
<p class=MsoNormal><span class=SpellE><b style='mso-bidi-font-weight:normal'><span |
<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>history</span></code><span |
| 1529 |
style='font-size:10.0pt;font-family:Arial'>getResult</span></b></span><b |
style='font-size:10.0pt'> - - the history undoing the operation <o:p></o:p></span></p> |
|
style='mso-bidi-font-weight:normal'><span style='font-size:10.0pt;font-family: |
|
|
Arial'>();<o:p></o:p></span></b></p> |
|
|
|
|
|
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>This method |
|
|
answers the result of command execution when the command is in certain |
|
|
states.<span style='mso-spacerun:yes'> </span>Since clients can execute an |
|
|
operation explicitly in the framework, EMF code could query the result after |
|
|
execution and store it in an EMF abstract operation.<span |
|
|
style='mso-spacerun:yes'> </span>This protocol could then be provided in the |
|
|
EMF operations.<o:p></o:p></span></p> |
|
|
|
|
|
<p class=MsoNormal><span class=SpellE><b style='mso-bidi-font-weight:normal'><span |
|
|
style='font-size:10.0pt;font-family:Arial'>getAffectedObjects</span></b></span><b |
|
|
style='mso-bidi-font-weight:normal'><span style='font-size:10.0pt;font-family: |
|
|
Arial'>();<o:p></o:p></span></b></p> |
|
|
|
|
|
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>This method |
|
|
is used to highlight the appropriate objects in a view to show what the EMF command |
|
|
did.<span style='mso-spacerun:yes'> </span><span |
|
|
style='mso-spacerun:yes'> </span>It is not clear that this will be generally necessary.<span |
|
|
style='mso-spacerun:yes'> </span>This protocol could be added in an EMF |
|
|
operation abstract class.<o:p></o:p></span></p> |
|
| 1530 |
|
|
| 1531 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span |
| 1532 |
|
style='font-size:10.0pt'> <o:p></o:p></span></p> |
| 1533 |
|
|
| 1534 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>As |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the |
| 1535 |
discussed with <span class=SpellE>refactoring</span> changes, an abstract class |
IStatus describing whether the operation is approved. The undo will not proceed |
| 1536 |
providing the mapped protocol will likely evolve, along with usage patterns for |
if the status severity is not </span><code><span style='font-size:10.0pt'>OK</span></code><span |
| 1537 |
listening for new EMF operations and assigning appropriate operation contexts. <o:p></o:p></span></p> |
style='font-size:10.0pt'>, and the caller requesting the undo will be returned |
| 1538 |
|
the status that caused the rejection. Any other status severities will not be |
| 1539 |
<b><span style='font-size:16.0pt;font-family:Arial;mso-fareast-font-family: |
interpreted by the history.<o:p></o:p></span></p> |
|
"Times New Roman";mso-font-kerning:16.0pt;mso-ansi-language:EN-US;mso-fareast-language: |
|
|
EN-US;mso-bidi-language:AR-SA'><br clear=all style='page-break-before:always'> |
|
|
</span></b> |
|
| 1540 |
|
|
| 1541 |
<h1>Appendix A:<span style='mso-spacerun:yes'> </span>Workbench Undo Scenarios<span |
<pre>public org.eclipse.core.runtime.IStatus <b>proceedRedoing</b>(IOperation operation, IOperationHistory history)</pre> |
|
style='font-size:10.0pt'><o:p></o:p></span></h1> |
|
| 1542 |
|
|
| 1543 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>The |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Return |
| 1544 |
following scenarios were used while discussing possible designs for a common |
a status indicating whether the specified operation should be redone. Any |
| 1545 |
undo framework.<span style='mso-spacerun:yes'> </span><span |
status that does not have severity </span><code><span style='font-size:10.0pt'>IStatus.OK</span></code><span |
| 1546 |
style='mso-spacerun:yes'> </span>Most of these scenarios involve conflicting |
style='font-size:10.0pt'> will not be approved. Implementers should not assume |
| 1547 |
contexts or scopes.<span style='mso-spacerun:yes'> </span>These scenarios, |
that the redo will be performed when the status is </span><code><span |
| 1548 |
involving mixed text edits and <span class=SpellE>refactoring</span> |
style='font-size:10.0pt'>OK</span></code><span style='font-size:10.0pt'>, since |
| 1549 |
operations, have complicated previous efforts to define a common undo |
other operation approvers may veto the redo. <o:p></o:p></span></p> |
|
framework.<span style='mso-spacerun:yes'> </span><o:p></o:p></span></p> |
|
| 1550 |
|
|
| 1551 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span |
| 1552 |
|
style='font-size:10.0pt'> <o:p></o:p></span></p> |
| 1553 |
|
|
| 1554 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>The |
<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>operation</span></code><span |
| 1555 |
scenarios assume that an integrated undo in the workbench should present a |
style='font-size:10.0pt'> - - the operation to be redone <o:p></o:p></span></p> |
|
common “Undo” command rather than the separate commands employed today, and |
|
|
that the “Undo” command is descriptive enough to imply the operation that will |
|
|
take place.<o:p></o:p></span></p> |
|
| 1556 |
|
|
| 1557 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>history</span></code><span |
| 1558 |
|
style='font-size:10.0pt'> - - the history redoing the operation <o:p></o:p></span></p> |
| 1559 |
|
|
| 1560 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>For each |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span |
| 1561 |
scenario described, we attempt to describe the desired outcome, the outcome in |
style='font-size:10.0pt'> <o:p></o:p></span></p> |
|
R3.0.1 where applicable, and any interesting alternative outcomes. <o:p></o:p></span></p> |
|
| 1562 |
|
|
| 1563 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the |
| 1564 |
|
IStatus describing whether the operation is approved. The redo will not proceed |
| 1565 |
|
if the status severity is no </span><code><span style='font-size:10.0pt'>OK</span></code><span |
| 1566 |
|
style='font-size:10.0pt'>, and the caller requesting the redo will be returned |
| 1567 |
|
the status that caused the rejection. Any other status severities will not be |
| 1568 |
|
interpreted by the history.<o:p></o:p></span></p> |
| 1569 |
|
|
| 1570 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Note that |
<h3>IOperationHistoryListener</h3> |
|
some scenarios involve nearly the same user interactions, but are different in |
|
|
desired outcome based on what the user was trying to accomplish while |
|
|
performing the operations.<span style='mso-spacerun:yes'> </span>Specific user |
|
|
intent is described in order to clarify the scenario.<o:p></o:p></span></p> |
|
| 1571 |
|
|
| 1572 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<pre>public void <b>historyNotification</b>(OperationHistoryEvent event)</pre> |
| 1573 |
|
|
| 1574 |
<p class=MsoNormal><b style='mso-bidi-font-weight:normal'><span |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Something |
| 1575 |
style='font-size:10.0pt;font-family:Arial'>Scenario #1:</span></b><span |
of note has happened in the IOperationHistory. Listeners should check the |
| 1576 |
style='font-size:10.0pt;font-family:Arial'><span style='mso-spacerun:yes'> |
supplied event for details. <o:p></o:p></span></p> |
|
</span>User is editing source file “A.”<span style='mso-spacerun:yes'> |
|
|
</span>While editing the document, some interrupt occurs causing the user to go |
|
|
to the navigator and <span class=SpellE>refactor</span> some code unrelated to |
|
|
A.<span style='mso-spacerun:yes'> </span>When the <span class=SpellE>refactoring</span> |
|
|
is complete, the user returns to the editor on “A” and notices a typo.<span |
|
|
style='mso-spacerun:yes'> </span>The user selects Edit>Undo.<o:p></o:p></span></p> |
|
| 1577 |
|
|
| 1578 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><span |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span |
| 1579 |
style='mso-tab-count:1'> </span><o:p></o:p></span></p> |
style='font-size:10.0pt'> <o:p></o:p></span></p> |
| 1580 |
|
|
| 1581 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Desired |
<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>event</span></code><span |
| 1582 |
Outcome:<span style='mso-spacerun:yes'> </span>The last text editing operation |
style='font-size:10.0pt'> - - the OperationHistoryEvent that describes the |
| 1583 |
made before the unrelated <span class=SpellE>refactoring</span> operation is |
particular notification.<o:p></o:p></span></p> |
|
undone.<span style='mso-spacerun:yes'> </span>The typo is corrected.<span |
|
|
style='mso-spacerun:yes'> </span>The undo command was described as “undo |
|
|
typing”<o:p></o:p></span></p> |
|
| 1584 |
|
|
| 1585 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<h3>OperationHistoryEvent</h3> |
| 1586 |
|
|
| 1587 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>R3.0.1 |
<pre>public IOperationHistory <b>history</b></pre><pre><o:p> </o:p></pre><pre>public IOperation <b>operation</b></pre><pre><o:p> </o:p></pre><pre>public boolean <b>operationAdded</b>()</pre> |
|
Outcome:<span style='mso-spacerun:yes'> </span>Desired Outcome.<o:p></o:p></span></p> |
|
| 1588 |
|
|
| 1589 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Returns |
| 1590 |
|
whether or not an operation was added to the history. Listeners typically use |
| 1591 |
|
this to add their context to a new operation as appropriate or otherwise record |
| 1592 |
|
the operation. <o:p></o:p></span></p> |
| 1593 |
|
|
| 1594 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Proposal |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span |
| 1595 |
Outcome:<span style='mso-spacerun:yes'> </span>Desired Outcome.<span |
style='font-size:10.0pt'> <o:p></o:p></span></p> |
|
style='mso-spacerun:yes'> </span>(Unrelated <span class=SpellE>refactoring</span> |
|
|
operation did not have the editor’s context).<span style='mso-spacerun:yes'> |
|
|
</span><o:p></o:p></span></p> |
|
| 1596 |
|
|
| 1597 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>true</span></code><span |
| 1598 |
|
style='font-size:10.0pt'> if an operation has been added, </span><code><span |
| 1599 |
|
style='font-size:10.0pt'>false</span></code><span style='font-size:10.0pt'> if |
| 1600 |
|
not.<o:p></o:p></span></p> |
| 1601 |
|
|
| 1602 |
<p class=MsoNormal><b style='mso-bidi-font-weight:normal'><span |
<pre>public boolean <b>operationRemoved</b>()</pre> |
|
style='font-size:10.0pt;font-family:Arial'>Scenario #2:</span></b><span |
|
|
style='font-size:10.0pt;font-family:Arial'><span style='mso-spacerun:yes'> |
|
|
</span>User is editing source file “A.”<span style='mso-spacerun:yes'> |
|
|
</span>While editing the document, some interrupt occurs causing the user to go |
|
|
to the navigator and <span class=SpellE>refactor</span> some code.<span |
|
|
style='mso-spacerun:yes'> </span>The <span class=SpellE>refactoring</span> |
|
|
operation updates references to the <span class=SpellE>refactored</span> code |
|
|
in file “A.”<span style='mso-spacerun:yes'> </span>When the <span |
|
|
class=SpellE>refactoring</span> is complete, the user returns to the editor on |
|
|
“A” and notices a typo.<span style='mso-spacerun:yes'> </span>The user selects |
|
|
Edit>Undo.<o:p></o:p></span></p> |
|
| 1603 |
|
|
| 1604 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><span |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Returns |
| 1605 |
style='mso-tab-count:1'> </span><o:p></o:p></span></p> |
whether or not an operation was removed from the history. Listeners typically |
| 1606 |
|
remove any record of the operation that they may have kept in their own state. <o:p></o:p></span></p> |
| 1607 |
|
|
| 1608 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Desired |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span |
| 1609 |
Outcome:<span style='mso-spacerun:yes'> </span>This scenario depends largely |
style='font-size:10.0pt'> <o:p></o:p></span></p> |
|
on the user’s intent.<span style='mso-spacerun:yes'> </span>If the typo was in |
|
|
a location completely unrelated to the <span class=SpellE>refactor</span>, the |
|
|
user expects the last text editing operation made before the <span |
|
|
class=SpellE>refactoring</span> operation to be undone, correcting the |
|
|
typo.<span style='mso-spacerun:yes'> </span><o:p></o:p></span></p> |
|
| 1610 |
|
|
| 1611 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>true</span></code><span |
| 1612 |
|
style='font-size:10.0pt'> if an operation has been removed, </span><code><span |
| 1613 |
|
style='font-size:10.0pt'>false</span></code><span style='font-size:10.0pt'> if |
| 1614 |
|
not.<o:p></o:p></span></p> |
| 1615 |
|
|
| 1616 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>R3.0.1 |
<pre>public boolean <b>aboutToExecute</b>()</pre> |
|
Outcome:<span style='mso-spacerun:yes'> </span>The text edit caused by the <span |
|
|
class=SpellE>refactoring</span> operation is undone, but the <span |
|
|
class=SpellE>refactoring</span> itself is not undone.<span |
|
|
style='mso-spacerun:yes'> </span>The typo remains until the user invokes |
|
|
subsequent “Undo.”<o:p></o:p></span></p> |
|
| 1617 |
|
|
| 1618 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Returns |
| 1619 |
|
whether or not an operation is about to execute. Listeners should prepare for |
| 1620 |
|
the execution as appropriate. Listeners will receive a done notification if the |
| 1621 |
|
operation is successful, or an operationNotCompleted notification if the |
| 1622 |
|
execution is cancelled or otherwise fails. This notification is only received |
| 1623 |
|
for those operations executed by the operation history. Operations that are |
| 1624 |
|
added to the history after execution do not trigger these notifications. If the |
| 1625 |
|
operation successfully executes, clients will also receive a notification that |
| 1626 |
|
it has been added to the history. <o:p></o:p></span></p> |
| 1627 |
|
|
| 1628 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Proposal |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span |
| 1629 |
Outcome:<span style='mso-spacerun:yes'> </span>This outcome can be implemented |
style='font-size:10.0pt'> <o:p></o:p></span></p> |
|
in different ways.<span style='mso-spacerun:yes'> </span>If the <span |
|
|
class=SpellE>refactoring</span> operation command is assigned the context for |
|
|
“A,” since A was affected, then the <span class=SpellE>refactoring</span> |
|
|
operation would be undone before the typo.<span style='mso-spacerun:yes'> |
|
|
</span>However, the editor could notice that the operation has multiple contexts |
|
|
and prompt the user with an operation history.<span style='mso-spacerun:yes'> |
|
|
</span><o:p></o:p></span></p> |
|
| 1630 |
|
|
| 1631 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>true</span></code><span |
| 1632 |
|
style='font-size:10.0pt'> if an operation is about to execute, </span><code><span |
| 1633 |
|
style='font-size:10.0pt'>false</span></code><span style='font-size:10.0pt'> if |
| 1634 |
|
not.<o:p></o:p></span></p> |
| 1635 |
|
|
| 1636 |
<p class=MsoNormal><b style='mso-bidi-font-weight:normal'><span |
<pre>public boolean <b>aboutToUndo</b>()</pre> |
|
style='font-size:10.0pt;font-family:Arial'>Scenario #3:</span></b><span |
|
|
style='font-size:10.0pt;font-family:Arial'><span style='mso-spacerun:yes'> |
|
|
</span>User is editing source file “A.”<span style='mso-spacerun:yes'> |
|
|
</span>While editing the document, some interrupt occurs causing the user to go |
|
|
to the navigator and <span class=SpellE>refactor</span> some code.<span |
|
|
style='mso-spacerun:yes'> </span>The <span class=SpellE>refactoring</span> |
|
|
operation updates references to the <span class=SpellE>refactored</span> code |
|
|
in file “A.”<span style='mso-spacerun:yes'> </span>When the <span |
|
|
class=SpellE>refactoring</span> is complete, the user recalls making a typo |
|
|
just before the <span class=SpellE>refactor</span>.<span |
|
|
style='mso-spacerun:yes'> </span>The user returns to the editor on “A” and |
|
|
looks for the typo.<span style='mso-spacerun:yes'> </span>It is not there, as |
|
|
it has been replaced with new code due to the <span class=SpellE>refactoring</span> |
|
|
operation. The user selects Edit>Undo.<o:p></o:p></span></p> |
|
| 1637 |
|
|
| 1638 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><span |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Returns |
| 1639 |
style='mso-tab-count:1'> </span><o:p></o:p></span></p> |
whether or not an operation is about to be undone. Listeners should prepare for |
| 1640 |
|
the undo as appropriate. Listeners will receive an undone notification if the |
| 1641 |
|
operation is successful, or an operationNotCompleted notification if the undo |
| 1642 |
|
is cancelled or otherwise fails. <o:p></o:p></span></p> |
| 1643 |
|
|
| 1644 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Desired |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span |
| 1645 |
Outcome:<span style='mso-spacerun:yes'> </span>At this point, the user needs |
style='font-size:10.0pt'> <o:p></o:p></span></p> |
|
information that helps explain the disappearance of the typo.<span |
|
|
style='mso-spacerun:yes'> </span>In this case, there are two helpful options:<o:p></o:p></span></p> |
|
| 1646 |
|
|
| 1647 |
<ol style='margin-top:0in' start=1 type=1> |
<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>true</span></code><span |
| 1648 |
<li class=MsoNormal style='mso-list:l16 level1 lfo5;tab-stops:list .5in'><span |
style='font-size:10.0pt'> if an operation is about to undo, </span><code><span |
| 1649 |
style='font-size:10.0pt;font-family:Arial'>The last performed <span |
style='font-size:10.0pt'>false</span></code><span style='font-size:10.0pt'> if |
| 1650 |
class=SpellE>refactoring</span> operation is undone.<span |
not.<o:p></o:p></span></p> |
|
style='mso-spacerun:yes'> </span>This returns the user to the typo, in |
|
|
effect showing why the typo had disappeared.<span |
|
|
style='mso-spacerun:yes'> </span>The user then selects “Redo,” having |
|
|
been satisfied that the typo was corrected by the <span class=SpellE>refactoring</span> |
|
|
operation.<span style='mso-spacerun:yes'> </span>This operation is |
|
|
somewhat “heavyweight,” but one could argue that it’s the more expected |
|
|
outcome.<o:p></o:p></span></li> |
|
|
<li class=MsoNormal style='mso-list:l16 level1 lfo5;tab-stops:list .5in'><span |
|
|
style='font-size:10.0pt;font-family:Arial'>The text edit caused by the <span |
|
|
class=SpellE>refactoring</span> is undone, exposing the typo and, in |
|
|
effect, showing why it’s gone.<span style='mso-spacerun:yes'> </span>The |
|
|
user then selects “Redo,” having been satisfied that the typo was already |
|
|
corrected by the <span class=SpellE>refactoring</span> operation. <span |
|
|
style='mso-spacerun:yes'> </span>This is a “lighter weight” solution but |
|
|
perhaps more confusing.<o:p></o:p></span></li> |
|
|
</ol> |
|
| 1651 |
|
|
| 1652 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><span |
<pre>public boolean <b>aboutToRedo</b>()</pre> |
|
style='mso-spacerun:yes'> </span><o:p></o:p></span></p> |
|
| 1653 |
|
|
| 1654 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>R3.0.1 |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Returns |
| 1655 |
Outcome:<span style='mso-spacerun:yes'> </span>Desired Outcome #2.<o:p></o:p></span></p> |
whether or not an operation is about to be redone. Listeners should prepare for |
| 1656 |
|
the redo as appropriate. Listeners will receive a redone notification if the |
| 1657 |
|
operation is successful, or an operationNotCompleted notification if the redo |
| 1658 |
|
is cancelled or otherwise fails. <o:p></o:p></span></p> |
| 1659 |
|
|
| 1660 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span |
| 1661 |
|
style='font-size:10.0pt'> <o:p></o:p></span></p> |
| 1662 |
|
|
| 1663 |
|
<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>true</span></code><span |
| 1664 |
|
style='font-size:10.0pt'> if an operation is about to redo, </span><code><span |
| 1665 |
|
style='font-size:10.0pt'>false</span></code><span style='font-size:10.0pt'> if |
| 1666 |
|
not.<o:p></o:p></span></p> |
| 1667 |
|
|
| 1668 |
|
<pre>public boolean <b>done</b>()</pre> |
| 1669 |
|
|
| 1670 |
|
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Returns |
| 1671 |
|
whether or not an operation was initially done. Listeners can take appropriate |
| 1672 |
|
action, such as revealing any relevant state in the UI. This notification is |
| 1673 |
|
only received for those operations executed by the operation history. Operations |
| 1674 |
|
that are added to the history after execution do not trigger this notification. |
| 1675 |
|
Clients will also receive a notification that the operation has been added to |
| 1676 |
|
the history. <o:p></o:p></span></p> |
| 1677 |
|
|
| 1678 |
|
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span |
| 1679 |
|
style='font-size:10.0pt'> <o:p></o:p></span></p> |
| 1680 |
|
|
| 1681 |
|
<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>true</span></code><span |
| 1682 |
|
style='font-size:10.0pt'> if an operation has been done, </span><code><span |
| 1683 |
|
style='font-size:10.0pt'>false</span></code><span style='font-size:10.0pt'> if |
| 1684 |
|
not.<o:p></o:p></span></p> |
| 1685 |
|
|
| 1686 |
|
<pre>public boolean <b>undone</b>()</pre> |
| 1687 |
|
|
| 1688 |
|
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Returns |
| 1689 |
|
whether or not an operation was undone. Listeners can take appropriate action, |
| 1690 |
|
such as revealing any relevant state in the UI. <o:p></o:p></span></p> |
| 1691 |
|
|
| 1692 |
|
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span |
| 1693 |
|
style='font-size:10.0pt'> <o:p></o:p></span></p> |
| 1694 |
|
|
| 1695 |
|
<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>true</span></code><span |
| 1696 |
|
style='font-size:10.0pt'> if an operation has been undone, </span><code><span |
| 1697 |
|
style='font-size:10.0pt'>false</span></code><span style='font-size:10.0pt'> if |
| 1698 |
|
not.<o:p></o:p></span></p> |
| 1699 |
|
|
| 1700 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Proposal |
<pre>public boolean <b>redone</b>()</pre> |
| 1701 |
outcome:<span style='mso-spacerun:yes'> </span>Desired Outcome #1.<span |
|
| 1702 |
style='mso-spacerun:yes'> </span>This scenario is the same as scenario #2 |
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Returns |
| 1703 |
except for user intent, so the UI could present similar choices as described |
whether or not an operation was redone. Listeners can take appropriate action, |
| 1704 |
above.<span style='mso-spacerun:yes'> </span><o:p></o:p></span></p> |
such as revealing any relevant state in the UI. <o:p></o:p></span></p> |
| 1705 |
|
|
| 1706 |
|
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span |
| 1707 |
|
style='font-size:10.0pt'> <o:p></o:p></span></p> |
| 1708 |
|
|
| 1709 |
|
<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>true</span></code><span |
| 1710 |
|
style='font-size:10.0pt'> if an operation has been redone, </span><code><span |
| 1711 |
|
style='font-size:10.0pt'>false</span></code><span style='font-size:10.0pt'> if |
| 1712 |
|
not.<o:p></o:p></span></p> |
| 1713 |
|
|
| 1714 |
|
<pre>public boolean <b>operationNotOK</b>()</pre> |
| 1715 |
|
|
| 1716 |
|
<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Returns |
| 1717 |
|
whether or not an operation was attempted and not successful. Listeners |
| 1718 |
|
typically use this when they have prepared for an execute, undo, or redo, and |
| 1719 |
|
need to know that the operation did not successfully complete. For example, |
| 1720 |
|
listeners that turn redraw off before an operation is undone would turn redraw |
| 1721 |
|
on when the operation completes, or when this notification is received, since |
| 1722 |
|
there will be no notification of the completion. <o:p></o:p></span></p> |
| 1723 |
|
|
| 1724 |
|
<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span |
| 1725 |
|
style='font-size:10.0pt'> <o:p></o:p></span></p> |
| 1726 |
|
|
| 1727 |
|
<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>true</span></code><span |
| 1728 |
|
style='font-size:10.0pt'> if an operation has been redone, </span><code><span |
| 1729 |
|
style='font-size:10.0pt'>false</span></code><span style='font-size:10.0pt'> if |
| 1730 |
|
not.<o:p></o:p></span></p> |
| 1731 |
|
|
| 1732 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
| 1733 |
|
|
| 1734 |
<p class=MsoNormal><b style='mso-bidi-font-weight:normal'><span |
<h2>UI Support Classes<span style='font-size:10.0pt'><o:p></o:p></span></h2> |
|
style='font-size:10.0pt;font-family:Arial'>Scenario #4:</span></b><span |
|
|
style='font-size:10.0pt;font-family:Arial'><span style='mso-spacerun:yes'> |
|
|
</span>User is editing source file “A” and considers renaming a method in |
|
|
“A.”<span style='mso-spacerun:yes'> </span>While typing a new name for the |
|
|
method, the user realizes that a <span class=SpellE>refactoring</span> |
|
|
operation will simplify the editing process.<span style='mso-spacerun:yes'> |
|
|
</span>The user chooses “<span class=SpellE>Refactor</span>>Rename” to |
|
|
rename the method.<span style='mso-spacerun:yes'> </span>The <span |
|
|
class=SpellE>refactor</span> causes references to be updated in other |
|
|
files.<span style='mso-spacerun:yes'> </span>The user then decides that the |
|
|
rename was not appropriate.<span style='mso-spacerun:yes'> </span>The user selects |
|
|
Edit>Undo.<o:p></o:p></span></p> |
|
| 1735 |
|
|
| 1736 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><span |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Additional support |
| 1737 |
style='mso-tab-count:1'> </span><o:p></o:p></span></p> |
classes will be provided in the package org.eclipse.ui.operations.<span |
| 1738 |
|
style='mso-spacerun:yes'> </span>These classes handle policy decisions about |
| 1739 |
|
the undo model to be used by the workbench.<span style='mso-spacerun:yes'> |
| 1740 |
|
</span>Access to the undo and redo commands, as well as the operations history, |
| 1741 |
|
will be provided through workbench.<o:p></o:p></span></p> |
| 1742 |
|
|
| 1743 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Desired |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
|
Outcome:<span style='mso-spacerun:yes'> </span>The <span class=SpellE>refactoring</span> |
|
|
operation is undone, updating all of the references. The user is returned to |
|
|
the typing state before the <span class=SpellE>refactor</span>.<span |
|
|
style='mso-spacerun:yes'> </span>Selecting another Edit>Undo will undo the |
|
|
typing of the new name and return to the old name. <o:p></o:p></span></p> |
|
| 1744 |
|
|
| 1745 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><span |
<h3>Workbench Operation History</h3> |
|
style='mso-spacerun:yes'> </span><o:p></o:p></span></p> |
|
| 1746 |
|
|
| 1747 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>R3.0.1 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>The |
| 1748 |
Outcome:<span style='mso-spacerun:yes'> </span>The text edit implied by the <span |
workbench will manage a common operation history that can be used by any |
| 1749 |
class=SpellE>refactoring</span> operation is undone, and the user is returned |
plug-in to integrate its undo and redo history with the workbench.<span |
| 1750 |
to the typing state before the <span class=SpellE>refactor</span>.<span |
style='mso-spacerun:yes'> </span>This operation history will be accessible |
| 1751 |
style='mso-spacerun:yes'> </span>However, the <span class=SpellE>refactoring</span> |
through workbench API, to be determined by M5.<o:p></o:p></span></p> |
|
itself is not undone.<span style='mso-spacerun:yes'> </span>This is undoable |
|
|
from a separate <span class=SpellE>Refactor</span>>Undo.<o:p></o:p></span></p> |
|
| 1752 |
|
|
| 1753 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
| 1754 |
|
|
| 1755 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Proposal |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Contexts |
| 1756 |
outcome:<span style='mso-spacerun:yes'> </span>Desired Outcome.<span |
will be defined for text editors (with specialization for source editors) and |
| 1757 |
style='mso-spacerun:yes'> </span>A user prompt or verification may occur as |
for the workspace.<span style='mso-spacerun:yes'> </span>Throughout the |
| 1758 |
discussed in other scenarios.<o:p></o:p></span></p> |
development of R3.1, plug-ins will be encouraged to define operations that |
| 1759 |
|
represent their existing actions or command handlers.<span |
| 1760 |
|
style='mso-spacerun:yes'> </span>Additional contexts may be defined by |
| 1761 |
|
plug-ins.<o:p></o:p></span></p> |
| 1762 |
|
|
| 1763 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
| 1764 |
|
|
| 1765 |
<p class=MsoNormal><b style='mso-bidi-font-weight:normal'><span |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Existing |
| 1766 |
style='font-size:10.0pt;font-family:Arial'>Scenario #5:</span></b><span |
workbench actions will be modified to support undo by mapping existing |
| 1767 |
style='font-size:10.0pt;font-family:Arial'><span style='mso-spacerun:yes'> |
workbench actions and handlers to operations.<span style='mso-spacerun:yes'> |
| 1768 |
</span>User is editing source file “A” and considers renaming a method in |
</span>The operations will be added incrementally once the framework is in |
| 1769 |
“A.”<span style='mso-spacerun:yes'> </span>The user decides that a <span |
place.<span style='mso-spacerun:yes'> </span><o:p></o:p></span></p> |
|
class=SpellE>refactoring</span> operation is in order.<span |
|
|
style='mso-spacerun:yes'> </span>The user chooses “<span class=SpellE>Refactor</span>>Rename” |
|
|
to rename the method.<span style='mso-spacerun:yes'> </span>The <span |
|
|
class=SpellE>refactor</span> causes references to be updated in other |
|
|
files.<span style='mso-spacerun:yes'> </span>The user then makes additional |
|
|
edits to the <span class=SpellE>javadoc</span> for the renamed method and |
|
|
realizes that the rename was not appropriate.<span style='mso-spacerun:yes'> |
|
|
</span>The user selects Edit>Undo.<o:p></o:p></span></p> |
|
| 1770 |
|
|
| 1771 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><span |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
|
style='mso-tab-count:1'> </span><o:p></o:p></span></p> |
|
| 1772 |
|
|
| 1773 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Desired |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Operations |
| 1774 |
Outcome:<span style='mso-spacerun:yes'> </span>The most recent editing changes |
that are assigned the workspace context will implement a subinterface, |
| 1775 |
to the <span class=SpellE>javadoc</span> are undone.<span |
IWorkspaceOperation.<span style='mso-spacerun:yes'> </span>IWorkspaceOperation |
| 1776 |
style='mso-spacerun:yes'> </span>The user can continue selecting “Undo” until |
adds protocol to access the model elements manipulated by an operation |
| 1777 |
the <span class=SpellE>refactoring</span> operation is undone, updating all of |
(getElements()), so that listeners can decide if the workspace operation |
| 1778 |
the references. <o:p></o:p></span></p> |
affects their model.<span style='mso-spacerun:yes'> </span>This protocol is |
| 1779 |
|
not generalized to IOperation.<span style='mso-spacerun:yes'> </span>Prior |
| 1780 |
|
experience with model-based operation frameworks has shown that there needs to |
| 1781 |
|
be a very specific contract regarding how and when validation is performed, |
| 1782 |
|
what underlying model listeners are used to validate the operation, and whether |
| 1783 |
|
operations history notifications or internal model notifications are used to |
| 1784 |
|
maintain the validity of the operation and the undo stack.<span |
| 1785 |
|
style='mso-spacerun:yes'> </span>These details for IWorkspaceOperation will |
| 1786 |
|
evolve as more workbench operations are created. <o:p></o:p></span></p> |
| 1787 |
|
|
| 1788 |
|
<h3>UndoHandler and RedoHandler</h3> |
| 1789 |
|
|
| 1790 |
|
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>The |
| 1791 |
|
Edit>Undo and Edit>Redo commands should be handled by any parts that wish |
| 1792 |
|
to support undo.<span style='mso-spacerun:yes'> </span>Common handlers for the |
| 1793 |
|
undo and redo commands will be provided.<span style='mso-spacerun:yes'> |
| 1794 |
|
</span>These handlers can be assigned a context that should be used to filter |
| 1795 |
|
the undo and redo history.<span style='mso-spacerun:yes'> </span>The handlers |
| 1796 |
|
are responsible for the following:<o:p></o:p></span></p> |
| 1797 |
|
|
| 1798 |
|
<ul style='margin-top:0in' type=disc> |
| 1799 |
|
<li class=MsoNormal style='mso-list:l6 level1 lfo11;tab-stops:list .5in'><span |
| 1800 |
|
style='font-size:10.0pt;font-family:Arial'>Undo and Redo commands will be |
| 1801 |
|
enabled based on the status of the history.<o:p></o:p></span></li> |
| 1802 |
|
<li class=MsoNormal style='mso-list:l6 level1 lfo11;tab-stops:list .5in'><span |
| 1803 |
|
style='font-size:10.0pt;font-family:Arial'>The Undo and Redo commands will |
| 1804 |
|
be appended with the label of the operation for the handler’s context.<o:p></o:p></span></li> |
| 1805 |
|
<li class=MsoNormal style='mso-list:l6 level1 lfo11;tab-stops:list .5in'><span |
| 1806 |
|
style='font-size:10.0pt;font-family:Arial'>The undo and redo history will |
| 1807 |
|
be flushed for the handler’s context whenever the most recent operation in |
| 1808 |
|
the history is invalid.<span style='mso-spacerun:yes'> </span>This |
| 1809 |
|
aggressive maintenance of the history is the most conservative approach |
| 1810 |
|
for ensuring that the history contains valid operations, and this strategy |
| 1811 |
|
may evolve with experience.<o:p></o:p></span></li> |
| 1812 |
|
</ul> |
| 1813 |
|
|
| 1814 |
|
<h3>Undo and Redo Toolbar Items</h3> |
| 1815 |
|
|
| 1816 |
|
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Time |
| 1817 |
|
permitting, classes that support toolbar dropdown items for undo and redo will |
| 1818 |
|
be developed.<span style='mso-spacerun:yes'> </span>These will also be |
| 1819 |
|
assigned a context.<span style='mso-spacerun:yes'> </span>By clicking on the |
| 1820 |
|
drop-down arrow, the user will see the history for that particular |
| 1821 |
|
context.<span style='mso-spacerun:yes'> </span>The user will only be able to |
| 1822 |
|
select a range, starting from the top item, to be undone or redone.<span |
| 1823 |
|
style='mso-spacerun:yes'> </span>It is expected that the ability to view the |
| 1824 |
|
history is more valuable to the user than the ability to multi-select |
| 1825 |
|
operations for undo.<o:p></o:p></span></p> |
| 1826 |
|
|
| 1827 |
|
<h3>Operation Approvers</h3> |
| 1828 |
|
|
| 1829 |
|
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>The |
| 1830 |
|
workbench will provide and install an IOperationApprover that consults the |
| 1831 |
|
contexts of an operation to determine whether undo or redo should proceed.<span |
| 1832 |
|
style='mso-spacerun:yes'> </span>The policy is described as follows:<o:p></o:p></span></p> |
| 1833 |
|
|
| 1834 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
| 1835 |
|
|
| 1836 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>R3.0.1 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>The |
| 1837 |
Outcome:<span style='mso-spacerun:yes'> </span>The most recent editing changes |
workbench will allow undo or redo of any valid operation in the history, <i |
| 1838 |
to the <span class=SpellE>javadoc</span> are undone.<span |
style='mso-bidi-font-style:normal'>as long as there are no more recent |
| 1839 |
style='mso-spacerun:yes'> </span>The user can continue selecting “Undo” until |
operations in the history that share a context with the operation to be |
| 1840 |
the text edit implied by the <span class=SpellE>refactoring</span> operation is |
executed.</i> <span style='mso-spacerun:yes'> </span>If the operation to be |
| 1841 |
undone.<span style='mso-spacerun:yes'> </span>However, the <span class=SpellE>refactoring</span> |
undone or redone has contexts that are also present in operations appearing |
| 1842 |
itself is not undone.<span style='mso-spacerun:yes'> </span>This is undoable |
later in the history, then the undo or redo of the operation will not be |
| 1843 |
from a separate <span class=SpellE>Refactor</span>>Undo.<o:p></o:p></span></p> |
permitted.<o:p></o:p></span></p> |
| 1844 |
|
|
| 1845 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
| 1846 |
|
|
| 1847 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Proposal |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>A concrete |
| 1848 |
outcome:<span style='mso-spacerun:yes'> </span>Desired Outcome.<o:p></o:p></span></p> |
example will help explain this.<span style='mso-spacerun:yes'> </span><o:p></o:p></span></p> |
| 1849 |
|
|
| 1850 |
|
<ol style='margin-top:0in' start=1 type=1> |
| 1851 |
|
<li class=MsoNormal style='mso-list:l3 level1 lfo14;tab-stops:list .5in'><span |
| 1852 |
|
style='font-size:10.0pt;font-family:Arial'>The user makes local edits in |
| 1853 |
|
editor A.<o:p></o:p></span></li> |
| 1854 |
|
<li class=MsoNormal style='mso-list:l3 level1 lfo14;tab-stops:list .5in'><span |
| 1855 |
|
style='font-size:10.0pt;font-family:Arial'>The user initiates a |
| 1856 |
|
refactoring operation whose context is “A” and “workspace.”<o:p></o:p></span></li> |
| 1857 |
|
<li class=MsoNormal style='mso-list:l3 level1 lfo14;tab-stops:list .5in'><span |
| 1858 |
|
style='font-size:10.0pt;font-family:Arial'>The user makes additional local |
| 1859 |
|
edits to editor A.<o:p></o:p></span></li> |
| 1860 |
|
<li class=MsoNormal style='mso-list:l3 level1 lfo14;tab-stops:list .5in'><span |
| 1861 |
|
style='font-size:10.0pt;font-family:Arial'>The user goes to the navigator |
| 1862 |
|
and selects Undo.<o:p></o:p></span></li> |
| 1863 |
|
</ol> |
| 1864 |
|
|
| 1865 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
| 1866 |
|
|
| 1867 |
<p class=MsoNormal><b style='mso-bidi-font-weight:normal'><span |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>In the proposed |
| 1868 |
style='font-size:10.0pt;font-family:Arial'>Scenario #6:</span></b><span |
implementation, the navigator requests an undo for the workspace context.<span |
| 1869 |
style='font-size:10.0pt;font-family:Arial'><span style='mso-spacerun:yes'> |
style='mso-spacerun:yes'> </span>The refactoring operation triggered in the |
| 1870 |
</span>User is editing source file “A” and considers renaming a method in |
editor is the most recent operation that has the workspace context, but it also |
| 1871 |
“A.”<span style='mso-spacerun:yes'> </span>The user decides that a <span |
contains context “A.”<span style='mso-spacerun:yes'> </span>Since subsequent |
| 1872 |
class=SpellE>refactoring</span> operation is in order.<span |
operations in the history also have context “A,”, the operation will not be |
| 1873 |
style='mso-spacerun:yes'> </span>The user chooses “<span class=SpellE>Refactor</span>>Rename” |
allowed.<span style='mso-spacerun:yes'> </span>An explanation will be provided |
| 1874 |
to rename the method.<span style='mso-spacerun:yes'> </span>The <span |
to the user after the fact:<span style='mso-spacerun:yes'> </span>“Cannot undo |
| 1875 |
class=SpellE>refactor</span> causes references to be updated in other |
the refactoring operation because there have been subsequent changes to |
| 1876 |
files.<span style='mso-spacerun:yes'> </span>The user then proceeds to edit <span |
A.”<span style='mso-spacerun:yes'> </span><o:p></o:p></span></p> |
|
class=SpellE>javadoc</span> in another part of the file, unrelated to |
|
|
change.<span style='mso-spacerun:yes'> </span>The user realizes the <span |
|
|
class=SpellE>refactor</span> was not appropriate, and not wanting to undo the |
|
|
edits to the <span class=SpellE>javadoc</span>, selects the navigator view, and |
|
|
selects Edit>Undo, assuming that the navigator undo won’t affect local edit |
|
|
changes.<o:p></o:p></span></p> |
|
| 1877 |
|
|
| 1878 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><span |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
|
style='mso-tab-count:1'> </span><o:p></o:p></span></p> |
|
| 1879 |
|
|
| 1880 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Desired |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Future |
| 1881 |
Outcome:<span style='mso-spacerun:yes'> </span>The <span class=SpellE>refactoring</span> |
releases may warn the user or provide a preference to determine whether the |
| 1882 |
operation is undone, but the changes to the <span class=SpellE>javadoc</span> |
undo should proceed anyway, and whether the subsequent changes to “A” should |
| 1883 |
made afterward are not undone.<span style='mso-spacerun:yes'> </span>The local |
also be undone, or be flushed from the history. Early prototypes of the |
| 1884 |
changes to file “A” could only be undone while inside editor A.<o:p></o:p></span></p> |
framework showed that such warnings interrupt workflow and can be very |
| 1885 |
|
difficult to understand, so the initial UI will be to prohibit the undo, |
| 1886 |
|
explaining why.<span style='mso-spacerun:yes'> </span><o:p></o:p></span></p> |
| 1887 |
|
|
| 1888 |
|
<h2>Migration Examples</h2> |
| 1889 |
|
|
| 1890 |
|
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>The |
| 1891 |
|
following examples explain how existing code can be migrated to use the |
| 1892 |
|
operations framework.<span style='mso-spacerun:yes'> </span>An early prototype |
| 1893 |
|
used these techniques to integrate the SDK text editor, refactoring framework, |
| 1894 |
|
and sample applications into a common undo framework.<span |
| 1895 |
|
style='mso-spacerun:yes'> </span></span></p> |
| 1896 |
|
|
| 1897 |
|
<h3>Mapping existing actions or command handlers to operations</h3> |
| 1898 |
|
|
| 1899 |
|
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Converting |
| 1900 |
|
an existing action to use operations is straightforward, apart from |
| 1901 |
|
implementing the undo and redo behavior for the action.<span |
| 1902 |
|
style='mso-spacerun:yes'> </span>The run() or runWithEvent method inside the |
| 1903 |
|
action should create an operation, execute it, and add it to the operations |
| 1904 |
|
history, rather than run the code inside the method.<span |
| 1905 |
|
style='mso-spacerun:yes'> </span>The following code shows the existing run() |
| 1906 |
|
method in the EditorAction of the readme tool example |
| 1907 |
|
(org.eclipse.ui.examples.readmetool):<o:p></o:p></span></p> |
| 1908 |
|
|
| 1909 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
| 1910 |
|
|
| 1911 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>R3.0.1 |
<pre>public void run() {</pre><pre><span style='mso-spacerun:yes'> </span>String editorName = MessageUtil.getString("Empty_Editor_Name"); </pre><pre><span style='mso-spacerun:yes'> </span>if (activeEditor != null)</pre><pre><span style='mso-spacerun:yes'> </span>editorName = activeEditor.getTitle();</pre><pre><span style='mso-spacerun:yes'> </span>MessageDialog</pre><pre><span style='mso-spacerun:yes'> </span>.openInformation(</pre><pre><span style='mso-spacerun:yes'> </span>shell,</pre><pre><span style='mso-spacerun:yes'> </span>MessageUtil.getString("Readme_Editor"), </pre><pre><span style='mso-spacerun:yes'> </span>MessageUtil.format("ReadmeEditorActionExecuted", </pre><pre><span |
| 1912 |
Outcome:<span style='mso-spacerun:yes'> </span>The <span class=SpellE>refactoring</span> |
style='mso-tab-count:4'> </span>new Object[] { getText(), editorName })); </pre><pre><span style='mso-spacerun:yes'> </span>}</pre><pre><span |
| 1913 |
operation is undone, and the most recent changes to the file are lost.<o:p></o:p></span></p> |
style='font-family:Arial'>Using operations, the run method simplifies:<o:p></o:p></span></pre><pre><span |
| 1914 |
|
style='font-family:Arial'><o:p> </o:p></span></pre><pre><span style='mso-spacerun:yes'> </span>public void run() {</pre><pre><span style='mso-spacerun:yes'> </span>String editorName = MessageUtil.getString("Empty_Editor_Name"); </pre><pre><span style='mso-spacerun:yes'> </span><span style='mso-spacerun:yes'> </span>if (activeEditor != null)</pre><pre><span style='mso-spacerun:yes'> </span>editorName = activeEditor.getTitle();</pre><pre><span style='mso-spacerun:yes'> </span>// create the operation</pre><pre><span style='mso-spacerun:yes'> </span>IOperation operation = new EditorOperation(</pre><pre><span |
| 1915 |
|
style='mso-tab-count:2'> </span>getText(),shell, editorName);</pre><pre><span style='mso-spacerun:yes'> </span>// execute (and add to the history)</pre><pre><span style='mso-spacerun:yes'> </span>history.execute(operation, null);</pre><pre><span style='mso-spacerun:yes'> </span>}</pre><pre><span |
| 1916 |
|
style='font-family:Arial'>The operation encapsulates the old run behavior, as well as the undo and redo for the operation:<o:p></o:p></span></pre><pre><span |
| 1917 |
|
style='font-family:Arial'><o:p> </o:p></span></pre><pre>class EditorOperation extends AbstractOperation {</pre><pre><span style='mso-spacerun:yes'> </span>Shell fShell;</pre><pre><span style='mso-spacerun:yes'> </span>String fEditorName;</pre><pre><span style='mso-spacerun:yes'> </span>public EditorOperation(String label, Shell shell, String editorName) {</pre><pre><span style='mso-spacerun:yes'> </span>super(label);</pre><pre><span style='mso-spacerun:yes'> </span>fShell = shell;</pre><pre><span style='mso-spacerun:yes'> </span>fEditorName = editorName;</pre><pre><span style='mso-spacerun:yes'> </span></pre><pre><span style='mso-spacerun:yes'> </span>}</pre><pre><span style='mso-spacerun:yes'> </span>public IStatus execute(IProgressMonitor monitor) {</pre><pre><span style='mso-spacerun:yes'> </span>MessageDialog.openInformation(</pre><pre><span style='mso-spacerun:yes'> </span>fShell,</pre><pre><span style='mso-spacerun:yes'> </span>MessageUtil.getString("Readme_Editor"), </pre><pre><span style='mso-spacerun:yes'> </span>MessageUtil.format("ReadmeEditorActionExecuted", </pre><pre><span |
| 1918 |
|
style='mso-tab-count:3'> </span>new Object[] { getLabel(), fEditorName }));<span style='mso-spacerun:yes'> </span></pre><pre><span style='mso-spacerun:yes'> </span>return Status.OK_STATUS;</pre><pre><span style='mso-spacerun:yes'> </span>}</pre><pre><span style='mso-spacerun:yes'> </span>public IStatus undo(IProgressMonitor monitor) {</pre><pre><span style='mso-spacerun:yes'> </span>// implement the undo here</pre><pre><span style='mso-spacerun:yes'> </span>return Status.OK_STATUS;</pre><pre><span style='mso-spacerun:yes'> </span>}</pre><pre><span style='mso-spacerun:yes'> </span>public IStatus redo(IProgressMonitor monitor) {</pre><pre><span style='mso-spacerun:yes'> </span>// implement the redo here</pre><pre><span style='mso-spacerun:yes'> </span>return Status.OK_STATUS;</pre><pre><span style='mso-spacerun:yes'> </span>}</pre><pre><span style='mso-spacerun:yes'> </span>}</pre><pre><o:p> </o:p></pre><pre><span |
| 1919 |
|
style='font-family:Arial'>If an IHandler is provided for a command instead of using actions, the execute method of the handler is mapped similarly to the run method in an action:<o:p></o:p></span></pre><pre><span |
| 1920 |
|
style='font-family:Arial'><o:p> </o:p></span></pre><pre><span style='mso-spacerun:yes'> </span>public Object execute(Map params) throws ExecutionException {</pre><pre><span style='mso-spacerun:yes'> </span>try {</pre><pre><span |
| 1921 |
|
style='mso-tab-count:1'> </span><span style='mso-spacerun:yes'> </span>IEditorPart activeEditor = params.get("ACTIVE_EDITOR");</pre><pre><span |
| 1922 |
|
style='mso-tab-count:1'> </span><span style='mso-spacerun:yes'> </span>Shell shell = params.get("SHELL");</pre><pre><span |
| 1923 |
|
style='mso-tab-count:1'> </span><span style='mso-spacerun:yes'> </span>String label = params.get("NAME");</pre><pre><span |
| 1924 |
|
style='mso-tab-count:1'> </span><span style='mso-spacerun:yes'> </span>String editorName = MessageUtil.getString("Empty_Editor_Name"); </pre><pre><span style='mso-spacerun:yes'> </span>if (activeEditor != null)</pre><pre><span style='mso-spacerun:yes'> </span>editorName = activeEditor.getTitle();</pre><pre><span style='mso-spacerun:yes'> </span>// create the operation</pre><pre><span style='mso-spacerun:yes'> </span>IOperation operation =new EditorOperation(label, shell, editorName);</pre><pre><o:p> </o:p></pre><pre><span style='mso-spacerun:yes'> </span>// execute (and add to the history)</pre><pre><span style='mso-spacerun:yes'> </span>history.execute(operation, null);</pre><pre><span style='mso-spacerun:yes'> </span>} catch (Exception e) {</pre><pre><span style='mso-spacerun:yes'> </span>throw new ExecutionException(</pre><pre><span style='mso-spacerun:yes'> </span>"While executing the operation, an exception occurred", e); </pre><pre><span style='mso-spacerun:yes'> </span>}</pre><pre><span style='mso-spacerun:yes'> </span>return null;</pre><pre><span style='mso-spacerun:yes'> </span>}</pre><pre><span |
| 1925 |
|
style='font-family:Arial'><o:p> </o:p></span></pre><pre><span |
| 1926 |
|
style='font-family:Arial'>When an action launches a wizard. then the operation is typically created as part of processing the “Finish” button in the wizard.<span style='mso-spacerun:yes'> </span>Some restructuring may be required.<span style='mso-spacerun:yes'> </span>For example, wizards are often implemented in hierarchies and make use of convenience methods in the wizard hierarchy.<span style='mso-spacerun:yes'> </span>Some of these methods may have to move to a corresponding hierarchy of operations.</span> </pre> |
| 1927 |
|
|
| 1928 |
|
<h3>Refactoring example:<span style='mso-spacerun:yes'> </span>mapping |
| 1929 |
|
existing protocol to IOperation</h3> |
| 1930 |
|
|
| 1931 |
|
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>In the |
| 1932 |
|
current SDK implementation, org.eclipse.ltk.core.refactoring provides an undo |
| 1933 |
|
framework for undoing refactoring operations.<span style='mso-spacerun:yes'> |
| 1934 |
|
</span>This framework is based on the notion of “Change” objects.<span |
| 1935 |
|
style='mso-spacerun:yes'> </span>Change objects that can be undone are |
| 1936 |
|
responsible for returning the undo version of a change when they are |
| 1937 |
|
executed.<span style='mso-spacerun:yes'> </span>An undo stack is maintained by |
| 1938 |
|
an internal undo manager.<span style='mso-spacerun:yes'> </span>This undo |
| 1939 |
|
manager invalidates the history whenever an unknown workspace change |
| 1940 |
|
occurs.<span style='mso-spacerun:yes'> </span>Undo-aware objects send signals |
| 1941 |
|
to the undo manager as they perform operations, so that the undo manager will |
| 1942 |
|
not invalidate the history.<o:p></o:p></span></p> |
| 1943 |
|
|
| 1944 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
| 1945 |
|
|
| 1946 |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Proposal |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>A prototype |
| 1947 |
outcome:<span style='mso-spacerun:yes'> </span>This can be implemented in |
integrated the refactoring change framework with the operations framework as |
| 1948 |
different ways with <span class=SpellE>IOperationApproval</span>.<span |
follows:<o:p></o:p></span></p> |
|
style='mso-spacerun:yes'> </span>The operation history would notice that the |
|
|
chosen operation has context “A” and that later changes for “A” are in the |
|
|
history.<span style='mso-spacerun:yes'> </span>The <span class=SpellE>IOperationApproval</span> |
|
|
assigned to context “A” could prompt the user as to whether to undo the more |
|
|
recent changes in “A.”<o:p></o:p></span></p> |
|
| 1949 |
|
|
| 1950 |
<p class=MsoNormal style='text-align:justify'><span style='font-size:10.0pt; |
<p class=MsoNormal style='margin-left:39.0pt;text-indent:-.25in;mso-list:l4 level1 lfo16; |
| 1951 |
font-family:Arial'><o:p> </o:p></span></p> |
tab-stops:list 39.0pt'><![if !supportLists]><span style='font-size:10.0pt; |
| 1952 |
|
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>1.<span |
| 1953 |
|
style='font:7.0pt "Times New Roman"'> </span></span></span><![endif]><span |
| 1954 |
|
style='font-size:10.0pt;font-family:Arial'>The change objects were wrappered |
| 1955 |
|
with a class that implements IOperation (and IWorkspaceOperation) and maps the |
| 1956 |
|
operation protocol to the Change protocol.<o:p></o:p></span></p> |
| 1957 |
|
|
| 1958 |
</div> |
<p class=MsoNormal style='margin-left:39.0pt;text-indent:-.25in;mso-list:l4 level1 lfo16; |
| 1959 |
|
tab-stops:list 39.0pt'><![if !supportLists]><span style='font-size:10.0pt; |
| 1960 |
|
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>2.<span |
| 1961 |
|
style='font:7.0pt "Times New Roman"'> </span></span></span><![endif]><span |
| 1962 |
|
style='font-size:10.0pt;font-family:Arial'>The refactoring undo manager was |
| 1963 |
|
replaced with an alternate implementation that uses the operations history to |
| 1964 |
|
maintain the undo and redo history.<o:p></o:p></span></p> |
| 1965 |
|
|
| 1966 |
<div style='mso-element:footnote-list'><![if !supportFootnotes]><br clear=all> |
<p class=MsoNormal style='margin-left:39.0pt;text-indent:-.25in;mso-list:l4 level1 lfo16; |
| 1967 |
|
tab-stops:list 39.0pt'><![if !supportLists]><span style='font-size:10.0pt; |
| 1968 |
|
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>3.<span |
| 1969 |
|
style='font:7.0pt "Times New Roman"'> </span></span></span><![endif]><span |
| 1970 |
|
style='font-size:10.0pt;font-family:Arial'>The workspace listener and |
| 1971 |
|
validation strategy used in the Change framework was maintained since the |
| 1972 |
|
timing of the notifications was critical.<span style='mso-spacerun:yes'> |
| 1973 |
|
</span>Additional integration work could be done to use the operations history |
| 1974 |
|
listeners for the same purpose, or to change the validation strategy as more |
| 1975 |
|
workspace operations are supported outside of refactoring.<o:p></o:p></span></p> |
| 1976 |
|
|
| 1977 |
<hr align=left size=1 width="33%"> |
<p class=MsoNormal style='margin-left:39.0pt;text-indent:-.25in;mso-list:l4 level1 lfo16; |
| 1978 |
|
tab-stops:list 39.0pt'><![if !supportLists]><span style='font-size:10.0pt; |
| 1979 |
|
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>4.<span |
| 1980 |
|
style='font:7.0pt "Times New Roman"'> </span></span></span><![endif]><span |
| 1981 |
|
style='font-size:10.0pt;font-family:Arial'>Unrelated listeners (such as text |
| 1982 |
|
editors) listened for new operations being added.<span |
| 1983 |
|
style='mso-spacerun:yes'> </span>These listeners could check the elements |
| 1984 |
|
affected by the workspace operation and determine whether another context |
| 1985 |
|
should be assigned to the operation.<o:p></o:p></span></p> |
| 1986 |
|
|
| 1987 |
<![endif]> |
<p class=MsoNormal style='margin-left:39.0pt;text-indent:-.25in;mso-list:l4 level1 lfo16; |
| 1988 |
|
tab-stops:list 39.0pt'><![if !supportLists]><span style='font-size:10.0pt; |
| 1989 |
|
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>5.<span |
| 1990 |
|
style='font:7.0pt "Times New Roman"'> </span></span></span><![endif]><span |
| 1991 |
|
style='font-size:10.0pt;font-family:Arial'>Refactoring operations could be |
| 1992 |
|
undone and redone from any view or editor that installed the undo and redo |
| 1993 |
|
handlers on the workspace context.<o:p></o:p></span></p> |
| 1994 |
|
|
| 1995 |
|
<h3>Text editor example:<span style='mso-spacerun:yes'> </span>implementing |
| 1996 |
|
IOperation in preexisting commands</h3> |
| 1997 |
|
|
| 1998 |
|
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>The JFace |
| 1999 |
|
text framework supports undo and redo of text editing operations.<span |
| 2000 |
|
style='mso-spacerun:yes'> </span>This implementation relies on private undo |
| 2001 |
|
stacks that are maintained by each editor.<span style='mso-spacerun:yes'> |
| 2002 |
|
</span>The JFace IUndoManager listens to text changes coming from the |
| 2003 |
|
underlying widget, and builds a TextCommand for each undoable edit.<span |
| 2004 |
|
style='mso-spacerun:yes'> </span><o:p></o:p></span></p> |
| 2005 |
|
|
| 2006 |
<div style='mso-element:footnote' id=ftn1> |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p> </o:p></span></p> |
| 2007 |
|
|
| 2008 |
<p class=MsoNormal><a style='mso-footnote-id:ftn1' href="#_ftnref1" name="_ftn1" |
<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>A prototype |
| 2009 |
title=""><span class=MsoFootnoteReference><span style='mso-special-character: |
integrated the text undo in JFace with the operations framework as follows:<o:p></o:p></span></p> |
|
footnote'><![if !supportFootnotes]><span class=MsoFootnoteReference><span |
|
|
style='font-size:12.0pt;font-family:"Times New Roman";mso-fareast-font-family: |
|
|
"Times New Roman";mso-ansi-language:EN-US;mso-fareast-language:EN-US; |
|
|
mso-bidi-language:AR-SA'>[1]</span></span><![endif]></span></span></a> <span |
|
|
style='font-size:10.0pt;font-family:Arial'>Literature addressing multi-user |
|
|
undo [<span class=SpellE>Abowd</span> & Dix] addresses similar scoping |
|
|
issues in a multi-user model.<span style='mso-spacerun:yes'> |
|
|
</span>Collaborating users may expect a global undo scope while users working |
|
|
in separate contexts may not.<span style='mso-spacerun:yes'> </span>Users may |
|
|
be moving between collaboration and separation in a single work session, and the |
|
|
system cannot detect which is the case.<span style='mso-spacerun:yes'> |
|
|
</span>Undo implementations in these systems typically keep track of the user |
|
|
who initiated the operation within a global history and filter the history |
|
|
appropriately.<span style='mso-spacerun:yes'> </span>Potential conflicts are |
|
|
brought to the attention of the user(s).<o:p></o:p></span></p> |
|
| 2010 |
|
|
| 2011 |
<p class=MsoFootnoteText><o:p> </o:p></p> |
<ol style='margin-top:0in' start=1 type=1> |
| 2012 |
|
<li class=MsoNormal style='mso-list:l5 level1 lfo19;tab-stops:list .5in'><span |
| 2013 |
|
style='font-size:10.0pt;font-family:Arial'>The existing TextCommand was |
| 2014 |
|
altered to implement the IOperation interface.<o:p></o:p></span></li> |
| 2015 |
|
<li class=MsoNormal style='mso-list:l5 level1 lfo19;tab-stops:list .5in'><span |
| 2016 |
|
style='font-size:10.0pt;font-family:Arial'>Specialized contexts (one |
| 2017 |
|
instance for each text editor) are assigned to the operations.<o:p></o:p></span></li> |
| 2018 |
|
<li class=MsoNormal style='mso-list:l5 level1 lfo19;tab-stops:list .5in'><span |
| 2019 |
|
style='font-size:10.0pt;font-family:Arial'>The existing UndoManager was |
| 2020 |
|
replaced with an alternate implementation that added text commands to the |
| 2021 |
|
operations history instead of a local stack, and used the operation |
| 2022 |
|
history protocol when handling undo and redo commands.<o:p></o:p></span></li> |
| 2023 |
|
<li class=MsoNormal style='mso-list:l5 level1 lfo19;tab-stops:list .5in'><span |
| 2024 |
|
style='font-size:10.0pt;font-family:Arial'>The undo manager installs a |
| 2025 |
|
listener on the history to monitor new operations that are added to the |
| 2026 |
|
history.<o:p></o:p></span></li> |
| 2027 |
|
<li class=MsoNormal style='mso-list:l5 level1 lfo19;tab-stops:list .5in'><span |
| 2028 |
|
style='font-size:10.0pt;font-family:Arial'>When an “outside” operation is |
| 2029 |
|
added to the history, the undo manager consults the editor’s operation |
| 2030 |
|
context to see if the outside operation is relevant.<span |
| 2031 |
|
style='mso-spacerun:yes'> </span>The editor context can check the |
| 2032 |
|
elements affected by workspace operations and add itself to the |
| 2033 |
|
operation’s context if appropriate.<o:p></o:p></span></li> |
| 2034 |
|
</ol> |
| 2035 |
|
|
| 2036 |
</div> |
<p class=MsoNormal style='text-align:justify'><span style='font-size:10.0pt; |
| 2037 |
|
font-family:Arial'><o:p> </o:p></span></p> |
| 2038 |
|
|
| 2039 |
</div> |
</div> |
| 2040 |
|
|
Parent Directory
| 
Revision Log
| 
Patch