platform-ui-home/R3_1/undo-redo-proposal/undo-redo support.html

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1.4 - (download) (as text) (annotate)
Mon Dec 20 22:54:58 2004 UTC (4 years, 11 months ago) by sfranklin
Branch: MAIN
Changes since 1.3: +624 -488 lines 
formatting change

<html xmlns:v="urn:schemas-microsoft-com:vml"
xmlns:o="urn:schemas-microsoft-com:office:office"
xmlns:w="urn:schemas-microsoft-com:office:word"
xmlns:st1="urn:schemas-microsoft-com:office:smarttags"
xmlns="http://www.w3.org/TR/REC-html40">

<head>
<meta http-equiv=Content-Type content="text/html; charset=windows-1252">
<meta name=ProgId content=Word.Document>
<meta name=Generator content="Microsoft Word 10">
<meta name=Originator content="Microsoft Word 10">
<link rel=File-List href="undo-redo%20support_files/filelist.xml">
<title>Undo/redo support in Eclipse</title>
<o:SmartTagType namespaceuri="urn:schemas-microsoft-com:office:smarttags"
 name="date"/>
<!--[if gte mso 9]><xml>
 <o:DocumentProperties>
  <o:Author>IBM_USER</o:Author>
  <o:LastAuthor>IBM_USER</o:LastAuthor>
  <o:Revision>8</o:Revision>
  <o:TotalTime>4519</o:TotalTime>
  <o:LastPrinted>2004-11-08T17:14:00Z</o:LastPrinted>
  <o:Created>2004-12-20T21:30:00Z</o:Created>
  <o:LastSaved>2004-12-20T22:54:00Z</o:LastSaved>
  <o:Pages>1</o:Pages>
  <o:Words>6341</o:Words>
  <o:Characters>36147</o:Characters>
  <o:Company>IBM</o:Company>
  <o:Lines>301</o:Lines>
  <o:Paragraphs>84</o:Paragraphs>
  <o:CharactersWithSpaces>42404</o:CharactersWithSpaces>
  <o:Version>10.6626</o:Version>
 </o:DocumentProperties>
</xml><![endif]--><!--[if gte mso 9]><xml>
 <w:WordDocument>
  <w:SpellingState>Clean</w:SpellingState>
  <w:GrammarState>Clean</w:GrammarState>
  <w:Compatibility>
   <w:BreakWrappedTables/>
   <w:SnapToGridInCell/>
   <w:WrapTextWithPunct/>
   <w:UseAsianBreakRules/>
  </w:Compatibility>
  <w:BrowserLevel>MicrosoftInternetExplorer4</w:BrowserLevel>
 </w:WordDocument>
</xml><![endif]--><!--[if !mso]><object
 classid="clsid:38481807-CA0E-42D2-BF39-B33AF135CC4D" id=ieooui></object>
<style>
st1\:*{behavior:url(#ieooui) }
</style>
<![endif]-->
<style>
<!--
 /* Font Definitions */
 @font-face
	{font-family:Wingdings;
	panose-1:5 0 0 0 0 0 0 0 0 0;
	mso-font-charset:2;
	mso-generic-font-family:auto;
	mso-font-pitch:variable;
	mso-font-signature:0 268435456 0 0 -2147483648 0;}
 /* Style Definitions */
 p.MsoNormal, li.MsoNormal, div.MsoNormal
	{mso-style-parent:"";
	margin:0in;
	margin-bottom:.0001pt;
	mso-pagination:widow-orphan;
	font-size:12.0pt;
	font-family:"Times New Roman";
	mso-fareast-font-family:"Times New Roman";}
h1
	{mso-style-next:Normal;
	margin-top:12.0pt;
	margin-right:0in;
	margin-bottom:3.0pt;
	margin-left:0in;
	mso-pagination:widow-orphan;
	page-break-after:avoid;
	mso-outline-level:1;
	font-size:16.0pt;
	font-family:Arial;
	mso-font-kerning:16.0pt;}
h2
	{mso-style-next:Normal;
	margin-top:12.0pt;
	margin-right:0in;
	margin-bottom:3.0pt;
	margin-left:0in;
	mso-pagination:widow-orphan;
	page-break-after:avoid;
	mso-outline-level:2;
	font-size:14.0pt;
	font-family:Arial;
	font-style:italic;}
h3
	{mso-style-next:Normal;
	margin-top:12.0pt;
	margin-right:0in;
	margin-bottom:3.0pt;
	margin-left:0in;
	mso-pagination:widow-orphan;
	page-break-after:avoid;
	mso-outline-level:3;
	font-size:13.0pt;
	font-family:Arial;}
h4
	{mso-style-next:Normal;
	margin-top:12.0pt;
	margin-right:0in;
	margin-bottom:3.0pt;
	margin-left:0in;
	mso-pagination:widow-orphan;
	page-break-after:avoid;
	mso-outline-level:4;
	font-size:14.0pt;
	font-family:"Times New Roman";}
h5
	{mso-style-next:Normal;
	margin-top:12.0pt;
	margin-right:0in;
	margin-bottom:3.0pt;
	margin-left:0in;
	mso-pagination:widow-orphan;
	mso-outline-level:5;
	font-size:13.0pt;
	font-family:"Times New Roman";
	font-style:italic;}
p.MsoFootnoteText, li.MsoFootnoteText, div.MsoFootnoteText
	{mso-style-noshow:yes;
	margin:0in;
	margin-bottom:.0001pt;
	mso-pagination:widow-orphan;
	font-size:10.0pt;
	font-family:"Times New Roman";
	mso-fareast-font-family:"Times New Roman";}
span.MsoFootnoteReference
	{mso-style-noshow:yes;
	vertical-align:super;}
p.MsoBodyText2, li.MsoBodyText2, div.MsoBodyText2
	{margin-top:0in;
	margin-right:0in;
	margin-bottom:6.0pt;
	margin-left:0in;
	line-height:200%;
	mso-pagination:widow-orphan;
	font-size:12.0pt;
	font-family:"Times New Roman";
	mso-fareast-font-family:"Times New Roman";}
a:link, span.MsoHyperlink
	{color:#0000EE;
	text-decoration:underline;
	text-underline:single;}
a:visited, span.MsoHyperlinkFollowed
	{color:purple;
	text-decoration:underline;
	text-underline:single;}
code
	{font-family:"Courier New";
	mso-ascii-font-family:"Courier New";
	mso-fareast-font-family:"Times New Roman";
	mso-hansi-font-family:"Courier New";
	mso-bidi-font-family:"Courier New";}
pre
	{margin:0in;
	margin-bottom:.0001pt;
	mso-pagination:widow-orphan;
	font-size:10.0pt;
	font-family:"Courier New";
	mso-fareast-font-family:"Times New Roman";}
span.SpellE
	{mso-style-name:"";
	mso-spl-e:yes;}
span.GramE
	{mso-style-name:"";
	mso-gram-e:yes;}
@page Section1
	{size:8.5in 11.0in;
	margin:1.0in .75in .5in 1.0in;
	mso-header-margin:.5in;
	mso-footer-margin:.5in;
	mso-paper-source:0;}
div.Section1
	{page:Section1;}
 /* List Definitions */
 @list l0
	{mso-list-id:347761159;
	mso-list-type:hybrid;
	mso-list-template-ids:-1680017606 67698689 67698691 67698693 67698689 67698691 67698693 67698689 67698691 67698693;}
@list l0:level1
	{mso-level-number-format:bullet;
	mso-level-text:\F0B7;
	mso-level-tab-stop:.5in;
	mso-level-number-position:left;
	text-indent:-.25in;
	font-family:Symbol;}
@list l0:level2
	{mso-level-tab-stop:1.0in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l0:level3
	{mso-level-tab-stop:1.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l0:level4
	{mso-level-tab-stop:2.0in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l0:level5
	{mso-level-tab-stop:2.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l0:level6
	{mso-level-tab-stop:3.0in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l0:level7
	{mso-level-tab-stop:3.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l0:level8
	{mso-level-tab-stop:4.0in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l0:level9
	{mso-level-tab-stop:4.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l1
	{mso-list-id:364596818;
	mso-list-template-ids:-488625314;}
@list l1:level1
	{mso-level-number-format:bullet;
	mso-level-text:\F0B7;
	mso-level-tab-stop:.5in;
	mso-level-number-position:left;
	text-indent:-.25in;
	mso-ansi-font-size:10.0pt;
	font-family:Symbol;}
@list l2
	{mso-list-id:604456885;
	mso-list-type:hybrid;
	mso-list-template-ids:1734899956 67698703 67698691 67698693 67698689 67698691 67698693 67698689 67698691 67698693;}
@list l2:level1
	{mso-level-tab-stop:.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l2:level2
	{mso-level-number-format:bullet;
	mso-level-text:o;
	mso-level-tab-stop:1.0in;
	mso-level-number-position:left;
	text-indent:-.25in;
	font-family:"Courier New";}
@list l2:level3
	{mso-level-number-format:bullet;
	mso-level-text:\F0A7;
	mso-level-tab-stop:1.5in;
	mso-level-number-position:left;
	text-indent:-.25in;
	font-family:Wingdings;}
@list l2:level4
	{mso-level-number-format:bullet;
	mso-level-text:\F0B7;
	mso-level-tab-stop:2.0in;
	mso-level-number-position:left;
	text-indent:-.25in;
	font-family:Symbol;}
@list l2:level5
	{mso-level-tab-stop:2.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l2:level6
	{mso-level-tab-stop:3.0in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l2:level7
	{mso-level-tab-stop:3.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l2:level8
	{mso-level-tab-stop:4.0in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l2:level9
	{mso-level-tab-stop:4.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l3
	{mso-list-id:798038152;
	mso-list-type:hybrid;
	mso-list-template-ids:-2087438622 67698703 67698713 67698715 67698703 67698713 67698715 67698703 67698713 67698715;}
@list l3:level1
	{mso-level-tab-stop:39.0pt;
	mso-level-number-position:left;
	margin-left:39.0pt;
	text-indent:-.25in;}
@list l3:level2
	{mso-level-tab-stop:1.0in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l3:level3
	{mso-level-tab-stop:1.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l3:level4
	{mso-level-tab-stop:2.0in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l3:level5
	{mso-level-tab-stop:2.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l3:level6
	{mso-level-tab-stop:3.0in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l3:level7
	{mso-level-tab-stop:3.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l3:level8
	{mso-level-tab-stop:4.0in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l3:level9
	{mso-level-tab-stop:4.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l4
	{mso-list-id:1085106306;
	mso-list-type:hybrid;
	mso-list-template-ids:1015583604 67698703 67698713 67698715 67698703 67698713 67698715 67698703 67698713 67698715;}
@list l4:level1
	{mso-level-tab-stop:.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l4:level2
	{mso-level-tab-stop:1.0in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l4:level3
	{mso-level-tab-stop:1.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l4:level4
	{mso-level-tab-stop:2.0in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l4:level5
	{mso-level-tab-stop:2.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l4:level6
	{mso-level-tab-stop:3.0in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l4:level7
	{mso-level-tab-stop:3.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l4:level8
	{mso-level-tab-stop:4.0in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l4:level9
	{mso-level-tab-stop:4.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l5
	{mso-list-id:1167818358;
	mso-list-template-ids:-1827253532;}
@list l6
	{mso-list-id:1292246357;
	mso-list-template-ids:24384264;}
@list l7
	{mso-list-id:1478297229;
	mso-list-type:hybrid;
	mso-list-template-ids:-438127954 67698689 67698691 67698693 67698689 67698691 67698693 67698689 67698691 67698693;}
@list l7:level1
	{mso-level-number-format:bullet;
	mso-level-text:\F0B7;
	mso-level-tab-stop:.5in;
	mso-level-number-position:left;
	text-indent:-.25in;
	font-family:Symbol;}
@list l7:level2
	{mso-level-tab-stop:1.0in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l7:level3
	{mso-level-tab-stop:1.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l7:level4
	{mso-level-tab-stop:2.0in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l7:level5
	{mso-level-tab-stop:2.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l7:level6
	{mso-level-tab-stop:3.0in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l7:level7
	{mso-level-tab-stop:3.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l7:level8
	{mso-level-tab-stop:4.0in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l7:level9
	{mso-level-tab-stop:4.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l8
	{mso-list-id:1631007561;
	mso-list-template-ids:1365561448;}
@list l8:level1
	{mso-level-number-format:bullet;
	mso-level-text:\F0B7;
	mso-level-tab-stop:.5in;
	mso-level-number-position:left;
	text-indent:-.25in;
	mso-ansi-font-size:10.0pt;
	font-family:Symbol;}
@list l9
	{mso-list-id:1723091313;
	mso-list-type:hybrid;
	mso-list-template-ids:-1797201838 67698703 67698713 67698715 67698703 67698713 67698715 67698703 67698713 67698715;}
@list l9:level1
	{mso-level-tab-stop:.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l9:level2
	{mso-level-tab-stop:1.0in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l9:level3
	{mso-level-tab-stop:1.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l9:level4
	{mso-level-tab-stop:2.0in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l9:level5
	{mso-level-tab-stop:2.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l9:level6
	{mso-level-tab-stop:3.0in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l9:level7
	{mso-level-tab-stop:3.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l9:level8
	{mso-level-tab-stop:4.0in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l9:level9
	{mso-level-tab-stop:4.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l10
	{mso-list-id:1731031428;
	mso-list-type:hybrid;
	mso-list-template-ids:1886447558 67698703 67698713 67698715 67698703 67698713 67698715 67698703 67698713 67698715;}
@list l10:level1
	{mso-level-tab-stop:39.0pt;
	mso-level-number-position:left;
	margin-left:39.0pt;
	text-indent:-.25in;}
@list l10:level2
	{mso-level-tab-stop:1.0in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l10:level3
	{mso-level-tab-stop:1.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l10:level4
	{mso-level-tab-stop:2.0in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l10:level5
	{mso-level-tab-stop:2.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l10:level6
	{mso-level-tab-stop:3.0in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l10:level7
	{mso-level-tab-stop:3.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l10:level8
	{mso-level-tab-stop:4.0in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l10:level9
	{mso-level-tab-stop:4.5in;
	mso-level-number-position:left;
	text-indent:-.25in;}
@list l11
	{mso-list-id:1917208525;
	mso-list-template-ids:2040176132;}
ol
	{margin-bottom:0in;}
ul
	{margin-bottom:0in;}
-->
</style>
<!--[if gte mso 10]>
<style>
 /* Style Definitions */
 table.MsoNormalTable
	{mso-style-name:"Table Normal";
	mso-tstyle-rowband-size:0;
	mso-tstyle-colband-size:0;
	mso-style-noshow:yes;
	mso-style-parent:"";
	mso-padding-alt:0in 5.4pt 0in 5.4pt;
	mso-para-margin:0in;
	mso-para-margin-bottom:.0001pt;
	mso-pagination:widow-orphan;
	font-size:10.0pt;
	font-family:"Times New Roman";}
</style>
<![endif]-->
</head>

<body lang=EN-US link="#0000EE" vlink=purple style='tab-interval:.5in'>

<div class=Section1>

<h1>Generalized Undo Support in Eclipse</h1>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Last
updated:<span style='mso-spacerun:yes'>  </span></span><st1:date Year="2004"
Day="17" Month="12"><span style='font-size:10.0pt;font-family:Arial'>Dec. 17,
 2004</span></st1:date><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'>Status:<span
style='mso-spacerun:yes'>  </span>Proposal <o:p></o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>(<span
class=GramE>see</span> also </span><a
href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=37716">37716</a>)<span
style='font-size:10.0pt;font-family:Arial'><o:p></o:p></span></p>

<h2>Problem Description</h2>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>In R3.0.1 of
the Eclipse SDK, there is no generalized support for undoing user actions.<span
style='mso-spacerun:yes'>  </span>Each plug-in is left to implement its own
strategy for undo, if at all.<span style='mso-spacerun:yes'>  </span>This
approach can cause problems for both Eclipse users and plug-in developers:<o:p></o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><span
style='mso-spacerun:yes'> </span><o:p></o:p></span></p>

<ul style='margin-top:0in' type=disc>
 <li class=MsoNormal style='mso-list:l0 level1 lfo3;tab-stops:list .5in'><span
     style='font-size:10.0pt;font-family:Arial'>Undo and redo actions appear in
     different menus, causing user confusion and UI clutter<o:p></o:p></span></li>
 <li class=MsoNormal style='mso-list:l0 level1 lfo3;tab-stops:list .5in'><span
     style='font-size:10.0pt;font-family:Arial'>Undo and redo implementations
     may have different semantics.<o:p></o:p></span></li>
 <li class=MsoNormal style='mso-list:l0 level1 lfo3;tab-stops:list .5in'><span
     style='font-size:10.0pt;font-family:Arial'>Plug-ins that depend on other
     plug-ins which implement their own undo strategy are forced to choose
     between different implementations and possibly write integration code to
     allow the different frameworks to coexist.<o:p></o:p></span></li>
</ul>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p>&nbsp;</o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Further,
the meaning of undo can be very different depending on what the user is
doing.<span style='mso-spacerun:yes'>  </span>The most common type of undo is
text undo.<span style='mso-spacerun:yes'>  </span>The user can undo lightweight
edit operations such as inserting, replacing, or deleting text.<span
style='mso-spacerun:yes'>  </span>Other types of undo may involve more complex,
heavyweight operations that affect an underlying model of many elements.<span
style='mso-spacerun:yes'>  </span>For example, the JDT refactoring support
provides undo support for refactoring operations that involve many Java
elements at different levels, such as Java packages, compilation units,
classes, and methods.<o:p></o:p></span></p>

<h2>Operations Framework</h2>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>The
proposed framework defines an interface for describing work, called an
“operation” (<span class=SpellE>IOperation</span>), that can be executed,
undone, and redone.<span style='mso-spacerun:yes'>  </span>Operations are
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, undone, or redone as a unit, and
can never be partially 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'><o:p>&nbsp;</o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Operations
can be assigned one or more contexts (<span class=SpellE>IOperationContext</span>)
to which they apply.<span style='mso-spacerun:yes'>  </span>An operation<span
style='mso-spacerun:yes'>  </span>context describes the context in which the
user is working when an operation is performed, undone, or redone.<span
style='mso-spacerun:yes'>  </span>Contexts can be used by workbench parts to
filter the operations history, so that only those operations that have been
assigned the part’s context are available for undo/redo when that part is
active.<o:p></o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p>&nbsp;</o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>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. For example, a text editor’s context is related to the editor
itself and its life-cycle is similar to that of the editor.<span
style='mso-spacerun:yes'>  </span>The navigator’s context is closely related to
the workspace model objects, and the context related to the workspace has a
life cycle to similar to that of the workspace itself.<o:p></o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p>&nbsp;</o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Contexts
can be assigned to operations in multiple ways:<o:p></o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p>&nbsp;</o:p></span></p>

<p class=MsoNormal style='margin-left:39.0pt;text-indent:-.25in;mso-list:l10 level1 lfo5;
tab-stops:list 39.0pt'><![if !supportLists]><span style='font-size:10.0pt;
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>1.<span
style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; </span></span></span><![endif]><span
style='font-size:10.0pt;font-family:Arial'>The context can be assigned
initially when the operation is created.<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>

<p class=MsoNormal style='margin-left:39.0pt;text-indent:-.25in;mso-list:l10 level1 lfo5;
tab-stops:list 39.0pt'><![if !supportLists]><span style='font-size:10.0pt;
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>2.<span
style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; </span></span></span><![endif]><span
style='font-size:10.0pt;font-family:Arial'>A listener interface on the
operations history allows listeners to detect when an operation is added to the
history.<span style='mso-spacerun:yes'>  </span>Listeners can decide if their
context should be added to the operation.<span style='mso-spacerun:yes'> 
</span><o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:21.0pt'><span style='font-size:10.0pt;
font-family:Arial'><o:p>&nbsp;</o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>An
operation may have more than one context.<span style='mso-spacerun:yes'> 
</span>For example, an operation may affect many elements in the workspace,
including one that is currently open in an editor.<span
style='mso-spacerun:yes'>  </span>That operation could be assigned two
independent contexts, so that it can be undone from both the editor and the
view manipulating the model.<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>&nbsp;</o:p></span></p>

<h2>Levels of Integration and Migration</h2>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Many
plug-ins have already invested heavily in building objects that describe
undoable user commands or operations.<span style='mso-spacerun:yes'>  </span>It
is not expected that all plug-ins will adopt the framework completely, given
the individual schedules and other constraints for each plug-in.<span
style='mso-spacerun:yes'>  </span>However, the integration can be achieved in
phases that will immediately provide value to dependent plug-ins.<span
style='mso-spacerun:yes'>  </span>The following adoption strategy is strongly
encouraged:<o:p></o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p>&nbsp;</o:p></span></p>

<ol style='margin-top:0in' start=1 type=1>
 <li class=MsoNormal style='mso-list:l9 level1 lfo8;tab-stops:list .5in'><span
     style='font-size:10.0pt;font-family:Arial'>Existing command/undo frameworks
     can implement the <span class=SpellE>IOperation</span> interface on their
     existing command objects, while still maintaining their individual
     strategies for managing undo stacks or histories.<span
     style='mso-spacerun:yes'>  </span>If there is a substantial investment in
     an existing model-based operation or command framework, wrappers could be
     used to map <span class=SpellE>IOperation</span> protocol to the existing
     protocol.<span style='mso-spacerun:yes'>  </span>The commands/operations
     need not be assigned a context or added to a common operation
     history.<span style='mso-spacerun:yes'>  </span>This level of integration
     allows command hierarchies built in different frameworks to be treated the
     same by plug-ins that depend upon these different frameworks.<span
     style='mso-spacerun:yes'>  </span>Clients of existing command frameworks
     may then use the workbench operation history, assign contexts to
     operations as needed, and even add operations to the history, while still
     using commands built on earlier frameworks.<o:p></o:p></span></li>
 <li class=MsoNormal style='mso-list:l9 level1 lfo8;tab-stops:list .5in'><span
     style='font-size:10.0pt;font-family:Arial'>Existing command/undo
     frameworks may use the listener interfaces provided by the operations
     history to listen for operations that are of interest.<span
     style='mso-spacerun:yes'>  </span>These commands may be wrapped or
     otherwise recorded so that they can be undone from privately maintained
     undo implementations.<span style='mso-spacerun:yes'>  </span>This level of
     integration allows views and editors to appear more tightly integrated
     with the operations framework, since workbench operations of interest can
     be undone or redone from private undo implementations.<o:p></o:p></span></li>
 <li class=MsoNormal style='mso-list:l9 level1 lfo8;tab-stops:list .5in'><span
     style='font-size:10.0pt;font-family:Arial'>Full integration is achieved by
     using the workbench operation history to record the undo and redo history
     as operations occur.<span style='mso-spacerun:yes'>  </span>Once all
     plug-ins share an operation history, clients will be able to use unified
     listeners and handlers to track execution of operations, undo, and redo
     them.<span style='mso-spacerun:yes'>  </span><o:p></o:p></span></li>
</ol>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p>&nbsp;</o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Framework
interfaces will be defined in the <span class=SpellE>org.eclipse.core.operations</span>
package.<span style='mso-spacerun:yes'>  </span>This package will be contained
in a plug-in that has no dependencies on the Eclipse runtime, so that raw <span
class=SpellE>JFace</span> users may make use of it.<span
style='mso-spacerun:yes'>  </span>(The exact plug-in containing the framework
package is not defined at this time, as these packages may be combined with
other packages that provide similar headless infrastructure.)<o:p></o:p></span></p>

<h2>Framework interfaces</h2>

<h3><span class=SpellE>IOperation</span></h3>

<p class=MsoNormal><span class=SpellE><span style='font-size:10.0pt;font-family:
Arial'>IOperation</span></span><span style='font-size:10.0pt;font-family:Arial'>
defines an operation that can be executed, undone, and redone.<span
style='mso-spacerun:yes'>  </span>Operations typically have fully defined
parameters. That is, they are usually created after the user has been queried
for any input needed to define the operation.<o:p></o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p>&nbsp;</o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Operations
determine their ability to execute, undo, or redo according to the current
state of the application. They do not make decisions about their validity based
on where they occur in the operation history. That is left to the particular
operation history.<o:p></o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p>&nbsp;</o:p></span></p>

<pre>public void <span class=SpellE>addContext</span>(<span class=SpellE>IOperationContext</span> context)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Add
the specified context to the operation. If the context is already present, do
not add it again. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>context</span></code><span
style='font-size:10.0pt'> - - the context to be added<o:p></o:p></span></p>

<pre><a name="removeContext(org.eclipse.core.operation"></a>public void <span
class=SpellE>removeContext</span>(<span class=SpellE>IOperationContext</span> context)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Remove
the specified context from the operation. This method has no effect if the
context is not present. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>context</span></code><span
style='font-size:10.0pt'> - - the context to be removed<o:p></o:p></span></p>

<pre><a name="hasContext(org.eclipse.core.operations.I"></a>public <span
class=SpellE>boolean</span> <span class=SpellE><b>hasContext</b></span>(<span
class=SpellE>IOperationContext</span> context)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Returns
whether the operation has the specified context. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>context</span></code><span
style='font-size:10.0pt'> - - the context in question <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>true</span></code><span
style='font-size:10.0pt'> if the context is present, </span><code><span
style='font-size:10.0pt'>false</span></code><span style='font-size:10.0pt'> if
it is not.<o:p></o:p></span></p>

<pre><a name="getContexts()"></a>public <span class=SpellE>IOperationContext</span> [] <span
class=SpellE><b>getContexts</b></span>()</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Returns
the array of contexts that have been assigned to the operation. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the array
of contexts<o:p></o:p></span></p>

<pre><a name="canExecute()"></a>public <span class=SpellE>boolean</span> <span
class=SpellE><b>canExecute</b></span>()</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Returns
whether the operation can be executed in its current state. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>true</span></code><span
style='font-size:10.0pt'> if the operation can be executed; </span><code><span
style='font-size:10.0pt'>false</span></code><span style='font-size:10.0pt'>
otherwise.<o:p></o:p></span></p>

<pre><a name="canRedo()"></a>public <span class=SpellE>boolean</span> <span
class=SpellE><b>canRedo</b></span>()</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Returns
whether the operation can be redone in its current state. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>true</span></code><span
style='font-size:10.0pt'> if the operation can be redone; </span><code><span
style='font-size:10.0pt'>false</span></code><span style='font-size:10.0pt'>
otherwise.<o:p></o:p></span></p>

<pre><a name="canUndo()"></a>public <span class=SpellE>boolean</span> <span
class=SpellE><b>canUndo</b></span>()</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Returns
whether the operation can be undone in its current state. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>true</span></code><span
style='font-size:10.0pt'> if the operation can be undone; </span><code><span
style='font-size:10.0pt'>false</span></code><span style='font-size:10.0pt'>
otherwise.<o:p></o:p></span></p>

<pre><a name="execute(org.eclipse.core.runtime.IProgre"></a>public <span
class=SpellE>org.eclipse.core.runtime.IStatus</span> <b>execute</b>(<span
class=SpellE>org.eclipse.core.runtime.IProgressMonitor</span>&nbsp;monitor)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Execute
the operation. This method should only be called the first time that an
operation is executed. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>monitor</span></code><span
style='font-size:10.0pt'> - <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the <span
class=SpellE>IStatus</span> of the execution. The status severity should be set
to </span><code><span style='font-size:10.0pt'>OK</span></code><span
style='font-size:10.0pt'> if the operation was successful, and </span><code><span
style='font-size:10.0pt'>ERROR</span></code><span style='font-size:10.0pt'> if
it was not. Any other status is assumed to represent an incompletion of the
execution.<o:p></o:p></span></p>

<pre><a name="redo(org.eclipse.core.runtime.IProgressM"></a>public <span
class=SpellE>org.eclipse.core.runtime.IStatus</span> <b>redo</b>(<span
class=SpellE>org.eclipse.core.runtime.IProgressMonitor</span>&nbsp;monitor)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Redo
the operation. This method should only be called after an operation has been
undone. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>monitor</span></code><span
style='font-size:10.0pt'> - <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the <span
class=SpellE>IStatus</span> of the redo. The status severity should be set to </span><code><span
style='font-size:10.0pt'>OK</span></code><span style='font-size:10.0pt'> if the
redo was successful, and </span><code><span style='font-size:10.0pt'>ERROR</span></code><span
style='font-size:10.0pt'> if it was not. Any other status is assumed to
represent an incompletion of the redo.<o:p></o:p></span></p>

<pre>public <span class=SpellE>org.eclipse.core.runtime.IStatus</span> <b>undo</b>(<span
class=SpellE>org.eclipse.core.runtime.IProgressMonitor</span>&nbsp;monitor)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Undo
the operation. This method should only be called after an operation has been
executed. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>monitor</span></code><span
style='font-size:10.0pt'> - <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the <span
class=SpellE>IStatus</span> of the undo. The status severity should be set to </span><code><span
style='font-size:10.0pt'>OK</span></code><span style='font-size:10.0pt'> if the
redo was successful, and </span><code><span style='font-size:10.0pt'>ERROR</span></code><span
style='font-size:10.0pt'> if it was not. Any other status is assumed to
represent an incompletion of the undo.<o:p></o:p></span></p>

<pre>public void <b>dispose</b>()</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Dispose
of the operation. This method is used when the operation is no longer kept in
the history. Implementers of this method typically <span class=SpellE>unregister</span>
any listeners. <o:p></o:p></span></p>

<pre>public <span class=SpellE>java.lang.String</span> <span class=SpellE><b>getLabel</b></span>()</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Return
the label that should be used to show the name of the operation to the user.
This label is typically appended to the &quot;Undo&quot; or &quot;Redo&quot;
menu entry. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the
label<o:p></o:p></span></p>

<pre>public <span class=SpellE>java.lang.String</span> <span class=SpellE><b>getDescription</b></span>()</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Return
the description that should be used to further describe this operation to the
user. The description is used in history lists when the user requests more
information about an operation. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the
description<o:p></o:p></span></p>

<h3><span class=SpellE>IOperationHistory</span></h3>

<p class=MsoNormal><span class=SpellE><span style='font-size:10.0pt;font-family:
Arial'>IOperationHistory</span></span><span style='font-size:10.0pt;font-family:
Arial'> tracks a history of operations that can be undone or redone. Operations
are added to the history once they have been initially executed. Clients may
choose whether to have the operations history perform the initial execution or
simply add the operation to the history. Once operations are added to the
history, the methods <span class=SpellE>canRedo</span>() and <span
class=SpellE>canUndo</span>() are used to determine whether there is an
operation available for undo and redo in a given operation context.<span
style='mso-spacerun:yes'>  </span>The context-based protocol implies that there
is only one operation that can be undone or redone at a given time in a given
context. This is typical of a linear undo model, when only the most recently
executed operation is available for undo. When this protocol is used, a linear
model is enforced by the history. It is up to clients to determine how to
maintain a history that is invalid or stale. For example, when the most recent
operation for a context cannot be performed, clients may wish to flush the
history for that context.<o:p></o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p>&nbsp;</o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Additional
protocol allows direct undo and redo of a specified operation, regardless of
its position in the history. When a more flexible undo model is supported,
these methods can be implemented to undo and redo directly specified
operations. If an implementer of <span class=SpellE>IOperationHistory</span>
does not allow direct undo and redo, these methods can return a status
indicating that it is not allowed.<o:p></o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p>&nbsp;</o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Listeners (<span
class=SpellE>IOperationHistoryListener</span>) can listen for notifications
about changes in the history (operations added or removed), and for
notification before and after any operation is executed, undone or redone.
Notification of operation execution only occurs when clients direct the history
to execute the operation. If the operation is added after it is executed, there
can be no notification of its execution.<o:p></o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p>&nbsp;</o:p></span></p>

<p class=MsoNormal><span class=SpellE><span style='font-size:10.0pt;font-family:
Arial'>IOperationApprover</span></span><span style='font-size:10.0pt;
font-family:Arial'> defines an interface for approving an undo or redo before
it occurs. This is useful for injecting policy-decisions into the model -
whether direct undo and redo are supported, or warning the user about certain
kinds of operations. It can also be used when objects have state related to the
operation and need to determine whether an undo or redo will cause any
conflicts with their local state.<o:p></o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p>&nbsp;</o:p></span></p>

<pre>public void <b>add</b>(<span class=SpellE>IOperation</span> operation)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Add
the specified operation to the history without executing it. The operation should
have already been executed by the time it is added to the history. Listeners
will be notified that the operation was added to the history. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>operation</span></code><span
style='font-size:10.0pt'> - - the operation to be added to the history<o:p></o:p></span></p>

<pre>public <span class=SpellE>org.eclipse.core.runtime.IStatus</span> <b>execute</b>(<span
class=SpellE>IOperation</span> operation,</pre><pre><span style='mso-spacerun:yes'>                                                </span><span
class=SpellE>org.eclipse.core.runtime.IProgressMonitor</span>&nbsp;monitor)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Execute
the specified operation and add it to the operations history if successful.
This method is used by clients who wish operation history listeners to receive
notifications before and after the execution of the operation. Listeners will
be notified before ( </span><span class=SpellE><code><span style='font-size:
10.0pt'>aboutToExecute</span></code></span><span style='font-size:10.0pt'>) and
after (</span><code><span style='font-size:10.0pt'>done</span></code><span
style='font-size:10.0pt'> or </span><span class=SpellE><code><span
style='font-size:10.0pt'>operationNotOK</span></code></span><span
style='font-size:10.0pt'>). If the operation successfully executes, an
additional notification that the operation has been added to the history (</span><span
class=SpellE><code><span style='font-size:10.0pt'>operationAdded</span></code></span><span
style='font-size:10.0pt'>) will be sent. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>operation</span></code><span
style='font-size:10.0pt'> - - the operation to be executed and then added to
the history <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the <span
class=SpellE>IStatus</span> indicating whether the execution succeeded. The
severity code in the returned status describes whether the operation succeeded
and whether it was added to the history. </span><code><span style='font-size:
10.0pt'>OK</span></code><span style='font-size:10.0pt'> severity indicates that
the execute operation was successful and that the operation has been added to
the history. Listeners will receive the </span><code><span style='font-size:
10.0pt'>done</span></code><span style='font-size:10.0pt'> notification. </span><code><span
style='font-size:10.0pt'>CANCEL</span></code><span style='font-size:10.0pt'>
severity indicates that the user cancelled the operation and that the operation
was not added to the history. </span><code><span style='font-size:10.0pt'>ERROR</span></code><span
style='font-size:10.0pt'> severity indicates that the operation did not
successfully execute and that it was not added to the history. Any other severity
code is not specifically interpreted by the history, and the operation will not
be added to the history. For all severities other than </span><code><span
style='font-size:10.0pt'>OK</span></code><span style='font-size:10.0pt'>,
listeners will receive the </span><span class=SpellE><code><span
style='font-size:10.0pt'>operationNotOK</span></code></span><span
style='font-size:10.0pt'> notification instead of the </span><code><span
style='font-size:10.0pt'>done</span></code><span style='font-size:10.0pt'>
notification.<o:p></o:p></span></p>

<pre>public void <b>remove</b>(<span class=SpellE>IOperation</span> operation)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Remove
the specified operation from the history. Listeners will be notified of the
removal of the operation. This method is used by clients who want to flush a
particular subset of the history. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>operation</span></code><span
style='font-size:10.0pt'> - - the operation to be removed from the history<o:p></o:p></span></p>

<pre>public <span class=SpellE>org.eclipse.core.runtime.IStatus</span> <b>redo</b>(<span
class=SpellE>IOperationContext</span>&nbsp;context,</pre><pre><span style='mso-spacerun:yes'>                                             </span><span
class=SpellE>org.eclipse.core.runtime.IProgressMonitor</span>&nbsp;monitor)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Redo
the most recently undone operation in the given context <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>context</span></code><span
style='font-size:10.0pt'> - - the context to be redone, or null if the context
does not matter <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>monitor</span></code><span
style='font-size:10.0pt'> - - the progress monitor to be used for the redo, or
null if no progress monitor is provided. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the <span
class=SpellE>IStatus</span> indicating whether the redo succeeded. The severity
code in the returned status describes whether the operation succeeded and
whether it remains in the history. </span><code><span style='font-size:10.0pt'>OK</span></code><span
style='font-size:10.0pt'> severity indicates that the redo operation was
successful and that the operation has been placed on the undo history. Listeners
will receive the </span><code><span style='font-size:10.0pt'>redone</span></code><span
style='font-size:10.0pt'> notification. </span><code><span style='font-size:
10.0pt'>CANCEL</span></code><span style='font-size:10.0pt'> severity indicates
that the user cancelled the operation and that the operation remains in the
redo history. </span><code><span style='font-size:10.0pt'>ERROR</span></code><span
style='font-size:10.0pt'> severity indicates that the operation could not
successfully be redone and that it has been removed from the history. Listeners
will also be notified that the operation was removed. Any other severity code
is not specifically interpreted by the history, and is simply passed back to
the caller. For all severities other than </span><code><span style='font-size:
10.0pt'>OK</span></code><span style='font-size:10.0pt'>, listeners will receive
the </span><span class=SpellE><code><span style='font-size:10.0pt'>operationNotOK</span></code></span><span
style='font-size:10.0pt'> notification instead of the </span><code><span
style='font-size:10.0pt'>redone</span></code><span style='font-size:10.0pt'>
notification.<o:p></o:p></span></p>

<pre>public <span class=SpellE>org.eclipse.core.runtime.IStatus</span> <span
class=SpellE><b>redoOperation</b></span>(<span class=SpellE>IOperation</span> operation,</pre><pre><span style='mso-spacerun:yes'>                                                      </span><span
class=SpellE>org.eclipse.core.runtime.IProgressMonitor</span>&nbsp;monitor)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Redo
the specified operation <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>operation</span></code><span
style='font-size:10.0pt'> - - the operation to be redone <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>monitor</span></code><span
style='font-size:10.0pt'> - - the progress monitor to be used for the redo, or
null if no progress monitor is provided <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the <span
class=SpellE>IStatus</span> indicating whether the redo succeeded. The severity
code in the returned status describes whether the operation succeeded and
whether it remains in the history. </span><code><span style='font-size:10.0pt'>OK</span></code><span
style='font-size:10.0pt'> severity indicates that the redo operation was
successful and that the operation has been placed on the undo history.
Listeners will receive the </span><code><span style='font-size:10.0pt'>redone</span></code><span
style='font-size:10.0pt'> notification. </span><code><span style='font-size:
10.0pt'>CANCEL</span></code><span style='font-size:10.0pt'> severity indicates
that the user cancelled the operation and that the operation remains in the
redo history. </span><code><span style='font-size:10.0pt'>ERROR</span></code><span
style='font-size:10.0pt'> severity indicates that the operation could not
successfully be redone. The operation will remain at its current location in
the history, and callers must explicitly remove it if desired. Any other
severity code is not interpreted by the history, and is simply passed back to
the caller. For all severities other than </span><code><span style='font-size:
10.0pt'>OK</span></code><span style='font-size:10.0pt'>, listeners will receive
the </span><span class=SpellE><code><span style='font-size:10.0pt'>operationNotOK</span></code></span><span
style='font-size:10.0pt'> notification instead of the </span><code><span
style='font-size:10.0pt'>redone</span></code><span style='font-size:10.0pt'>
notification.<o:p></o:p></span></p>

<pre>public <span class=SpellE>org.eclipse.core.runtime.IStatus</span> <b>undo</b>(<span
class=SpellE>IOperationContext</span>&nbsp; context,</pre><pre><span style='mso-spacerun:yes'>                                             </span><span
class=SpellE>org.eclipse.core.runtime.IProgressMonitor</span>&nbsp;monitor)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Undo
the most recently undone operation in the given context <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>context</span></code><span
style='font-size:10.0pt'> - - the context to be undone, or null if the context
does not matter <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>monitor</span></code><span
style='font-size:10.0pt'> - - the progress monitor to be used for the undo, or
null if no progress monitor is provided. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the <span
class=SpellE>IStatus</span> indicating whether the undo succeeded. The severity
code in the returned status describes whether the operation succeeded and
whether it remains in the history. </span><code><span style='font-size:10.0pt'>OK</span></code><span
style='font-size:10.0pt'> severity indicates that the undo operation was
successful and that the operation has been placed on the redo history.
Listeners will receive the </span><code><span style='font-size:10.0pt'>undone</span></code><span
style='font-size:10.0pt'> notification. </span><code><span style='font-size:
10.0pt'>CANCEL</span></code><span style='font-size:10.0pt'> severity indicates
that the user cancelled the operation and that the operation remains in the
undo history. </span><code><span style='font-size:10.0pt'>ERROR</span></code><span
style='font-size:10.0pt'> severity indicates that the operation could not
successfully be undone and that it has been removed from the history. Listeners
will be notified that the operation was removed. Any other severity code is not
interpreted by the history, and is simply passed back to the caller. For all
severities other than </span><code><span style='font-size:10.0pt'>OK</span></code><span
style='font-size:10.0pt'>, listeners will receive the </span><span
class=SpellE><code><span style='font-size:10.0pt'>operationNotOK</span></code></span><span
style='font-size:10.0pt'> notification instead of the </span><code><span
style='font-size:10.0pt'>undone</span></code><span style='font-size:10.0pt'>
notification.<o:p></o:p></span></p>

<pre>public <span class=SpellE>org.eclipse.core.runtime.IStatus</span> <span
class=SpellE><b>undoOperation</b></span>(<span class=SpellE>IOperation</span> operation,</pre><pre><span style='mso-spacerun:yes'>                                                      </span><span
class=SpellE>org.eclipse.core.runtime.IProgressMonitor</span>&nbsp;monitor)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Undo
the specified operation <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>operation</span></code><span
style='font-size:10.0pt'> - - the operation to be undone <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>monitor</span></code><span
style='font-size:10.0pt'> - - the progress monitor to be used for the undo, or
null if no progress monitor is provided <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the <span
class=SpellE>IStatus</span> indicating whether the undo succeeded. The severity
code in the returned status describes whether the operation succeeded and
whether it remains in the history. </span><code><span style='font-size:10.0pt'>OK</span></code><span
style='font-size:10.0pt'> severity indicates that the undo operation was
successful and that the operation has been placed on the redo history.
Listeners will receive the </span><code><span style='font-size:10.0pt'>undone</span></code><span
style='font-size:10.0pt'> notification. </span><code><span style='font-size:
10.0pt'>CANCEL</span></code><span style='font-size:10.0pt'> severity indicates
that the user cancelled the operation and that the operation remains in the
undo history. </span><code><span style='font-size:10.0pt'>ERROR</span></code><span
style='font-size:10.0pt'> severity indicates that the operation could not successfully
be undone. The operation will remain at its current location in the history,
and callers must explicitly remove it if desired. Any other severity code is
not interpreted by the history, and is simply passed back to the caller. For
all severities other than </span><code><span style='font-size:10.0pt'>OK</span></code><span
style='font-size:10.0pt'>, listeners will receive the </span><span
class=SpellE><code><span style='font-size:10.0pt'>operationNotOK</span></code></span><span
style='font-size:10.0pt'> notification instead of the </span><code><span
style='font-size:10.0pt'>undone</span></code><span style='font-size:10.0pt'>
notification.<o:p></o:p></span></p>

<pre>public <span class=SpellE>boolean</span> <span class=SpellE><b>canRedo</b></span>(<span
class=SpellE>IOperationContext</span>&nbsp; context)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Return
whether there is a <span class=SpellE>redoable</span> operation available in
the given context. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>context</span></code><span
style='font-size:10.0pt'> - - the context to be checked, or null for any
context <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>true</span></code><span
style='font-size:10.0pt'> if there is a <span class=SpellE>redoable</span>
operation, </span><code><span style='font-size:10.0pt'>false</span></code><span
style='font-size:10.0pt'> otherwise.<o:p></o:p></span></p>

<pre>public <span class=SpellE>boolean</span> <span class=SpellE><b>canUndo</b></span>(<span
class=SpellE>IOperationContext</span>&nbsp; context)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Return
whether there is an undoable operation available in the given context <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>context</span></code><span
style='font-size:10.0pt'> - - the context to be checked, or null to represent
any context <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>true</span></code><span
style='font-size:10.0pt'> if there is an undoable operation, </span><code><span
style='font-size:10.0pt'>false</span></code><span style='font-size:10.0pt'>
otherwise.<o:p></o:p></span></p>

<pre>public void <span class=SpellE><b>addOperationApprover</b></span>(<span
class=SpellE>IOperationApprover</span>&nbsp;approver)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Add the
specified approver to the operation history. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>approver</span></code><span
style='font-size:10.0pt'> - - the <span class=SpellE>IOperationApprover</span>
that will be consulted before any operation in the history is undone or redone<o:p></o:p></span></p>

<pre>public void <span class=SpellE><b>addOperationHistoryListener</b></span>(<span
class=SpellE>IOperationHistoryListener</span> listener)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Add
the specified listener to the operation history. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>listener</span></code><span
style='font-size:10.0pt'> - - the <span class=SpellE>IOperationHistoryListener</span>
to receive notifications about changes in the history or operations that are
executed, undone, or redone<o:p></o:p></span></p>

<pre>public void <span class=SpellE><b>removeOperationApprover</b></span>(<span
class=SpellE>IOperationApprover</span>&nbsp; approver)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Remove
the specified operation approver from the operation history. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>approver</span></code><span
style='font-size:10.0pt'> - - the <span class=SpellE>IOperationApprover</span>
to be removed<o:p></o:p></span></p>

<pre>public void <span class=SpellE><b>removeOperationHistoryListener</b></span>(<span
class=SpellE>IOperationHistoryListener</span> listener)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Remove
the specified listener from the operation history. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>listener</span></code><span
style='font-size:10.0pt'> - - The <span class=SpellE>IOperationHistoryListener</span>
to be removed<o:p></o:p></span></p>

<pre>public <span class=SpellE>IOperation</span> <span class=SpellE><b>getRedoOperation</b></span>(<span
class=SpellE>IOperationContext</span>&nbsp; context)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Get
the operation that will next be redone in the given context. This method is
used to retrieve the label or description as needed for the &quot;Redo&quot;
menu. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>context</span></code><span
style='font-size:10.0pt'> - - the context for the redo, or null if the context
does not matter <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the
operation to be redone or </span><code><span style='font-size:10.0pt'>null</span></code><span
style='font-size:10.0pt'> if there is no valid operation available.<o:p></o:p></span></p>

<pre>public <span class=SpellE>IOperation</span> [] <span class=SpellE><b>getRedoHistory</b></span>(<span
class=SpellE>IOperationContext</span>&nbsp; context)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Get
the array of operations in the redo history for a given context. The operations
are in the order that they would be redone if successive &quot;Redo&quot;
commands were invoked. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>context</span></code><span
style='font-size:10.0pt'> - - the context for the redo, or null if the entire
history is requested <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the
array of operations in the history<o:p></o:p></span></p>

<pre>public <span class=SpellE>IOperation</span> <span class=SpellE><b>getUndoOperation</b></span>(<span
class=SpellE>IOperationContext</span>&nbsp; context)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Get
the operation that will next be undone in the given context. This method is
used to retrieve the label or description as needed for the &quot;Undo&quot;
menu. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>context</span></code><span
style='font-size:10.0pt'> - - the context for the undo, or null if the context
does not matter <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the
operation to be undone or </span><code><span style='font-size:10.0pt'>null</span></code><span
style='font-size:10.0pt'> if there is no operation available.<o:p></o:p></span></p>

<pre>public <span class=SpellE>IOperation</span> [] <span class=SpellE><b>getUndoHistory</b></span>(<span
class=SpellE>IOperationContext</span>&nbsp; context)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Get
the array of operations that can be undone in the specified context. The
operations are in the order that they would be undone if successive
&quot;Undo&quot; commands were invoked. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>context</span></code><span
style='font-size:10.0pt'> - - the context for the undo, or null if the entire
history is requested <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the
array of operations in the history<o:p></o:p></span></p>

<pre>public void <b>dispose</b>(<span class=SpellE>IOperationContext</span>&nbsp;context,</pre><pre><span style='mso-spacerun:yes'>                   </span><span style='mso-spacerun:yes'> </span><span
class=SpellE>boolean</span>&nbsp;<span class=SpellE>flushUndo</span>,</pre><pre><span style='mso-spacerun:yes'>                    </span><span
class=SpellE>boolean</span>&nbsp;<span class=SpellE>flushRedo</span>)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Dispose
of the specified context in the history. All operations that have only the
given context will be disposed. References to the context in operations that
have more than one context will also be removed. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>context</span></code><span
style='font-size:10.0pt'> - - the context to be disposed, or null if all
contexts are to be disposed <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><span class=SpellE><code><span
style='font-size:10.0pt'>flushUndo</span></code></span><span style='font-size:
10.0pt'> - - </span><code><span style='font-size:10.0pt'>true</span></code><span
style='font-size:10.0pt'> if the context should be flushed from the undo
history, </span><code><span style='font-size:10.0pt'>false</span></code><span
style='font-size:10.0pt'> if it should not <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><span class=SpellE><code><span
style='font-size:10.0pt'>flushRedo</span></code></span><span style='font-size:
10.0pt'> - - </span><code><span style='font-size:10.0pt'>true</span></code><span
style='font-size:10.0pt'> if the context should be flushed from the redo
history, </span><code><span style='font-size:10.0pt'>false</span></code><span
style='font-size:10.0pt'> if it should not.<o:p></o:p></span></p>

<pre>public <span class=SpellE>int</span> <span class=SpellE><b>getLimit</b></span>()</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Return
the specified limit on the undo and redo history. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>limit<o:p></o:p></span></p>

<pre>public void <span class=SpellE><b>setLimit</b></span>(<span class=SpellE>int</span>&nbsp;limit)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Set
the limit on the undo and redo history. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>limit</span></code><span
style='font-size:10.0pt'> - - the maximum number of operations that should be
kept in the history<o:p></o:p></span></p>

<h3><span class=SpellE>IOperationContext</span></h3>

<pre>public <span class=SpellE>java.lang.String</span> <span class=SpellE><b>getLabel</b></span>()</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Get
the label that should be used to describe the context in any views. Contexts
may be shown when filtered operation histories are shown to the user. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the
label for the context.<o:p></o:p></span></p>

<pre>public <span class=SpellE>IContextOperationApprover</span> <span
class=SpellE><b>getOperationApprover</b></span>()</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Get
the operation approver that is used to approve undo or redo operations
involving this context. A null context signifies that no special approval is
necessary. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the
operation approver for the context.<o:p></o:p></span></p>

<pre>public <span class=SpellE>boolean</span> <span class=SpellE><b>acceptOperation</b></span>(<span
class=SpellE>IOperation</span> operation)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Return
a <span class=SpellE>boolean</span> that indicates whether this context should
be assigned to the specified operation. This method should be overridden by
contexts that have complex rules for whether they should be assigned to an
operation. Simple contexts generally answer true. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>a <span
class=SpellE>boolean</span> indicating whether this context should be assigned
to the operation.<o:p></o:p></span></p>

<pre>public <span class=SpellE>boolean</span> <b>equals</b>(<span class=SpellE>IOperationContext</span>&nbsp;context)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Return
whether this context is equal to the specified context. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>context</span></code><span
style='font-size:10.0pt'> - <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>true</span></code><span
style='font-size:10.0pt'> if the contexts are equal, </span><code><span
style='font-size:10.0pt'>false</span></code><span style='font-size:10.0pt'>
otherwise.<o:p></o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p>&nbsp;</o:p></span></p>

<h3><span class=SpellE>IOperationApprover</span></h3>

<p class=MsoNormal><span class=SpellE><span style='font-size:10.0pt;font-family:
Arial'>IOperationApprover</span></span><span style='font-size:10.0pt;
font-family:Arial'> defines an interface for approving the undo or redo of a
particular operation within an operation history. Operations that are
candidates for undo or redo have already been validated against their current
state and according to the rules of the history.<o:p></o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p>&nbsp;</o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>By the time
an <span class=SpellE>IOperationApprover</span> is consulted, the undo has
already been requested. Approvers should true if the operation should proceed,
and false if it should not. When an operation is rejected, it is expected that
the object rejecting the operation has already consulted the user if necessary
or otherwise provided any necessary information to the user about the
rejection.<o:p></o:p></span></p>

<pre>public <span class=SpellE>org.eclipse.core.runtime.IStatus</span> <span
class=SpellE><b>proceedUndoing</b></span>(<span class=SpellE>IOperation</span> operation, <span
class=SpellE>IOperationHistory</span> history)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Return
a status indicating whether the specified operation should be undone. Any
status that does not have severity </span><span class=SpellE><code><span
style='font-size:10.0pt'>IStatus.OK</span></code></span><span style='font-size:
10.0pt'> will not be approved. Implementers should not assume that the undo
will be performed when the status is </span><code><span style='font-size:10.0pt'>OK</span></code><span
style='font-size:10.0pt'>, since other operation approvers can veto the undo. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>operation</span></code><span
style='font-size:10.0pt'> - - the operation to be undone <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>history</span></code><span
style='font-size:10.0pt'> - - the history undoing the operation <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the <span
class=SpellE>IStatus</span> describing whether the operation is approved. The
undo will not proceed if the status severity is not </span><code><span
style='font-size:10.0pt'>OK</span></code><span style='font-size:10.0pt'>, and
the caller requesting the undo will be returned the status that caused the
rejection. Any other status severities will not be interpreted by the history.<o:p></o:p></span></p>

<pre>public <span class=SpellE>org.eclipse.core.runtime.IStatus</span> <span
class=SpellE><b>proceedRedoing</b></span>(<span class=SpellE>IOperation</span> operation, <span
class=SpellE>IOperationHistory</span>&nbsp;history)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Return
a status indicating whether the specified operation should be redone. Any
status that does not have severity </span><span class=SpellE><code><span
style='font-size:10.0pt'>IStatus.OK</span></code></span><span style='font-size:
10.0pt'> will not be approved. Implementers should not assume that the redo
will be performed when the status is </span><code><span style='font-size:10.0pt'>OK</span></code><span
style='font-size:10.0pt'>, since other operation approvers may veto the redo. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>operation</span></code><span
style='font-size:10.0pt'> - - the operation to be redone <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>history</span></code><span
style='font-size:10.0pt'> - - the history redoing the operation <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>the <span
class=SpellE>IStatus</span> describing whether the operation is approved. The
redo will not proceed if the status severity is no </span><code><span
style='font-size:10.0pt'>OK</span></code><span style='font-size:10.0pt'>, and
the caller requesting the redo will be returned the status that caused the
rejection. Any other status severities will not be interpreted by the history.<o:p></o:p></span></p>

<h3><span class=SpellE>IOperationHistoryListener</span></h3>

<pre>public void <span class=SpellE><b>historyNotification</b></span>(<span
class=SpellE>OperationHistoryEvent</span> event)</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Something
of note has happened in the <span class=SpellE>IOperationHistory</span>.
Listeners should check the supplied event for details. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Parameters:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>event</span></code><span
style='font-size:10.0pt'> - - the <span class=SpellE>OperationHistoryEvent</span>
that describes the particular notification.<o:p></o:p></span></p>

<h3><span class=SpellE>OperationHistoryEvent</span></h3>

<pre>public <span class=SpellE>IOperationHistory</span> <b>history</b></pre><pre><o:p>&nbsp;</o:p></pre><pre>public <span
class=SpellE>IOperation</span> <b>operation</b></pre><pre><o:p>&nbsp;</o:p></pre><pre>public <span
class=SpellE>boolean</span> <span class=SpellE><b>operationAdded</b></span>()</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Returns
whether or not an operation was added to the history. Listeners typically use
this to add their context to a new operation as appropriate or otherwise record
the operation. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>true</span></code><span
style='font-size:10.0pt'> if an operation has been added, </span><code><span
style='font-size:10.0pt'>false</span></code><span style='font-size:10.0pt'> if
not.<o:p></o:p></span></p>

<pre>public <span class=SpellE>boolean</span> <span class=SpellE><b>operationRemoved</b></span>()</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Returns
whether or not an operation was removed from the history. Listeners typically
remove any record of the operation that they may have kept in their own state. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>true</span></code><span
style='font-size:10.0pt'> if an operation has been removed, </span><code><span
style='font-size:10.0pt'>false</span></code><span style='font-size:10.0pt'> if
not.<o:p></o:p></span></p>

<pre>public <span class=SpellE>boolean</span> <span class=SpellE><b>aboutToExecute</b></span>()</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Returns
whether or not an operation is about to execute. Listeners should prepare for the
execution as appropriate. Listeners will receive a done notification if the
operation is successful, or an <span class=SpellE>operationNotCompleted</span>
notification if the execution is cancelled or otherwise fails. This
notification is only received for those operations executed by the operation
history. Operations that are added to the history after execution do not
trigger these notifications. If the operation successfully executes, clients
will also receive a notification that it has been added to the history. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>true</span></code><span
style='font-size:10.0pt'> if an operation is about to execute, </span><code><span
style='font-size:10.0pt'>false</span></code><span style='font-size:10.0pt'> if
not.<o:p></o:p></span></p>

<pre>public <span class=SpellE>boolean</span> <span class=SpellE><b>aboutToUndo</b></span>()</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Returns
whether or not an operation is about to be undone. Listeners should prepare for
the undo as appropriate. Listeners will receive an undone notification if the operation
is successful, or an <span class=SpellE>operationNotCompleted</span>
notification if the undo is cancelled or otherwise fails. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>true</span></code><span
style='font-size:10.0pt'> if an operation is about to undo, </span><code><span
style='font-size:10.0pt'>false</span></code><span style='font-size:10.0pt'> if
not.<o:p></o:p></span></p>

<pre>public <span class=SpellE>boolean</span> <span class=SpellE><b>aboutToRedo</b></span>()</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Returns
whether or not an operation is about to be redone. Listeners should prepare for
the redo as appropriate. Listeners will receive a redone notification if the
operation is successful, or an <span class=SpellE>operationNotCompleted</span>
notification if the redo is cancelled or otherwise fails. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>true</span></code><span
style='font-size:10.0pt'> if an operation is about to redo, </span><code><span
style='font-size:10.0pt'>false</span></code><span style='font-size:10.0pt'> if
not.<o:p></o:p></span></p>

<pre>public <span class=SpellE>boolean</span> <b>done</b>()</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Returns
whether or not an operation was initially done. Listeners can take appropriate
action, such as revealing any relevant state in the UI. This notification is
only received for those operations executed by the operation history.
Operations that are added to the history after execution do not trigger this
notification. Clients will also receive a notification that the operation has
been added to the history. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>true</span></code><span
style='font-size:10.0pt'> if an operation has been done, </span><code><span
style='font-size:10.0pt'>false</span></code><span style='font-size:10.0pt'> if
not.<o:p></o:p></span></p>

<pre>public <span class=SpellE>boolean</span> <b>undone</b>()</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Returns
whether or not an operation was undone. Listeners can take appropriate action,
such as revealing any relevant state in the UI. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>true</span></code><span
style='font-size:10.0pt'> if an operation has been undone, </span><code><span
style='font-size:10.0pt'>false</span></code><span style='font-size:10.0pt'> if
not.<o:p></o:p></span></p>

<pre>public <span class=SpellE>boolean</span> <b>redone</b>()</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Returns
whether or not an operation was redone. Listeners can take appropriate action,
such as revealing any relevant state in the UI. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>true</span></code><span
style='font-size:10.0pt'> if an operation has been redone, </span><code><span
style='font-size:10.0pt'>false</span></code><span style='font-size:10.0pt'> if
not.<o:p></o:p></span></p>

<pre>public <span class=SpellE>boolean</span> <span class=SpellE><b>operationNotOK</b></span>()</pre>

<p class=MsoNormal style='margin-left:.5in'><span style='font-size:10.0pt'>Returns
whether or not an operation was attempted and not successful. Listeners
typically use this when they have prepared for an execute, undo, or redo, and
need to know that the operation did not successfully complete. For example,
listeners that turn redraw off before an operation is undone would turn redraw
on when the operation completes, or when this notification is received, since
there will be no notification of the completion. <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><b><span style='font-size:10.0pt'>Returns:</span></b><span
style='font-size:10.0pt'> <o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:.5in'><code><span style='font-size:10.0pt'>true</span></code><span
style='font-size:10.0pt'> if an operation has been redone, </span><code><span
style='font-size:10.0pt'>false</span></code><span style='font-size:10.0pt'> if
not.<o:p></o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p>&nbsp;</o:p></span></p>

<h2>UI Support Classes<span style='font-size:10.0pt'><o:p></o:p></span></h2>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Additional
support classes will be provided in the package <span class=SpellE>org.eclipse.ui.operations</span>.<span
style='mso-spacerun:yes'>  </span>These classes handle policy decisions about
the undo model to be used by the workbench.<span style='mso-spacerun:yes'> 
</span>Access to the undo and redo commands, as well as the operations history,
will be provided through workbench.<o:p></o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p>&nbsp;</o:p></span></p>

<h3>Workbench Operation History</h3>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>The
workbench will manage a common operation history that can be used by any
plug-in to integrate its undo and redo history with the workbench.<span
style='mso-spacerun:yes'>  </span>This operation history will be accessible
through workbench API, to be determined by M5.<o:p></o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p>&nbsp;</o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Contexts
will be defined for text editors (with specialization for source editors) and
for the workspace.<span style='mso-spacerun:yes'>  </span>Throughout the
development of R3.1, plug-ins will be encouraged to define operations that
represent their existing actions or command handlers.<span
style='mso-spacerun:yes'>  </span>Additional contexts may be defined by
plug-ins.<o:p></o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p>&nbsp;</o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Existing
workbench actions will be modified to support undo by mapping existing
workbench actions and handlers to operations.<span style='mso-spacerun:yes'> 
</span>The operations will be added incrementally once the framework is in
place.<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>&nbsp;</o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Operations
that are assigned the workspace context will implement a <span class=SpellE>subinterface</span>,
<span class=SpellE>IWorkspaceOperation</span>.<span style='mso-spacerun:yes'> 
</span><span class=SpellE>IWorkspaceOperation</span> adds protocol to access
the model elements manipulated by an operation (<span class=SpellE>getElements</span>()),
so that listeners can decide if the workspace operation affects their
model.<span style='mso-spacerun:yes'>  </span>This protocol is not generalized
to <span class=SpellE>IOperation</span>.<span style='mso-spacerun:yes'> 
</span>Prior experience with model-based operation frameworks has shown that
there needs to be a very specific contract regarding how and when validation is
performed, what underlying model listeners are used to validate the operation,
and whether operations history notifications or internal model notifications
are used to maintain the validity of the operation and the undo stack.<span
style='mso-spacerun:yes'>  </span>These details for <span class=SpellE>IWorkspaceOperation</span>
will evolve as more workbench operations are created. <o:p></o:p></span></p>

<h3><span class=SpellE>UndoHandler</span> and <span class=SpellE>RedoHandler</span></h3>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>The
Edit&gt;Undo and Edit&gt;Redo commands should be handled by any parts that wish
to support undo.<span style='mso-spacerun:yes'>  </span>Common handlers for the
undo and redo commands will be provided.<span style='mso-spacerun:yes'> 
</span>These handlers can be assigned a context that should be used to filter
the undo and redo history.<span style='mso-spacerun:yes'>  </span>The handlers
are responsible for the following:<o:p></o:p></span></p>

<ul style='margin-top:0in' type=disc>
 <li class=MsoNormal style='mso-list:l7 level1 lfo11;tab-stops:list .5in'><span
     style='font-size:10.0pt;font-family:Arial'>Undo and Redo commands will be
     enabled based on the status of the history.<o:p></o:p></span></li>
 <li class=MsoNormal style='mso-list:l7 level1 lfo11;tab-stops:list .5in'><span
     style='font-size:10.0pt;font-family:Arial'>The Undo and Redo commands will
     be appended with the label of the operation for the handler’s context.<o:p></o:p></span></li>
 <li class=MsoNormal style='mso-list:l7 level1 lfo11;tab-stops:list .5in'><span
     style='font-size:10.0pt;font-family:Arial'>The undo and redo history will
     be flushed for the handler’s context whenever the most recent operation in
     the history is invalid.<span style='mso-spacerun:yes'>  </span>This
     aggressive maintenance of the history is the most conservative approach
     for ensuring that the history contains valid operations, and this strategy
     may evolve with experience.<o:p></o:p></span></li>
</ul>

<h3>Undo and Redo Toolbar Items</h3>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Time
permitting, classes that support toolbar dropdown items for undo and redo will
be developed.<span style='mso-spacerun:yes'>  </span>These will also be
assigned a context.<span style='mso-spacerun:yes'>  </span>By clicking on the
drop-down arrow, the user will see the history for that particular
context.<span style='mso-spacerun:yes'>  </span>The user will only be able to
select a range, starting from the top item, to be undone or redone.<span
style='mso-spacerun:yes'>  </span>It is expected that the ability to view the
history is more valuable to the user than the ability to multi-select
operations for undo.<o:p></o:p></span></p>

<h3>Operation Approvers</h3>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>The
workbench will provide and install an <span class=SpellE>IOperationApprover</span>
that consults the contexts of an operation to determine whether undo or redo
should proceed.<span style='mso-spacerun:yes'>  </span>The policy is described
as follows:<o:p></o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p>&nbsp;</o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>The
workbench will allow undo or 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>If the operation to be
undone or redone has contexts that are also present in operations appearing
later in the history, then the undo or redo of the operation will not be
permitted.<o:p></o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p>&nbsp;</o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>A concrete
example will help explain this.<span style='mso-spacerun:yes'>  </span><o:p></o:p></span></p>

<ol style='margin-top:0in' start=1 type=1>
 <li class=MsoNormal style='mso-list:l2 level1 lfo14;tab-stops:list .5in'><span
     style='font-size:10.0pt;font-family:Arial'>The user makes local edits in
     editor A.<o:p></o:p></span></li>
 <li class=MsoNormal style='mso-list:l2 level1 lfo14;tab-stops:list .5in'><span
     style='font-size:10.0pt;font-family:Arial'>The user initiates a
     refactoring operation whose context is “A” and “workspace.”<o:p></o:p></span></li>
 <li class=MsoNormal style='mso-list:l2 level1 lfo14;tab-stops:list .5in'><span
     style='font-size:10.0pt;font-family:Arial'>The user makes additional local
     edits to editor A.<o:p></o:p></span></li>
 <li class=MsoNormal style='mso-list:l2 level1 lfo14;tab-stops:list .5in'><span
     style='font-size:10.0pt;font-family:Arial'>The user goes to the navigator
     and selects Undo.<o:p></o:p></span></li>
</ol>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p>&nbsp;</o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>In the
proposed implementation, the navigator requests an undo for the workspace
context.<span style='mso-spacerun:yes'>  </span>The refactoring 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
operation will not be allowed.<span style='mso-spacerun:yes'>  </span>An
explanation will be provided to the user after the fact:<span
style='mso-spacerun:yes'>  </span>“Cannot undo the refactoring operation
because there have been subsequent changes to A.”<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>&nbsp;</o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Future
releases may warn the user or provide a preference to determine whether the
undo should proceed anyway, and whether the subsequent changes to “A” should
also be undone, or be flushed from the history. Early prototypes of the
framework showed that such warnings interrupt workflow and can be very
difficult to understand, so the initial UI will be to prohibit the undo,
explaining why.<span style='mso-spacerun:yes'>   </span><o:p></o:p></span></p>

<h2>Migration Examples</h2>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>The
following examples explain how existing code can be migrated to use the
operations framework.<span style='mso-spacerun:yes'>  </span>An early prototype
used these techniques to integrate the SDK text editor, refactoring framework,
and sample applications into a common undo framework.<span
style='mso-spacerun:yes'>  </span></span></p>

<h3>Mapping existing actions or command handlers to operations</h3>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>Converting
an existing action to use operations is straightforward, apart from
implementing the undo and redo behavior for the action.<span
style='mso-spacerun:yes'>  </span>The run() or <span class=SpellE>runWithEvent</span>
method inside the action should create an operation, execute it, and add it to
the operations history, rather than run the code inside the method.<span
style='mso-spacerun:yes'>  </span>The following code shows the existing run()
method in the <span class=SpellE>EditorAction</span> of the <span class=SpellE>readme</span>
tool example (<span class=SpellE>org.eclipse.ui.examples.readmetool</span>):<o:p></o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p>&nbsp;</o:p></span></p>

<pre>public void run() {</pre><pre><span style='mso-spacerun:yes'>            </span>String <span
class=SpellE>editorName</span> = <span class=SpellE>MessageUtil.getString</span>(&quot;<span
class=SpellE>Empty_Editor_Name</span>&quot;); </pre><pre><span style='mso-spacerun:yes'>            </span>if (<span
class=SpellE>activeEditor</span> != null)</pre><pre><span style='mso-spacerun:yes'>       </span><span style='mso-spacerun:yes'>         </span><span
class=SpellE>editorName</span> = <span class=SpellE>activeEditor.getTitle</span>();</pre><pre><span style='mso-spacerun:yes'>            </span><span
class=SpellE>MessageDialog</span></pre><pre><span style='mso-spacerun:yes'>                    </span>.<span
class=SpellE>openInformation</span>(</pre><pre><span style='mso-spacerun:yes'>                            </span>shell,</pre><pre><span style='mso-spacerun:yes'>                            </span><span
class=SpellE>MessageUtil.getString</span>(&quot;<span class=SpellE>Readme_Editor</span>&quot;), </pre><pre><span style='mso-spacerun:yes'>                            </span><span
class=SpellE>MessageUtil.format</span>(&quot;<span class=SpellE>ReadmeEditorActionExecuted</span>&quot;, </pre><pre><span
style='mso-tab-count:4'>                               </span>new Object[] { <span
class=SpellE>getText</span>(), <span class=SpellE>editorName</span> })); </pre><pre><span style='mso-spacerun:yes'>        </span>}</pre><pre><span
style='font-family:Arial'>Using operations, the run method simplifies:<o:p></o:p></span></pre><pre><span
style='font-family:Arial'><o:p>&nbsp;</o:p></span></pre><pre><span style='mso-spacerun:yes'>        </span>public void run() {</pre><pre><span style='mso-spacerun:yes'>            </span>String <span
class=SpellE>editorName</span> = <span class=SpellE>MessageUtil.getString</span>(&quot;<span
class=SpellE>Empty_Editor_Name</span>&quot;); </pre><pre><span style='mso-spacerun:yes'>           </span><span style='mso-spacerun:yes'> </span>if (<span
class=SpellE>activeEditor</span> != null)</pre><pre><span style='mso-spacerun:yes'>                </span><span
class=SpellE>editorName</span> = <span class=SpellE>activeEditor.getTitle</span>();</pre><pre><span style='mso-spacerun:yes'>            </span>// create the operation</pre><pre><span style='mso-spacerun:yes'>            </span><span
class=SpellE>IOperation</span> operation = new <span class=SpellE>EditorOperation</span>(</pre><pre><span
style='mso-tab-count:2'>               </span><span class=SpellE>getText</span>(),shell, <span
class=SpellE>editorName</span>);</pre><pre><span style='mso-spacerun:yes'>            </span>// execute (and add to the history)</pre><pre><span style='mso-spacerun:yes'>   </span><span style='mso-spacerun:yes'>         </span><span
class=SpellE>history.execute</span>(operation, null);</pre><pre><span style='mso-spacerun:yes'>        </span>}</pre><pre><span
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
style='font-family:Arial'><o:p>&nbsp;</o:p></span></pre><pre>class <span
class=SpellE>EditorOperation</span> extends <span class=SpellE>AbstractOperation</span> {</pre><pre><span style='mso-spacerun:yes'>        </span>Shell <span
class=SpellE>fShell</span>;</pre><pre><span style='mso-spacerun:yes'>        </span>String <span
class=SpellE>fEditorName</span>;</pre><pre><span style='mso-spacerun:yes'>     </span><span style='mso-spacerun:yes'>   </span>public <span
class=SpellE>EditorOperation</span>(String label, Shell <span class=SpellE>shell</span>, String <span
class=SpellE>editorName</span>) {</pre><pre><span style='mso-spacerun:yes'>            </span>super(label);</pre><pre><span style='mso-spacerun:yes'>            </span><span
class=SpellE>fShell</span> = shell;</pre><pre><span style='mso-spacerun:yes'>            </span><span
class=SpellE>fEditorName</span> = <span class=SpellE>editorName</span>;</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 <span
class=SpellE>IStatus</span> execute(<span class=SpellE>IProgressMonitor</span> monitor) {</pre><pre><span style='mso-spacerun:yes'>        </span><span style='mso-spacerun:yes'>    </span><span
class=SpellE>MessageDialog.openInformation</span>(</pre><pre><span style='mso-spacerun:yes'>                    </span><span
class=SpellE>fShell</span>,</pre><pre><span style='mso-spacerun:yes'>                    </span><span
class=SpellE>MessageUtil.getString</span>(&quot;<span class=SpellE>Readme_Editor</span>&quot;), </pre><pre><span style='mso-spacerun:yes'>                    </span><span
class=SpellE>MessageUtil.format</span>(&quot;<span class=SpellE>ReadmeEditorActionExecuted</span>&quot;, </pre><pre><span
style='mso-tab-count:3'>                       </span>new Object[] { <span
class=SpellE>getLabel</span>(), <span class=SpellE>fEditorName</span> }));<span style='mso-spacerun:yes'>  </span></pre><pre><span style='mso-spacerun:yes'>            </span>return <span
class=SpellE>Status.OK_STATUS</span>;</pre><pre><span style='mso-spacerun:yes'>        </span>}</pre><pre><span style='mso-spacerun:yes'>        </span>public <span
class=SpellE>IStatus</span> undo(<span class=SpellE>IProgressMonitor</span> monitor) {</pre><pre><span style='mso-spacerun:yes'>            </span>// implement the undo here</pre><pre><span style='mso-spacerun:yes'>            </span>return <span
class=SpellE>Status.OK_STATUS</span>;</pre><pre><span style='mso-spacerun:yes'>        </span>}</pre><pre><span style='mso-spacerun:yes'>        </span>public <span
class=SpellE>IStatus</span> redo(<span class=SpellE>IProgressMonitor</span> monitor) {</pre><pre><span style='mso-spacerun:yes'>            </span>// implement the redo here</pre><pre><span style='mso-spacerun:yes'>            </span>return <span
class=SpellE>Status.OK_STATUS</span>;</pre><pre><span style='mso-spacerun:yes'>        </span>}</pre><pre><span style='mso-spacerun:yes'>    </span>}</pre><pre><o:p>&nbsp;</o:p></pre><pre><span
style='font-family:Arial'>If an <span class=SpellE>IHandler</span> 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
style='font-family:Arial'><o:p>&nbsp;</o:p></span></pre><pre><span style='mso-spacerun:yes'>        </span>public Object execute(Map <span
class=SpellE>params</span>) throws <span class=SpellE>ExecutionException</span> {</pre><pre><span style='mso-spacerun:yes'>        </span>try {</pre><pre><span
style='mso-tab-count:1'>        </span><span style='mso-spacerun:yes'>    </span><span
class=SpellE>IEditorPart</span> <span class=SpellE>activeEditor</span> = <span
class=SpellE>params.get</span>(&quot;ACTIVE_EDITOR&quot;);</pre><pre><span
style='mso-tab-count:1'>        </span><span style='mso-spacerun:yes'>    </span>Shell <span
class=SpellE>shell</span> = <span class=SpellE>params.get</span>(&quot;SHELL&quot;);</pre><pre><span
style='mso-tab-count:1'>        </span><span style='mso-spacerun:yes'>    </span>String label = <span
class=SpellE>params.get</span>(&quot;NAME&quot;);</pre><pre><span
style='mso-tab-count:1'>        </span><span style='mso-spacerun:yes'>    </span>String <span
class=SpellE>editorName</span> = <span class=SpellE>MessageUtil.getString</span>(&quot;<span
class=SpellE>Empty_Editor_Name</span>&quot;); </pre><pre><span style='mso-spacerun:yes'>            </span>if (<span
class=SpellE>activeEditor</span> != null)</pre><pre><span style='mso-spacerun:yes'>                </span><span
class=SpellE>editorName</span> = <span class=SpellE>activeEditor.getTitle</span>();</pre><pre><span style='mso-spacerun:yes'>            </span>// create the operation</pre><pre><span style='mso-spacerun:yes'>            </span><span
class=SpellE>IOperation</span> operation =new <span class=SpellE>EditorOperation</span>(label, shell, <span
class=SpellE>editorName</span>);</pre><pre><o:p>&nbsp;</o:p></pre><pre><span style='mso-spacerun:yes'>            </span>// execute (and add to the history)</pre><pre><span style='mso-spacerun:yes'>            </span><span
class=SpellE>history.execute</span>(operation, null);</pre><pre><span style='mso-spacerun:yes'>        </span>} catch (Exception e) {</pre><pre><span style='mso-spacerun:yes'>            </span>throw new <span
class=SpellE>ExecutionException</span>(</pre><pre><span style='mso-spacerun:yes'>                    </span>&quot;While executing the operation, an exception occurred&quot;, 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
style='font-family:Arial'><o:p>&nbsp;</o:p></span></pre>

<p class=MsoNormal><span class=GramE><span style='font-size:10.0pt;font-family:
Arial'>When an action launches a wizard.</span></span><span style='font-size:
10.0pt;font-family:Arial'> <span class=GramE>then</span> 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. <o:p></o:p></span></p>

<h3>Refactoring example:<span style='mso-spacerun:yes'>  </span>mapping
existing protocol to <span class=SpellE>IOperation</span></h3>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>In the current
SDK implementation, <span class=SpellE>org.eclipse.ltk.core.refactoring</span>
provides an undo framework for undoing refactoring operations.<span
style='mso-spacerun:yes'>  </span>This framework is based on the notion of
“Change” objects.<span style='mso-spacerun:yes'>  </span>Change objects that
can be undone are responsible for returning the undo version of a change when
they are executed.<span style='mso-spacerun:yes'>  </span>An undo stack is
maintained by an internal undo manager.<span style='mso-spacerun:yes'> 
</span>This undo manager invalidates the history whenever an unknown workspace
change occurs.<span style='mso-spacerun:yes'>  </span>Undo-aware objects send
signals to the undo manager as they perform operations, so that the undo
manager will not invalidate the history.<o:p></o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'><o:p>&nbsp;</o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>A prototype
integrated the refactoring change framework with the operations framework as
follows:<o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:39.0pt;text-indent:-.25in;mso-list:l3 level1 lfo16;
tab-stops:list 39.0pt'><![if !supportLists]><span style='font-size:10.0pt;
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>1.<span
style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; </span></span></span><![endif]><span
style='font-size:10.0pt;font-family:Arial'>The change objects were <span
class=SpellE>wrappered</span> with a class that implements <span class=SpellE>IOperation</span>
(and <span class=SpellE>IWorkspaceOperation</span>) and maps the operation
protocol to the Change protocol.<o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:39.0pt;text-indent:-.25in;mso-list:l3 level1 lfo16;
tab-stops:list 39.0pt'><![if !supportLists]><span style='font-size:10.0pt;
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>2.<span
style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; </span></span></span><![endif]><span
style='font-size:10.0pt;font-family:Arial'>The refactoring undo manager was
replaced with an alternate implementation that uses the operations history to
maintain the undo and redo history.<o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:39.0pt;text-indent:-.25in;mso-list:l3 level1 lfo16;
tab-stops:list 39.0pt'><![if !supportLists]><span style='font-size:10.0pt;
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>3.<span
style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; </span></span></span><![endif]><span
style='font-size:10.0pt;font-family:Arial'>The workspace listener and validation
strategy used in the Change framework was maintained since the timing of the
notifications was critical.<span style='mso-spacerun:yes'>  </span>Additional
integration work could be done to use the operations history listeners for the
same purpose, or to change the validation strategy as more workspace operations
are supported outside of refactoring.<o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:39.0pt;text-indent:-.25in;mso-list:l3 level1 lfo16;
tab-stops:list 39.0pt'><![if !supportLists]><span style='font-size:10.0pt;
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>4.<span
style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; </span></span></span><![endif]><span
style='font-size:10.0pt;font-family:Arial'>Unrelated listeners (such as text
editors) listened for new operations being added.<span
style='mso-spacerun:yes'>  </span>These listeners could check the elements
affected by the workspace operation and determine whether another context
should be assigned to the operation.<o:p></o:p></span></p>

<p class=MsoNormal style='margin-left:39.0pt;text-indent:-.25in;mso-list:l3 level1 lfo16;
tab-stops:list 39.0pt'><![if !supportLists]><span style='font-size:10.0pt;
font-family:Arial;mso-fareast-font-family:Arial'><span style='mso-list:Ignore'>5.<span
style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; </span></span></span><![endif]><span
style='font-size:10.0pt;font-family:Arial'>Refactoring operations could be
undone and redone from any view or editor that installed the undo and redo
handlers on the workspace context.<o:p></o:p></span></p>

<h3>Text editor example:<span style='mso-spacerun:yes'>  </span>implementing <span
class=SpellE>IOperation</span> in preexisting commands</h3>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>The <span
class=SpellE>JFace</span> text framework supports undo and redo of text editing
operations.<span style='mso-spacerun:yes'>  </span>This implementation relies
on private undo stacks that are maintained by each editor.<span
style='mso-spacerun:yes'>  </span>The <span class=SpellE>JFace</span> <span
class=SpellE>IUndoManager</span> listens to text changes coming from the
underlying widget, and builds a <span class=SpellE>TextCommand</span> for each
undoable edit.<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>&nbsp;</o:p></span></p>

<p class=MsoNormal><span style='font-size:10.0pt;font-family:Arial'>A prototype
integrated the text undo in <span class=SpellE>JFace</span> with the operations
framework as follows:<o:p></o:p></span></p>

<ol style='margin-top:0in' start=1 type=1>
 <li class=MsoNormal style='mso-list:l4 level1 lfo19;tab-stops:list .5in'><span
     style='font-size:10.0pt;font-family:Arial'>The existing <span
     class=SpellE>TextCommand</span> was altered to implement the <span
     class=SpellE>IOperation</span> interface.<o:p></o:p></span></li>
 <li class=MsoNormal style='mso-list:l4 level1 lfo19;tab-stops:list .5in'><span
     style='font-size:10.0pt;font-family:Arial'>Specialized contexts (one
     instance for each text editor) are assigned to the operations.<o:p></o:p></span></li>
 <li class=MsoNormal style='mso-list:l4 level1 lfo19;tab-stops:list .5in'><span
     style='font-size:10.0pt;font-family:Arial'>The existing <span
     class=SpellE>UndoManager</span> was replaced with an alternate
     implementation that added text commands to the operations history instead
     of a local stack, and used the operation history protocol when handling
     undo and redo commands.<o:p></o:p></span></li>
 <li class=MsoNormal style='mso-list:l4 level1 lfo19;tab-stops:list .5in'><span
     style='font-size:10.0pt;font-family:Arial'>The undo manager installs a
     listener on the history to monitor new operations that are added to the
     history.<o:p></o:p></span></li>
 <li class=MsoNormal style='mso-list:l4 level1 lfo19;tab-stops:list .5in'><span
     style='font-size:10.0pt;font-family:Arial'>When an “outside” operation is
     added to the history, the undo manager consults the editor’s operation
     context to see if the outside operation is relevant.<span
     style='mso-spacerun:yes'>  </span>The editor context can check the
     elements affected by workspace operations and add itself to the
     operation’s context if appropriate.<o:p></o:p></span></li>
</ol>

<p class=MsoNormal style='text-align:justify'><span style='font-size:10.0pt;
font-family:Arial'><o:p>&nbsp;</o:p></span></p>

</div>

</body>

</html>