org.eclipse.platform.doc.isv/porting/3.1/recommended.html

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1.17 - (download) (as text) (annotate)
Fri May 26 15:54:56 2006 UTC (3 years, 6 months ago) by johna
Branch: MAIN
CVS Tags: v20070607-1300, v20070607-0010, v20070510-0010, I20070206-0010, v20060602-1302, I20070814-0800, v20070515-0010, v20070109-1100, v20060925, v20070313-1330, v20070607-0011, v20060731, v20070403-0800, v20070424-0800, v20070917-1800, v20070605-0010, v20070605-0011, v20060803, v20070306-0800, v20070806-1800, v20070205, v20070130-0800, R3_3_1_1, v20070430-0010, v20070202, v20060808, v20070319-0010, v20070613, v20061121-0800, v20061213-1300, R3_2_1, v20070531-0010a, v20061129, R3_2_2, v20061017-0800, v20070531-1734, v20061107-0800, v20070427, v20060809-1200, v20070226, v20061211-0010, v20060724, v20070525-0010, v20070528-1858, v20070724-0800, v20070516-0800, v20070911-0800, v20061113, v20060602-1130, r321_v2006030, v20061101-0800, v20070427-1300, v20070427-0010, v20070802-0800, v20070525-1346, v20070607-2219, v20070523-0010, v20060710, v20061213-1300b, v20070205-1800, v20070917_1242, v20061023, v20070220-0800, v20060926-0800, v20070313-0800, v20070815, R3_2, R3_3, v20060829-0800, M20070913-0800, v20061003-0800, v20070116-0800, v20060602-0010-zrh, I20070731-0800, v20061024-0800, v20070828-0800, v20070501-0010, v20070319-1800, v20070524-0800, v20070419, r331_v20070913, pre_R3_3, v20061030-0010, v20070318, v20070416, v20070227-0800, v20070808-1800, v20070430-0800, v20070508-0800, v20070904-0800, v20070503-0800, v20070913-0800, r322_v20070109, v20070316, v20070123, v20070122, v20070925-0800, v20060602-0011sf, v20061006, I20070821-0800, v20070524-0010, v20061205-0800, v20070511-0010, v20070525-1050, v20070404, v20061030-1200, v20061128-0800, v20061120, v20070530-0010, v20070806-0010, v20070710-0800, v20070410-0800, v20060605, v20070525-0010a, v20070525-0010b, I20070814-0800a, v20070524, v20070123-0800, v20070417-0800, M20070822-0800, R32x_v20070115, v20061010-0800, v20070814-0800, v20070205-0010, v20061114-0800, v20070606-0011, v20070601-1520, v20070717-0800, R32x_v20060710, R32x_v20060711, v20070213-0800, v20070319-0800, v20060612-0900, v20070608-1300, v20070606-0010, v20060612, v20070327-0800, v20060821, v20070516-0010, v20060602-0011, v20071002-0800, v20070321-1800, v20070731-0800, v20070108, M20070801-0800, v20070427-0800, v20070607-1800, v20070423, R3_3_1, R3_3_2, v20070821-0800, v20070312, R32x_v20060808, v20070531-1300, v20070531-0010, v20070914, v20070917, v20070919, v20060626, v20061211-1600, v20070219, v20060918, I20060605-1430, v20070525-1225, v20070512-0010, v20070430-1300, v20061208, v20070621, v20070511-0100, v20070530-1714
Branch point for: R3_3_maintenance, R3_2_maintenance
Changes since 1.16: +1 -1 lines 
close anchor tag

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>

<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>Changes required when adopting 3.1 mechanisms and APIs</title>
</head>

<body>

<h2>Changes required when adopting 3.1 mechanisms and APIs</h2>
<p>This section describes changes that are required if you are trying to change
 your 3.0 plug-in to adopt the 3.1 mechanisms and APIs.</p>
  
<h3>Platform undo/redo support</h3>
<p>
Eclipse 3.1 provides a new infrastructure for defining <b>undoable operations</b> and a shared
<b>operation history</b> that keeps track of operations that have been executed, undone, and
redone. The various undo frameworks provided by add-on plug-ins should
migrated over time to the platform operation support, so that clients of these frameworks 
can integrate more deeply with the platform and make their undoable operations available
for undo in other plug-in views and editors.  See the 
<a href="../../guide/wrkAdv_undo.htm">Undoable operations</a> documentation for basic
information about adding undo support to a plug-in.  Plug-ins that already define undo support
or use another framework can be migrated to the new undo support in a staged fashion, as
described below.</p>
<h4>Migrating plug-in specific operation (command) classes to IUndoableOperation</h4>
<p>Plug-ins that already define classes describing their undoable operations should add
an implementation for the interface <b>IUndoableOperation</b> to their operation/command
classes.  Plug-ins may still use older frameworks for managing the history (command stack)
if necessary, but providing an interface for <b>IUndoableOperation</b> allows a plug-in's
clients to use the same operations in the platform operations history, and to mix and match
undoable operations from different plug-ins.  This strategy is similar to that used by
the SDK text editors to migrate to the new operations framework.  If a direct mapping of
the interface is not possible, wrappers can be used to map <b>IUndoableOperation</b>
protocol to legacy undo objects.  This strategy is used by the Platform/JDT
refactoring support.  Migration of the operation/command classes to <b>IUndoableOperation</b>
is an important step because it allows the undoable operations from different frameworks
to be utilized by other plug-ins without either plug-in having to migrate completely.</p>
<h4>Migrating command stacks with IOperationHistory</h4>
<p>Once undoable operations or commands are expressed in terms of <b>IUndoableOperation</b>, plug-ins 
that define an undo history (command stack) for keeping track of the undoable and redoable 
operations can migrate to the platform operations history by defining an <b>IUndoContext</b>
that represents their undo history.  Undo histories that were previously managed locally 
can be merged into the common operation history by defining a unique 
undo context either for each part or for each model object, adding the appropriate undo context to each operation, and
then adding the operation to the platform operation history.  Undo histories with more 
global scope can be implemented by defining a unique undo context representing that undo scope,
assigning that context to each operation, and then adding the operation to the platform
operation history.  See the 
<a href="../../guide/wrkAdv_undo.htm">Undoable operations</a> documentation for examples of
creating undo contexts, assigning them, and adding operations to the platform operation history.
</p>
<h4>Defining undoable operations global to the workbench</h4>
<p>Plug-ins that wish their operations to be undoable from workbench views such as the 
Navigator or Package Explorer should assign the workbench undo context to their operations.
See the <a href="../../guide/wrkAdv_undo.htm">Undoable operations</a> documentation for more information
about this undo context and how it can be retrieved by both workbench and headless plug-ins.
</p>
<h3>Platform undo/redo action handlers</h3>
<p>
Plug-ins that do not define an undo infrastructure or undoable operations, but wish to 
provide access to the platform's undo history, should consider retargeting the global 
undo and redo action handlers with the new common undo and redo action handlers.  The action
handlers should be assigned an undo context specifying which undo and redo history
is to be shown.  Plug-ins can use their locally defined undo contexts for showing "part-local"
undo and redo history.  The workbench undo context can be used for showing workbench-wide
undo and redo history.  Again, the 
<a href="../../guide/wrkAdv_undo.htm">Undoable operations</a> documentation 
has a complete example.</p>
<h4>Migrating text operation actions to the common action handlers</h4>
<p>Migrating text editor undo and redo actions is a bit different than simple retargeting
of the global undo/redo action handlers.  The <b>AbstractTextEditor</b> framework defines 
common text actions using a parameterized <b>TextOperationAction</b>.  These actions are stored
locally in the framework and used to dispatch various commands to an editor's text operation
target.  For text undo to work properly, the text editor framework relies on the presence 
of text operation actions with the proper id's (<tt>ITextEditorActionConstants.REDO</tt>
and <tt>ITextEditorActionConstants.UNDO</tt>). 
</p>
<p><b>AbstractTextEditor</b> has been migrated so that it creates the common action handlers, while
still assigning them to the TextOperationAction table with their legacy id's.  In this way, the
new undo and redo action handlers can be retrieved using the legacy techniques for retrieving
the action and performing an operation.  Text editors in the <b>AbstractTextEditor</b> hierarchy 
will inherit this behavior.  </p>
<p>Editors that do not inherit this behavior from <b>AbstractTextEditor</b> should consider 
migrating any existing undo and redo actions to use the new handlers.  Editors with
legacy undo and redo TextOperationActions will still have working local undo support, since 
the JFace Text undo manager API used by these actions is still supported.  However, the 
undo and redo action labels will not be consistent with the new Eclipse SDK undo/redo actions, which show 
the name of the available undo or redo operation.  To create the common undo and redo
action handlers, the undo context used by the text viewer's undo manager should
be used when creating the action handlers, and those handlers should be set into the
editor using the appropriate <tt>ITextEditorActionConstants</tt> id.  See 
<b><tt>AbstractTextEditor.createUndoRedoActions()</tt></b> and <b><tt>AbstractTextEditor.getUndoContext()</tt></b>
for a detailed example.  Editors that rely on an <b>EditorActionBarContributor</b> subclass to 
add to the action bars of their editors can use a similar technique by creating undo and redo action
handlers and setting them when the active editor is set. </p>
<h3>Help Enhancements</h3>
<h4>Information Search</h4>
<p>Plug-ins that contribute search pages into the <b>Search</b> dialog should 
consider porting all their information-style searches into federated search 
engines. Since 3.1, all information-style search is separated from the 
workbench-artifact search. Information search engines are run in parallel as 
background jobs and their results collated in the new Help view. See
<a href="../../guide/help_search.htm">Help Search</a> for more details.</p>
<h4>Dynamic help</h4>
<p>The new dynamic help view will work with existing context IDs that are 
statically associated with widgets in workbench parts and dialogs. However, if 
you catch help event yourself and show help, dynamic help view will not be able 
to show anything useful. To fix the problem, you should adapt to the new <code>
IContextProvider</code> interface as described in
<a href="../../guide/help_context_dynamic.htm">Dynamic Context Help</a> 
document.</p>

<h3><a name="PreferenceStore"></a>JFace Preference Stores</h3>
<p>As of release 3.1 the <a href="../api/org/eclipse/jface/preference/IPreferenceStore.html">
  <strong>org.eclipse.jface.preference.IPreferenceStore</strong></a> 
  that is returned from <b>AbstractUIPlugin.getPreferenceStore()</b> will be an instance 
  of <strong><a href="../api/org/eclipse/ui/preferences/ScopedPreferenceStore.html">
  org.eclipse.ui.preferences.ScopedPreferenceStore</a></strong>. 
  The ScopedPreferenceStore uses the <b>org.eclipse.core.runtime.preferences</b> API to manage preferences. 
  In 3.0 it used the compatibility layer to interface with an instance of <strong>
  <a href="../api/org/eclipse/core/runtime/Preferences.html">org.eclipse.core.runtime.Preferences</a></strong>.</p>
<p>In 3.1 we have disambiguated IPreferenceStore to be more specific about the 
  types of the values sent in preference changed events. The IPreferenceStore 
  from AbstractUIPlugin#getPreferenceStore has the same behavior as before,
  but it is now specified more clearly.</p>
<p><strong>Typing:</strong> <strong><a href="../api/org/eclipse/jface/util/IPropertyChangeListener.html">
  org.eclipse.jface.util.IPropertyChangeListener</a></strong> 
  added to an IPreferenceStore can potentially get two types of old and new values 
  - typed or String representations. Any event generated by a call to a typed 
  IPreferenceStore API (such as <code>setValue(String key, boolean value)</code> 
  will generate a typed event. However it is also possible that events will be 
  propagated from the core runtime preferences which generate an untyped event 
  (for instance on a preference import). Property listeners need to be prepared 
  for both. Note also that typed events will not be propagating primitive types 
  so a call to <code>setValue(String key, boolean value)</code> will result in 
  an event where the oldValue and newValue are Booleans.</p>
<p><strong>putValue</strong>: IPreferenceStore.putValue(String key, String value) 
  will not generate a change event. This API is meant to be used for private preferences 
  that no listener would want to react to.</p>
<p><strong>initializeDefaultPreferences</strong>. This API was deprecated in Eclipse 
  3.0 as it is only fired if the compatibility layer is used. As most plug-ins 
  rely on AbstractUIPlugin#getPreferenceStore to get their preference store this 
  was being fired on plug-in start-up previously. If your plug-in does not access 
  the compatibility layer itself then this method may not be fired. It is recommended 
  that you create a <a href="../api/org/eclipse/core/runtime/preferences/AbstractPreferenceInitializer.html">
  <strong>org.eclipse.core.runtime.preferences.AbstractPreferenceInitializer</strong></a> 
  to handle your preference initialization.</p>

</body>
</html>