| <!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> |
| Retargetable actions |
| </TITLE> |
| |
| <link rel="stylesheet" type="text/css" HREF="../book.css"> |
| </HEAD> |
| <BODY BGCOLOR="#ffffff"> |
| <h2>Retargetable actions</h2> |
| <p>It is common for a plug-in's views and editors to implement actions that are |
| semantically similar to existing workbench actions, such as clipboard |
| cut/copy/paste, view refresh, or properties. The popup menu for views and |
| editors can become quite cluttered if every view or editor has to define unique |
| actions for these operations and include them in their menus. </p> |
| |
| |
| <p>To solve this problem, the workbench defines <b>retargetable</b> (also called |
| <b>global</b>) actions that can be handled by any view or editor. When a |
| view or editor is active, its handler will be run when the user chooses the |
| action from the workbench menu or toolbar. This allows views and editors |
| to share workbench menu space for semantically similar actions. </p> |
| |
| |
| <p><a href="../reference/api/org/eclipse/ui/IWorkbenchActionConstants.html"><b>IWorkbenchActionConstants</b></a> |
| documents all of the workbench actions and denotes retargetable actions as |
| global. For example, here is the definition of the <b>Properties</b> action.</p> |
| |
| |
| <pre>public static final String PROPERTIES = "properties"; // Global action. </pre> |
| |
| |
| <p>The following table summarizes some of the more common retargetable actions |
| that are implemented by views and editors:</p> |
| |
| |
| <table border="1" cellpadding="0" cellspacing="0" width="64%"> |
| <tr> |
| <td width="20%"> </td> |
| <td width="20%"><b>File menu</b></td> |
| <td width="20%"><b>Edit menu</b></td> |
| <td width="20%"><b>Navigate menu</b></td> |
| <td width="20%"><b>Project menu</b></td> |
| </tr> |
| <tr> |
| <td width="20%"><b>views</b></td> |
| <td width="20%">move<br> |
| rename<br> |
| refresh<br> |
| properties</td> |
| <td width="20%"> </td> |
| <td width="20%">go into<br> |
| go to resource<br> |
| sync with editor<br> |
| back<br> |
| forward<br> |
| up<br> |
| next<br> |
| previous</td> |
| <td width="20%">open<br> |
| close<br> |
| build<br> |
| rebuild</td> |
| </tr> |
| <tr> |
| <td width="20%"><b>editors</b></td> |
| <td width="20%">revert<br> |
| print</td> |
| <td width="20%">find</td> |
| <td width="20%"> </td> |
| <td width="20%"> </td> |
| </tr> |
| <tr> |
| <td width="20%"><b>views and editors</b></td> |
| <td width="20%"> </td> |
| <td width="20%">cut<br> |
| copy<br> |
| paste<br> |
| delete<br> |
| select all<br> |
| undo<br> |
| redo</td> |
| <td width="20%"> </td> |
| <td width="20%"> </td> |
| </tr> |
| </table> |
| <p>Retargetable actions are created using <b><a href="../reference/api/org/eclipse/ui/actions/RetargetAction.html">RetargetAction</a></b>. |
| The following snippet is from <b>WorkbenchActionBuilder</b>.</p> |
| |
| |
| <pre> propertiesAction = createGlobalAction(IWorkbenchActionConstants.PROPERTIES, "file", false); </pre> |
| |
| |
| <p>The <b> createGlobalAction</b> method shows us exactly how to make a <b><a href="../reference/api/org/eclipse/ui/actions/RetargetAction.html">RetargetAction</a></b>.</p> |
| |
| |
| <pre>private RetargetAction createGlobalAction(String id, String actionDefPrefix, boolean labelRetarget) { |
| RetargetAction action; |
| if (labelRetarget) { |
| action = new LabelRetargetAction(id, WorkbenchMessages.getString("Workbench." + id)); |
| } |
| else { |
| action = new RetargetAction(id, WorkbenchMessages.getString("Workbench." + id)); |
| } |
| ... |
| return action; |
| }</pre> |
| |
| <p>When creating a retargetable action, the workbench assigns the id for the |
| action and the default label. Note that there are two styles of retarget actions. <b><a href="../reference/api/org/eclipse/ui/actions/RetargetAction.html">RetargetAction</a> |
| </b>simply allows a view or editor to reimplement an action. <b><a href="../reference/api/org/eclipse/ui/actions/LabelRetargetAction.html">LabelRetargetAction</a> |
| </b>also allows views and editors to reset the label of the action. |
| This is useful for making the menu label more specific, such as relabeling an <b>Undo</b> |
| action as <b>Undo Typing</b>. </p> |
| |
| |
| <p>Now we know how the retarget actions are defined by the workbench. Let's look |
| next at how your view or editor can provide an implementation for a retargetable action. |
| This is done by <a href="wrkAdv_retarget_setting.htm">setting a global action |
| handler</a>.</p> |
| |
| |
| |
| </BODY> |
| </HTML> |
