Update and clean comments

git-svn-id: https://svn.argeo.org/commons/trunk@7319 4cfe0d0a-d680-48aa-b62c-e0a02a3f76cc

diff --git a/base/runtime/org.argeo.eclipse.ui/src/main/java/org/argeo/eclipse/ui/utils/CommandUtils.java b/base/runtime/org.argeo.eclipse.ui/src/main/java/org/argeo/eclipse/ui/utils/CommandUtils.java
index 51de673c8a842e3a2d34a92301d7787ac25bb8df..22a139f134aa565b119106ed292511d3693e29d5 100644 (file)
--- a/base/runtime/org.argeo.eclipse.ui/src/main/java/org/argeo/eclipse/ui/utils/CommandUtils.java
+++ b/base/runtime/org.argeo.eclipse.ui/src/main/java/org/argeo/eclipse/ui/utils/CommandUtils.java
@@ -38,83 +38,30 @@ import org.eclipse.ui.menus.CommandContributionItemParameter;
 import org.eclipse.ui.services.IServiceLocator;
 
 /**
- * Centralizes useful and generic methods concerning eclipse commands.
- * 
+ * Centralises useful and generic methods when dealing with commands in an
+ * Eclipse Workbench context
  */
 public class CommandUtils {
 
-       /**
-        * Factorizes command call that is quite verbose and always the same
-        * 
-        * NOTE that none of the parameter can be null
-        */
-       public static void CallCommandWithOneParameter(String commandId,
-                       String paramId, String paramValue) {
-               try {
-                       IWorkbench iw = ArgeoUiPlugin.getDefault().getWorkbench();
-
-                       IHandlerService handlerService = (IHandlerService) iw
-                                       .getService(IHandlerService.class);
-
-                       // get the command from plugin.xml
-                       IWorkbenchWindow window = iw.getActiveWorkbenchWindow();
-                       ICommandService cmdService = (ICommandService) window
-                                       .getService(ICommandService.class);
-
-                       Command cmd = cmdService.getCommand(commandId);
-
-                       ArrayList<Parameterization> parameters = new ArrayList<Parameterization>();
-
-                       // get the parameter
-                       IParameter iparam = cmd.getParameter(paramId);
-
-                       Parameterization params = new Parameterization(iparam, paramValue);
-                       parameters.add(params);
-
-                       // build the parameterized command
-                       ParameterizedCommand pc = new ParameterizedCommand(cmd,
-                                       parameters.toArray(new Parameterization[parameters.size()]));
-
-                       // execute the command
-                       handlerService = (IHandlerService) window
-                                       .getService(IHandlerService.class);
-                       handlerService.executeCommand(pc, null);
-               } catch (Exception e) {
-                       throw new ArgeoException("Error while calling command of id :"
-                                       + commandId, e);
-               }
-       }
-
        /**
         * Commodities the refresh of a single command with no parameter in a
         * Menu.aboutToShow method to simplify further development
         * 
+        * Note: that this method should be called with a false show command flag to
+        * remove a contribution that have been previously contributed
+        * 
         * @param menuManager
         * @param locator
         * @param cmdId
         * @param label
-        * @param iconPath
+        * @param icon
         * @param showCommand
         */
        public static void refreshCommand(IMenuManager menuManager,
                        IServiceLocator locator, String cmdId, String label,
                        ImageDescriptor icon, boolean showCommand) {
-               refreshParametrizedCommand(menuManager, locator, cmdId, label, icon,
-                               showCommand, null);
-       }
-
-       /**
-        * Commodities the refresh of a single command with a map of parameters in a
-        * Menu.aboutToShow method to simplify further development Rather use
-        * {@link refreshParameterizedCommand()}
-        */
-       @Deprecated
-       public static void refreshParametrizedCommand(IMenuManager menuManager,
-                       IServiceLocator locator, String cmdId, String label,
-                       ImageDescriptor icon, boolean showCommand,
-                       Map<String, String> params) {
                refreshParameterizedCommand(menuManager, locator, cmdId, label, icon,
-                               showCommand, params);
+                               showCommand, null);
        }
 
        /**
@@ -193,8 +140,8 @@ public class CommandUtils {
         * Helper to call a command with a map of parameters easily
         * 
         * @param paramMap
-        *            a map that links various commands ids with corresponding
-        *            String values.
+        *            a map that links various command IDs with corresponding String
+        *            values.
         */
        public static void callCommand(String commandID,
                        Map<String, String> paramMap) {
@@ -233,4 +180,59 @@ public class CommandUtils {
                                        + " calling the command " + commandID, e);
                }
        }
+
+       // legacy methods. Should be removed soon
+
+       /**
+        * Shortcut to call a command with a single parameter.
+        * 
+        * WARNING: none of the parameter can be null
+        * 
+        * @deprecated rather use <code>callCommand(commandID,parameterID,
+                       parameterValue)</code>
+        */
+       public static void CallCommandWithOneParameter(String commandId,
+                       String paramId, String paramValue) {
+               try {
+                       IWorkbench iw = ArgeoUiPlugin.getDefault().getWorkbench();
+                       IHandlerService handlerService = (IHandlerService) iw
+                                       .getService(IHandlerService.class);
+
+                       // Gets a command that must have been previously registered
+                       IWorkbenchWindow window = iw.getActiveWorkbenchWindow();
+                       ICommandService cmdService = (ICommandService) window
+                                       .getService(ICommandService.class);
+                       Command cmd = cmdService.getCommand(commandId);
+
+                       // Manages the single parameter
+                       ArrayList<Parameterization> parameters = new ArrayList<Parameterization>();
+                       IParameter iparam = cmd.getParameter(paramId);
+                       Parameterization params = new Parameterization(iparam, paramValue);
+                       parameters.add(params);
+
+                       // Create and execute the command
+                       ParameterizedCommand pc = new ParameterizedCommand(cmd,
+                                       parameters.toArray(new Parameterization[parameters.size()]));
+                       handlerService = (IHandlerService) window
+                                       .getService(IHandlerService.class);
+                       handlerService.executeCommand(pc, null);
+               } catch (Exception e) {
+                       throw new ArgeoException(
+                                       "Error calling command of id:" + commandId, e);
+               }
+       }
+
+       /**
+        * Commodities the refresh of a single command with a map of parameters in a
+        * Menu.aboutToShow method to simplify further development Rather use
+        * {@link refreshParameterizedCommand()}
+        */
+       @Deprecated
+       public static void refreshParametrizedCommand(IMenuManager menuManager,
+                       IServiceLocator locator, String cmdId, String label,
+                       ImageDescriptor icon, boolean showCommand,
+                       Map<String, String> params) {
+               refreshParameterizedCommand(menuManager, locator, cmdId, label, icon,
+                               showCommand, params);
+       }
 }
\ No newline at end of file