/plugins/ProjectViewer/tags/pv_2_1_3_7/projectviewer/action/package.html

# · HTML · 76 lines · 64 code · 12 blank · 0 comment · 0 complexity · da928c35f172a4e6398b04584ee6e799 MD5 · raw file 

    

  1. <body><h2>Creating custom actions.</h2>
    2. 

  2. 

  3. <p>ProjectViewer allows other plugin developers too interact with the file trees
    4. 

  4. by creating custom actions to be executed on the nodes. Actions can be added
    5. 

  5. to the tree's context menu or to the viewer's toolbar. It's recommended to
    6. 

  6. extend the context menu, since there's only so much useful space in the
    7. 

  7. toolbar for new actions.</p>
    8. 

  8. 

  9. <p>Creating a new action is very simple:</p>
    10. 

  10. 

  11. <ul>
    12. 

  12. <li>Create a new class that extends {@link projectviewer.action.Action Action}.</li>
    13. 

  13. <li>Implement the {@link projectviewer.action.Action#actionPerformed(ActionEvent)
    14. 

  14. 	actionPerformed()} method to execute the desired operations.</li>
    15. 

  15. <li>Register the action in the context menu
    16. 

  16. 	({@link projectviewer.vpt.VPTContextMenu#registerAction(Action) registerAction()})
    17. 

  17. 	or in the toolbar
    18. 

  18. 	({@link projectviewer.ProjectViewer#registerAction(Action) registerAction()})
    19. 

  19. 	by calling the appropriate method.</li>
    20. 

  20. </ul>
    21. 

  21. 

  22. <p>It's recommended to use the new API to register actions. Create the
    23. 

  23. following properties to automatically register actions with
    24. 

  24. ProjectViewer:</p>
    25. 

  25. 

  26. <ul>
    27. 

  27. 	<li>plugin.projectviewer.<i>class name</i>.toolbar-actions:<br>
    28. 

  28. 	list of classes that provide {@link projectviewer.action.Action Action}s that
    29. 

  29. 	will be added to the toolbar of the ProjectViewer dockable. One instance is
    30. 

  30. 	created for each class, and for each jEdit view the instance is cloned,
    31. 

  31. 	and then the "projectViewer" instance is set for the cloned object.</li>
    32. 

  32. 

  33. 	<li>plugin.projectviewer.<i>class name</i>.context-menu-actions:<br>
    34. 

  34. 	list of classes that provide {@link projectviewer.action.Action Action}s that
    35. 

  35. 	will be added to the tree's context menu. One instance is created for each
    36. 

  36. 	class, and for each jEdit view the instance is cloned, and then the
    37. 

  37. 	"projectViewer" instance is set for the cloned object.</li>
    38. 

  38. </ul>
    39. 

  39. 

  40. <p>The menu item show in the context menu is provided by the
    41. 

  41. {@link projectviewer.action.Action#getMenuItem() getMenuItem()} of the Action
    42. 

  42. class. Subclasses are welcome to override this method to provide other kinds
    43. 

  43. of menu items (a sub-menu, for example). For the toolbar button, the
    44. 

  44. {@link projectviewer.action.Action#getButton() getButton()} method is used.</p>
    45. 

  45. 

  46. <p>Before showing the menu item in the context menu, ProjectViewer will call
    47. 

  47. the {@link projectviewer.action.Action#prepareForNode(VPTNode) prepareForNode()}
    48. 

  48. method in all actions registered in the context menu. This allows each action to
    49. 

  49. decide if it should be shown for the given node and what message to show, for
    50. 

  50. example. For the toolbar buttons, this method is <b>never</b> called, so the
    51. 

  51. toolbar buttons should be able to be executed regardless of the current tree
    52. 

  52. selection. If your action depends on a certain kind of node, add it to the
    53. 

  53. context menu, and not to the toolbar. If you want to add it to the toolbar,
    54. 

  54. check for the node type in your <code>actionPerformed()</code> implementation.</p>
    55. 

  55. 

  56. <p>Another important thing to notice in the prepareForNode() method is that
    57. 

  57. the actions should check is the node is of a certain type, and not if the
    58. 

  58. node is not of a certain type. For example, use "node.isFile()" and not
    59. 

  59. "!node.isDirectory()". This ensures that the action will not do anything
    60. 

  60. wrong if a different node type is added in the future to PV, or if another
    61. 

  61. plugin adds a custom node type to PV.</p>
    62. 

  62. 

  63. <p>It's important to notice that the instance given to the <i>registerAction</i>
    64. 

  64. methods is not the instance used by the viewer instances. Those instances are
    65. 

  65. used as prototypes, and the viewers use {@link projectviewer.action.Action#clone()
    66. 

  66. clone()} to get instances for the specific viewer. After the cloning, the
    67. 

  67. {@link projectviewer.action.Action#setViewer(ProjectViewer) setViewer()} method
    68. 

  68. is called, so the actions have a reference to the viewers where they are being
    69. 

  69. used. This also means that you should not use the constructor of your Action
    70. 

  70. implementation to instantiate GUI components. Instantiations of GUI components
    71. 

  71. should be done lazily in the <code>getMenuItem()</code> or <code>getButton()</code>
    72. 

  72. methods. The default implementation already does this, so you should only worry
    73. 

  73. about this if you are overriding one of these methods.</p>
    74. 

  74. 

  75. </body>
    76.