bundles/org.eclipse.platform.doc.isv/guide/wrkAdv_undo_ide.htm - gerrit/platform/eclipse.platform.common - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><html lang="en">
 <HEAD>

 <meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2005. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >

 <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
 <META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">

 <LINK REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1" TYPE="text/css">
 <TITLE>
 Undo and the IDE Workbench
 </TITLE>

 <link rel="stylesheet" type="text/css" HREF="../book.css">
 </HEAD>
 <BODY BGCOLOR="#ffffff">
 <h3>Undo and the IDE Workbench</h3>
 <p>
 We've seen code snippets that use workbench protocol for accessing the operations history and the workbench undo
 context.  This is achieved using <a href="../reference/api/org/eclipse/ui/operations/IWorkbenchOperationSupport.html"><b>IWorkbenchOperationSupport</b></a>,
 which can be obtained from the workbench.  The notion of a workbench-wide undo context is fairly general.  It is up to the workbench application
 to determine what specific scope is implied by the workbench undo context, and which views or editors use the
 workbench context when providing undo support.
 </p>
 <p>
 In the case of the Eclipse IDE workbench, the workbench undo context should be assigned to any operation that affects the IDE workspace at large.
 This context is used by views that manipulate the workspace, such as the Resource Navigator.  The IDE workbench installs an adapter on
 the workspace for <a href="../reference/api/org/eclipse/core/commands/operations/IUndoContext.html"><b>IUndoContext</b></a> that returns the
 workbench undo context.  This model-based registration allows plug-ins that manipulate the workspace to obtain the appropriate undo context, even if they are headless and
 do not reference any workbench classes.</p>
 <pre>// get the operation history
 IOperationHistory history = OperationHistoryFactory.getOperationHistory();

 // obtain the appropriate undo context for my model
 IUndoContext workspaceContext = (IUndoContext)ResourcesPlugin.getWorkspace().getAdapter(IUndoContext.class);
 if (workspaceContext != null) {
 	// create an operation and assign it the context
 }

 </pre>
 Other plug-ins are encouraged to use this same technique for registering
 model-based undo contexts.
 <h3>Undoable Workspace Operations</h3>
 <p>
 Undoable operations are provided by the IDE plug-in that allow you to execute,
 undo, and redo common workspace manipulations.  Operations are provided for
 creating, moving, copying, and deleting projects, folders, and files.  The IDE
 plug-in uses these operations to provide undo support in the Resource Navigator.
 These classes can also be used by clients.  They are available in the package
 <a href="../reference/api/org/eclipse/ui/ide/undo/package-summary.html"><b>org.eclipse.ui.ide.undo</b></a>.
  </p>
 <p>
 Using the workspace undoable operations is similar to the examples shown for using
 any <a href="../reference/api/org/eclipse/core/commands/operations/IUndoableOperation.html"><b>IUndoableOperation</b></a>.
 The primary difference is that some of the details, such as assigning the appropriate
 undo context, are handled internally by the operation.  The following snippet shows
 how to use an undoable operation for creating a new file.
 </p>
 <pre>
 IFile newFileHandle = IDEWorkbenchPlugin.getPluginWorkspace().getRoot().
 	getFile(myNewFilePath);
 CreateFileOperation op = new CreateFileOperation(newFileHandle, null,
 	initialContentStream, "Create New File");
 </pre>
 <p>
 The operation is configured with a file handle for the file to be created, an
 input stream with the initial contents, and a label describing the operation.  Internally,
 the operation will assign the workspace undo context and handle other details such
 as keeping track of which resources the operation manipulates.  To execute the operation,
 the caller uses the standard <a href="../reference/api/org/eclipse/core/commands/operations/IOperationHistory.html"><b>IOperationHistory</b></a>
 protocol.
 </p>
 <pre>
 try {
 	PlatformUI.getWorkbench().getOperationSupport().getOperationHistory()
 		.execute(op, myProgressMonitor,
 			WorkspaceUndoUtil.getUIInfoAdapter(getShell()));
 } catch (final ExecutionException e) {
 	// handle exceptions
 }
 </pre>
 <p>
 Note that the caller is responsible for providing a progress monitor if desired, and
 an <a href="../reference/api/org/eclipse/core/runtime/IAdaptable.html"><b>IAdaptable</b></a> that
 can provide the shell that should be used for any prompting. The utility class
 <a href="../reference/api/org/eclipse/ui/ide/undo/WorkspaceUndoUtil.html"><b>WorkspaceUndoUtil</b></a>
 provides a utility method for creating the necessary adapter from a shell.
 </p>
 <p>Callers are also responsible for determining whether to execute the operation in
 the UI thread, the background, or a workbench job.  If the operation should be executed
 in the background, then the caller should create the appropriate progress monitor and run the
 snippet shown above in the appropriate runnable.
 </p>
 <p>The undo and redo of the operation will be performed by the undo and redo action handlers
 when the user initiates undo or redo.  The standard workbench action handlers use
 <a href="../reference/api/org/eclipse/core/commands/operations/IAdvancedUndoableOperation2.html"><b>IAdvancedUndoableOperation2</b></a>
 protocol to determine how to perform the undo and redo of operations.
 All of the workspace operations implement protocol that instructs clients to run the undo or redo
 of the operation in the background if possible.
 </p>
 </BODY>
 </HTML>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><html lang="en">
	<HEAD>

	<meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2005. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >

	<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
	<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">

	<LINK REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1" TYPE="text/css">
	<TITLE>
	Undo and the IDE Workbench
	</TITLE>

	<link rel="stylesheet" type="text/css" HREF="../book.css">
	</HEAD>
	<BODY BGCOLOR="#ffffff">
	<h3>Undo and the IDE Workbench</h3>
	<p>
	We've seen code snippets that use workbench protocol for accessing the operations history and the workbench undo
	context. This is achieved using <a href="../reference/api/org/eclipse/ui/operations/IWorkbenchOperationSupport.html"><b>IWorkbenchOperationSupport</b></a>,
	which can be obtained from the workbench. The notion of a workbench-wide undo context is fairly general. It is up to the workbench application
	to determine what specific scope is implied by the workbench undo context, and which views or editors use the
	workbench context when providing undo support.
	</p>
	<p>
	In the case of the Eclipse IDE workbench, the workbench undo context should be assigned to any operation that affects the IDE workspace at large.
	This context is used by views that manipulate the workspace, such as the Resource Navigator. The IDE workbench installs an adapter on
	the workspace for <a href="../reference/api/org/eclipse/core/commands/operations/IUndoContext.html"><b>IUndoContext</b></a> that returns the
	workbench undo context. This model-based registration allows plug-ins that manipulate the workspace to obtain the appropriate undo context, even if they are headless and
	do not reference any workbench classes.</p>
	<pre>// get the operation history
	IOperationHistory history = OperationHistoryFactory.getOperationHistory();

	// obtain the appropriate undo context for my model
	IUndoContext workspaceContext = (IUndoContext)ResourcesPlugin.getWorkspace().getAdapter(IUndoContext.class);
	if (workspaceContext != null) {
	// create an operation and assign it the context
	}

	</pre>
	Other plug-ins are encouraged to use this same technique for registering
	model-based undo contexts.
	<h3>Undoable Workspace Operations</h3>
	<p>
	Undoable operations are provided by the IDE plug-in that allow you to execute,
	undo, and redo common workspace manipulations. Operations are provided for
	creating, moving, copying, and deleting projects, folders, and files. The IDE
	plug-in uses these operations to provide undo support in the Resource Navigator.
	These classes can also be used by clients. They are available in the package
	<a href="../reference/api/org/eclipse/ui/ide/undo/package-summary.html"><b>org.eclipse.ui.ide.undo</b></a>.
	</p>
	<p>
	Using the workspace undoable operations is similar to the examples shown for using
	any <a href="../reference/api/org/eclipse/core/commands/operations/IUndoableOperation.html"><b>IUndoableOperation</b></a>.
	The primary difference is that some of the details, such as assigning the appropriate
	undo context, are handled internally by the operation. The following snippet shows
	how to use an undoable operation for creating a new file.
	</p>
	<pre>
	IFile newFileHandle = IDEWorkbenchPlugin.getPluginWorkspace().getRoot().
	getFile(myNewFilePath);
	CreateFileOperation op = new CreateFileOperation(newFileHandle, null,
	initialContentStream, "Create New File");
	</pre>
	<p>
	The operation is configured with a file handle for the file to be created, an
	input stream with the initial contents, and a label describing the operation. Internally,
	the operation will assign the workspace undo context and handle other details such
	as keeping track of which resources the operation manipulates. To execute the operation,
	the caller uses the standard <a href="../reference/api/org/eclipse/core/commands/operations/IOperationHistory.html"><b>IOperationHistory</b></a>
	protocol.
	</p>
	<pre>
	try {
	PlatformUI.getWorkbench().getOperationSupport().getOperationHistory()
	.execute(op, myProgressMonitor,
	WorkspaceUndoUtil.getUIInfoAdapter(getShell()));
	} catch (final ExecutionException e) {
	// handle exceptions
	}
	</pre>
	<p>
	Note that the caller is responsible for providing a progress monitor if desired, and
	an <a href="../reference/api/org/eclipse/core/runtime/IAdaptable.html"><b>IAdaptable</b></a> that
	can provide the shell that should be used for any prompting. The utility class
	<a href="../reference/api/org/eclipse/ui/ide/undo/WorkspaceUndoUtil.html"><b>WorkspaceUndoUtil</b></a>
	provides a utility method for creating the necessary adapter from a shell.
	</p>
	<p>Callers are also responsible for determining whether to execute the operation in
	the UI thread, the background, or a workbench job. If the operation should be executed
	in the background, then the caller should create the appropriate progress monitor and run the
	snippet shown above in the appropriate runnable.
	</p>
	<p>The undo and redo of the operation will be performed by the undo and redo action handlers
	when the user initiates undo or redo. The standard workbench action handlers use
	<a href="../reference/api/org/eclipse/core/commands/operations/IAdvancedUndoableOperation2.html"><b>IAdvancedUndoableOperation2</b></a>
	protocol to determine how to perform the undo and redo of operations.
	All of the workspace operations implement protocol that instructs clients to run the undo or redo
	of the operation in the background if possible.
	</p>
	</BODY>
	</HTML>