Configuring Custom Commands

StartExplorer can be extended and customized by the user by custom commands. Custom commands are sent to the command line so your custom commands can do anything that you can do from the command line.

You can add as many custom commands as you want. Custom commands will be shown in a sub menu of StartExplorer's context menus.

Configuring Custom Commands

Go to Window - Preferences - StartExplorer - Custom Commands to access StartExplorer's preference page. The upper area of the preference page is used to configure custom commands. The table shows you all configured custom commands. By default, there are already two custom commands (Notepad and UltraEdit). The buttons to the right of the table allow you to

• Add new custom commands,
• Edit existing custom commands,
• Remove existing custom commands and
• reorder the custom commands by moving individual commands Up and Down.

• Command: Enter the command to run. The command will be run via java.lang.Runtime.exec, that is, it will be executed as if you had entered the command on the command line.
  Example command: notepad ${resource_path}
  This opens the selected file(s) in Notepad (notepad.exe needs to be on the system path). ${resource_path} is a variable that will be replaced with the selected resouce's absolute path when the command is executed.
• Enabled for resources: If this option is checked, the custom command will appear in the context menu for resource views (Navigator, Package Explorer, etc.). If the option is unchecked, the custom command will not be shown in this context menu (useful if you only want to use this custom command for selected text regions in editors).
• Name for resources menu: The name which is shown in the context menu for resource views.
• Enabled for text selections: If this option is checked, the custom command will appear in the context menu for selected text regions in editors. If the option is unchecked, the custom command will not be shown in this context menu (useful if you only want to use this custom command in resource views).
• Name for text selection menu:The name which shown in the context menu for selected text regions in editors.
• Resource Type: You can configure the resource type a custom command is intended for, either "Files", "Folders" or "Files & Folders". If a custom command that is intended for files is execute on a directory, a dialog box with an error message is shown and no action is taken. If, on the other hand, a custom command intended for a folder is executed on a file, the command automatically uses the parent directory. Finally, for a custom command that is intended for files & folders, no such check is executed before invoking the command.
• Pass selected text to application: This changes the behaviour for the custom command when it is executed from within an editor for a selected text region. By default - when this option is not checked - the selected text will be interpreted as a filesystem path (denoting a file or a folder) and the custom command will be executed for this resource. If this option is checked the selected text will be passed to the command. StartExplorer will create a temp file which contains the selected text and calls the custom command with that temp file. To be precise: All supported variables will be substituted based on this temp file. You almost always will want to use the ${resource_path} variable for this use case.
  Example: To pass the selected text to your favourite editor, say Notepad (although I doubt that this is your favourite editor), you could configure the command like this:
  • Command: notepad ${resource_path}
  • Enabled for resources: No
  • Name for resources menu: leave this text field blank
  • Enabled for text selections: Yes
  • Name for text selection menu: Copy to Notepad
  • Pass selected text to application: Yes
• Save as:
  • Local (Preference Store): By default, custom commands are stored together with all other options in the Eclipse preferences.
  • Shared File: It is also possible to store a custom command definition as a file in one of your projects. This makes it possible to share custom commands in a version control system, for example to share them with your team. Custom commands stored as shared files will be imported automatically on Eclipse startup (or, to be more precise, when the StartExplorer plug-in is activated).

The export button let's you export the command definition to the file system, see Importing and exporting custom commands.

Edit an existing custom command

Select an existing custom command in the table and click the Edit button or simply double click a custom command. You can configure the new custom command in the following dialog. The dialog is exactly the same as for adding new custom commands.

Remove an existing custom command

Select an existing custom command in the table and click the Remove button to delete custom commands.

Reorder the custom commands

Select an existing custom command in the table and use the buttons Up and Down to change the order in which the custom commands appear in the context menu.

Importing and exporting custom commands

Command definitions can be exported to the file system. The dialog to edit a custom command offers an Export button. Click the button and choose a file to export the command. It will be stored as a *.startexplorer file, the format used internally is JSON. Commands that have been exported like that can be imported with the Import button on the preference page for custom commands. After importing a custom command it will be added to the end of the list. This feature makes it possible to share command definitions with other people.

Variables

StartExplorer supports is now integrated with the standard Eclipse mechanism and thus support all variables that are defined in your Eclipse installation/workspace. This includes well known variables like workspace_loc project_loc, but generally every variable that is defined, either by Eclipse or by any installed plug-in or that has been added manually (for example via Preferences -> Run/Debug -> String Substitution) can be used in custom command definitions and the command definitions for and custom desktop environments. Variables that take arguments are also supported. The content assist functionality in the preference pages will show all available variables.

For example, in my workspace, the following variables are supported:

• ${project_path}: Returns the workspace relative path of a resource's project. The target resource is the selected resource when no argument is specified, or the resource identified by a workspace relative path.
• ${project_name}: Returns the name of a resource's project. The target resource is the selected resource when no argument is specified, or the resource identified by a workspace relative path.
• ${project_loc}: Returns the absolute file system path of a resource's project. The target resource is the selected resource when no argument is specified, or the resource identified by a workspace relative path.
• ${system_path}: Returns the absolute file system path of the external tool. Resolved by finding the first occurrence of the named tool based on the system path specification. The tool name must be supplied as an argument.
• ${env_var}: Returns the value of an environment variable. An environment variable name must be specified as an argument.
• ${build_type}: Returns the type of build being performed - "incremental", "full", "auto", or "none".
• ${build_project}: Returns the absolute file system path of the project currently being built, or the absolute file system path of the resource identified by an optional argument interpreted as a path relative to the project currently being built.
• ${container_name}: Returns the name of a resource's container. The target resource is the selected resource when no argument is specified, or the resource identified by a workspace relative path.
• ${build_files}: Returns the set of absolute file system paths whose modification caused the current build. A list of the characters, 'a' (added), 'c' (changed), 'r' (removed), 'f' (files only), 'd' (directories only), can be supplied as an argument to limit the file list to just those types of deltas. Defaults to all deltas.
• ${selected_text}: Returns the text currently selected in the active editor.
• ${java_type_name}: Returns the fully qualified Java type name of the primary type in the selected resource.
• ${selected_resource_name}: Returns the name of the selected resource.
• ${selected_resource_path}: Returns the workspace relative path of the selected resource.
• ${container_path}: Returns the workspace relative path of a resource's container. The target resource is the selected resource when no argument is specified, or the resource identified by a workspace relative path.
• ${container_loc}: Returns the absolute file system path of a resource's container. The target resource is the selected resource when no argument is specified, or the resource identified by a workspace relative path.
• ${eclipse_home}: The location of the base installation for the running platform
• ${resource_path}: Returns the workspace relative path of a resource. The target resource is the selected resource when no argument is specified, or the resource identified by a workspace relative path.
• ${file_prompt}: Returns the absolute file system path of a file chosen in a file selection dialog. When one argument is provided, it is used a prompt hint on the dialog title. When a second argument is provided, it is used as an initial value for the file selection dialog. The first and second arguments must be separated with a ':'.
• ${resource_loc}: Returns the absolute file system path of a resource. The target resource is the selected resource when no argument is specified, or the resource identified by a workspace relative path.
• ${java_extensions_regex}: Regular expression matching registered Java-like file extensions
• ${system_property}: Returns the value of a system property from the Eclipse runtime. A system property name must be specified as an argument.
• ${project_classpath}: Returns the resolved class path of a project. A project name can be provided as an argument. If no argument is provided, the target project is the project of the selected resource.
• ${ee_home}: Returns the absolute file system path of the JRE home directory corresponding to the specified execution environment. An execution environment identifier must be provided as an argument.
• ${system}: Returns the value of an Eclipse system variable. A variable name must be specified as an argument - one of ARCH, ECLIPSE_HOME, NL, OS, or WS.
• ${workspace_loc}: Returns the absolute file system path of the workspace root. When an argument is specified, the absolute file system path of the resource identified by a workspace relative path is returned.
• ${folder_prompt}: Returns the absolute file system path of a directory chosen in a directory selection dialog. When one argument is provided, it is used a prompt hint on the dialog title. When a second argument is provided, it is used as an initial value for the directory selection dialog. The first and second arguments must be separated with a ':'.
• ${resource_name}: Returns the name of a resource. The target resource is the selected resource when no argument is specified, or the resource identified by a workspace relative path.
• ${string_prompt}: Returns the text value entered into a prompt dialog. When one argument is provided, it is used as a prompt hint on the input dialog. When a second argument is provided, it is used as an initial value in the input dialog. The first and second arguments must be separated with a ':'.
• ${selected_resource_loc}: Returns the absolute file system path of the selected resource.
• ${password_prompt}: Returns the text value entered into a password prompt dialog. When one argument is provided, it is used as a prompt hint on the input dialog. When a second argument is provided, it is used as an initial value in the input dialog. The first and second arguments must be separated with a ':'.

In addition, StartExplorer itself offers a few variables of its own. For the examples, let the full path of the resource be C:\path\to\resource.txt

1. ${resource_path}: Absolute path to selected resource (that is, C:\path\to\resource.txt))
2. ${resource_name}: File name or directory name of the resource, without path (that is, resource.txt)
3. ${resource_parent}: Absolute path to parent of selected resource (that is, C:\path\to)
4. ${resource_name_without_extension}: File name or directory name of the resource, without path and without extension (that is, resource, without trailing dot)
5. ${resource_extension}: Only the file's extension (that is, txt, without leading dot)

The text field for the command also provides content assist. If you press CTRL + Space or if you type '$' (and wait a second) the available variables will be listed, together with a short explanation.

Custom Commmands Compared to External Tools

Custom Commands are similar to External Tools, which are available in Eclipse without the StartExplorer plug-in. Here are the main differences:

• External Tools offer a lot more variables to use for your command (StartExplorer may offer more variables in future versions, who knows?)
• External Tools have significant longer startup times. Custom Commands are executed much faster. This is because External Tools are launched in a JVM of their own by default. Thus you have the JVM startup time plus the time the command needs to execute. StartExplorer Custom Commands are always launched in the same JVM as Eclipse, thus they start faster
• External Tools ignore selections of multiple resources. The external tool is only launched with the first selected resource. StartExplorer launches its commands on all selected resources.