org.eclipse.platform.doc.isv/porting/3.1/recommended.html
Parent Directory
| 
Revision Log
Revision 1.17 - (view) (download) (as text)
| 1 : | johna | 1.1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| 2 : | <html> | ||
| 3 : | |||
| 4 : | <head> | ||
| 5 : | tod | 1.5 | |
| 6 : | <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." > | ||
| 7 : | tod | 1.4 | |
| 8 : | johna | 1.1 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
| 9 : | <meta http-equiv="Content-Style-Type" content="text/css"> | ||
| 10 : | mvalenta | 1.11 | <link rel="STYLESHEET" href="../../book.css" charset="ISO-8859-1" type="text/css"> |
| 11 : | tod | 1.15 | <title>Changes required when adopting 3.1 mechanisms and APIs</title> |
| 12 : | johna | 1.1 | </head> |
| 13 : | |||
| 14 : | <body> | ||
| 15 : | |||
| 16 : | dmegert | 1.12 | <h2>Changes required when adopting 3.1 mechanisms and APIs</h2> |
| 17 : | <p>This section describes changes that are required if you are trying to change | ||
| 18 : | sfranklin | 1.7 | your 3.0 plug-in to adopt the 3.1 mechanisms and APIs.</p> |
| 19 : | johna | 1.2 | |
| 20 : | sfranklin | 1.6 | <h3>Platform undo/redo support</h3> |
| 21 : | <p> | ||
| 22 : | Eclipse 3.1 provides a new infrastructure for defining <b>undoable operations</b> and a shared | ||
| 23 : | <b>operation history</b> that keeps track of operations that have been executed, undone, and | ||
| 24 : | dmegert | 1.10 | redone. The various undo frameworks provided by add-on plug-ins should |
| 25 : | migrated over time to the platform operation support, so that clients of these frameworks | ||
| 26 : | sfranklin | 1.6 | can integrate more deeply with the platform and make their undoable operations available |
| 27 : | for undo in other plug-in views and editors. See the | ||
| 28 : | <a href="../../guide/wrkAdv_undo.htm">Undoable operations</a> documentation for basic | ||
| 29 : | information about adding undo support to a plug-in. Plug-ins that already define undo support | ||
| 30 : | dmegert | 1.10 | or use another framework can be migrated to the new undo support in a staged fashion, as |
| 31 : | sfranklin | 1.6 | described below.</p> |
| 32 : | <h4>Migrating plug-in specific operation (command) classes to IUndoableOperation</h4> | ||
| 33 : | <p>Plug-ins that already define classes describing their undoable operations should add | ||
| 34 : | an implementation for the interface <b>IUndoableOperation</b> to their operation/command | ||
| 35 : | classes. Plug-ins may still use older frameworks for managing the history (command stack) | ||
| 36 : | if necessary, but providing an interface for <b>IUndoableOperation</b> allows a plug-in's | ||
| 37 : | clients to use the same operations in the platform operations history, and to mix and match | ||
| 38 : | undoable operations from different plug-ins. This strategy is similar to that used by | ||
| 39 : | the SDK text editors to migrate to the new operations framework. If a direct mapping of | ||
| 40 : | the interface is not possible, wrappers can be used to map <b>IUndoableOperation</b> | ||
| 41 : | protocol to legacy undo objects. This strategy is used by the Platform/JDT | ||
| 42 : | refactoring support. Migration of the operation/command classes to <b>IUndoableOperation</b> | ||
| 43 : | is an important step because it allows the undoable operations from different frameworks | ||
| 44 : | to be utilized by other plug-ins without either plug-in having to migrate completely.</p> | ||
| 45 : | <h4>Migrating command stacks with IOperationHistory</h4> | ||
| 46 : | <p>Once undoable operations or commands are expressed in terms of <b>IUndoableOperation</b>, plug-ins | ||
| 47 : | that define an undo history (command stack) for keeping track of the undoable and redoable | ||
| 48 : | operations can migrate to the platform operations history by defining an <b>IUndoContext</b> | ||
| 49 : | that represents their undo history. Undo histories that were previously managed locally | ||
| 50 : | dmegert | 1.10 | can be merged into the common operation history by defining a unique |
| 51 : | undo context either for each part or for each model object, adding the appropriate undo context to each operation, and | ||
| 52 : | sfranklin | 1.6 | then adding the operation to the platform operation history. Undo histories with more |
| 53 : | global scope can be implemented by defining a unique undo context representing that undo scope, | ||
| 54 : | assigning that context to each operation, and then adding the operation to the platform | ||
| 55 : | operation history. See the | ||
| 56 : | <a href="../../guide/wrkAdv_undo.htm">Undoable operations</a> documentation for examples of | ||
| 57 : | creating undo contexts, assigning them, and adding operations to the platform operation history. | ||
| 58 : | </p> | ||
| 59 : | <h4>Defining undoable operations global to the workbench</h4> | ||
| 60 : | <p>Plug-ins that wish their operations to be undoable from workbench views such as the | ||
| 61 : | Navigator or Package Explorer should assign the workbench undo context to their operations. | ||
| 62 : | See the <a href="../../guide/wrkAdv_undo.htm">Undoable operations</a> documentation for more information | ||
| 63 : | about this undo context and how it can be retrieved by both workbench and headless plug-ins. | ||
| 64 : | </p> | ||
| 65 : | <h3>Platform undo/redo action handlers</h3> | ||
| 66 : | <p> | ||
| 67 : | Plug-ins that do not define an undo infrastructure or undoable operations, but wish to | ||
| 68 : | provide access to the platform's undo history, should consider retargeting the global | ||
| 69 : | undo and redo action handlers with the new common undo and redo action handlers. The action | ||
| 70 : | handlers should be assigned an undo context specifying which undo and redo history | ||
| 71 : | is to be shown. Plug-ins can use their locally defined undo contexts for showing "part-local" | ||
| 72 : | undo and redo history. The workbench undo context can be used for showing workbench-wide | ||
| 73 : | undo and redo history. Again, the | ||
| 74 : | <a href="../../guide/wrkAdv_undo.htm">Undoable operations</a> documentation | ||
| 75 : | has a complete example.</p> | ||
| 76 : | <h4>Migrating text operation actions to the common action handlers</h4> | ||
| 77 : | <p>Migrating text editor undo and redo actions is a bit different than simple retargeting | ||
| 78 : | of the global undo/redo action handlers. The <b>AbstractTextEditor</b> framework defines | ||
| 79 : | common text actions using a parameterized <b>TextOperationAction</b>. These actions are stored | ||
| 80 : | locally in the framework and used to dispatch various commands to an editor's text operation | ||
| 81 : | target. For text undo to work properly, the text editor framework relies on the presence | ||
| 82 : | of text operation actions with the proper id's (<tt>ITextEditorActionConstants.REDO</tt> | ||
| 83 : | and <tt>ITextEditorActionConstants.UNDO</tt>). | ||
| 84 : | </p> | ||
| 85 : | <p><b>AbstractTextEditor</b> has been migrated so that it creates the common action handlers, while | ||
| 86 : | still assigning them to the TextOperationAction table with their legacy id's. In this way, the | ||
| 87 : | sfranklin | 1.8 | new undo and redo action handlers can be retrieved using the legacy techniques for retrieving |
| 88 : | the action and performing an operation. Text editors in the <b>AbstractTextEditor</b> hierarchy | ||
| 89 : | will inherit this behavior. </p> | ||
| 90 : | <p>Editors that do not inherit this behavior from <b>AbstractTextEditor</b> should consider | ||
| 91 : | migrating any existing undo and redo actions to use the new handlers. Editors with | ||
| 92 : | legacy undo and redo TextOperationActions will still have working local undo support, since | ||
| 93 : | the JFace Text undo manager API used by these actions is still supported. However, the | ||
| 94 : | dmegert | 1.10 | undo and redo action labels will not be consistent with the new Eclipse SDK undo/redo actions, which show |
| 95 : | sfranklin | 1.8 | the name of the available undo or redo operation. To create the common undo and redo |
| 96 : | action handlers, the undo context used by the text viewer's undo manager should | ||
| 97 : | be used when creating the action handlers, and those handlers should be set into the | ||
| 98 : | sfranklin | 1.9 | editor using the appropriate <tt>ITextEditorActionConstants</tt> id. See |
| 99 : | sfranklin | 1.8 | <b><tt>AbstractTextEditor.createUndoRedoActions()</tt></b> and <b><tt>AbstractTextEditor.getUndoContext()</tt></b> |
| 100 : | for a detailed example. Editors that rely on an <b>EditorActionBarContributor</b> subclass to | ||
| 101 : | add to the action bars of their editors can use a similar technique by creating undo and redo action | ||
| 102 : | handlers and setting them when the active editor is set. </p> | ||
| 103 : | dejan | 1.14 | <h3>Help Enhancements</h3> |
| 104 : | <h4>Information Search</h4> | ||
| 105 : | <p>Plug-ins that contribute search pages into the <b>Search</b> dialog should | ||
| 106 : | consider porting all their information-style searches into federated search | ||
| 107 : | engines. Since 3.1, all information-style search is separated from the | ||
| 108 : | workbench-artifact search. Information search engines are run in parallel as | ||
| 109 : | background jobs and their results collated in the new Help view. See | ||
| 110 : | <a href="../../guide/help_search.htm">Help Search</a> for more details.</p> | ||
| 111 : | <h4>Dynamic help</h4> | ||
| 112 : | <p>The new dynamic help view will work with existing context IDs that are | ||
| 113 : | statically associated with widgets in workbench parts and dialogs. However, if | ||
| 114 : | you catch help event yourself and show help, dynamic help view will not be able | ||
| 115 : | to show anything useful. To fix the problem, you should adapt to the new <code> | ||
| 116 : | IContextProvider</code> interface as described in | ||
| 117 : | <a href="../../guide/help_context_dynamic.htm">Dynamic Context Help</a> | ||
| 118 : | document.</p> | ||
| 119 : | johna | 1.16 | |
| 120 : | johna | 1.17 | <h3><a name="PreferenceStore"></a>JFace Preference Stores</h3> |
| 121 : | johna | 1.16 | <p>As of release 3.1 the <a href="../api/org/eclipse/jface/preference/IPreferenceStore.html"> |
| 122 : | <strong>org.eclipse.jface.preference.IPreferenceStore</strong></a> | ||
| 123 : | that is returned from <b>AbstractUIPlugin.getPreferenceStore()</b> will be an instance | ||
| 124 : | of <strong><a href="../api/org/eclipse/ui/preferences/ScopedPreferenceStore.html"> | ||
| 125 : | org.eclipse.ui.preferences.ScopedPreferenceStore</a></strong>. | ||
| 126 : | The ScopedPreferenceStore uses the <b>org.eclipse.core.runtime.preferences</b> API to manage preferences. | ||
| 127 : | In 3.0 it used the compatibility layer to interface with an instance of <strong> | ||
| 128 : | <a href="../api/org/eclipse/core/runtime/Preferences.html">org.eclipse.core.runtime.Preferences</a></strong>.</p> | ||
| 129 : | <p>In 3.1 we have disambiguated IPreferenceStore to be more specific about the | ||
| 130 : | types of the values sent in preference changed events. The IPreferenceStore | ||
| 131 : | from AbstractUIPlugin#getPreferenceStore has the same behavior as before, | ||
| 132 : | but it is now specified more clearly.</p> | ||
| 133 : | <p><strong>Typing:</strong> <strong><a href="../api/org/eclipse/jface/util/IPropertyChangeListener.html"> | ||
| 134 : | org.eclipse.jface.util.IPropertyChangeListener</a></strong> | ||
| 135 : | added to an IPreferenceStore can potentially get two types of old and new values | ||
| 136 : | - typed or String representations. Any event generated by a call to a typed | ||
| 137 : | IPreferenceStore API (such as <code>setValue(String key, boolean value)</code> | ||
| 138 : | will generate a typed event. However it is also possible that events will be | ||
| 139 : | propagated from the core runtime preferences which generate an untyped event | ||
| 140 : | (for instance on a preference import). Property listeners need to be prepared | ||
| 141 : | for both. Note also that typed events will not be propagating primitive types | ||
| 142 : | so a call to <code>setValue(String key, boolean value)</code> will result in | ||
| 143 : | an event where the oldValue and newValue are Booleans.</p> | ||
| 144 : | <p><strong>putValue</strong>: IPreferenceStore.putValue(String key, String value) | ||
| 145 : | will not generate a change event. This API is meant to be used for private preferences | ||
| 146 : | that no listener would want to react to.</p> | ||
| 147 : | <p><strong>initializeDefaultPreferences</strong>. This API was deprecated in Eclipse | ||
| 148 : | 3.0 as it is only fired if the compatibility layer is used. As most plug-ins | ||
| 149 : | rely on AbstractUIPlugin#getPreferenceStore to get their preference store this | ||
| 150 : | was being fired on plug-in start-up previously. If your plug-in does not access | ||
| 151 : | the compatibility layer itself then this method may not be fired. It is recommended | ||
| 152 : | that you create a <a href="../api/org/eclipse/core/runtime/preferences/AbstractPreferenceInitializer.html"> | ||
| 153 : | <strong>org.eclipse.core.runtime.preferences.AbstractPreferenceInitializer</strong></a> | ||
| 154 : | to handle your preference initialization.</p> | ||
| 155 : | |||
| 156 : | johna | 1.1 | </body> |
| 157 : | </html> |
| help@eclipse.org | ViewVC Help |
| Powered by ViewVC 1.0.3 |