In this section we’ll look at the standard components which ship with Eclipse. The Eclipse SDK contains a number of views, including the Navigator, Outline, Properties, Tasks, and Bookmarks view. Eclipse also contains a default text editor and a Resource perspective.
As a plug-in developer, you should try to add new actions to the existing parts. This leads to better integration with the platform, and the existing knowledge of the user.
|
Tip
|
Guideline 12.1 If appropriate, add actions to standard components of Eclipse using the plug-in registry. |
When extending the standard components such as the Navigator, Outline, Properties, Tasks, and Bookmark views, make sure your specialized components carry over the base component’s characteristics (drag and drop support, keyboard navigation, selection behaviour, etc.)
|
Tip
|
Guideline 12.2 If you subclass or copy any of the standard components, always carry over the standard components' characteristics. |
The Navigator is used to navigate the workspace, create new resources, modify resources, and open an editor on a resource. Plug-in developers may contribute new actions to the menu, toolbar, and context menu.
This is done by adding an extension to the plug-in registry.
|
Tip
|
Guideline 13.1 Add actions to the Navigator View menu, toolbar, and context menu using the plug-in registry. |
If object contributions are made to the context menu, try to qualify the target object as much as possible,
to avoid adding the command to the wrong objects in the Navigator.
For instance, a Java command may target Files with a .java extension, or IProjects with a Java nature.
It will cause confusion if Java actions appear on non-java objects.
Some actions are a reflection of tool use, rather than object type. For instance, a repository plug-in may provide actions for file check in, check out, etc. These actions should appear on the resources in the Navigator only if the user has actively chosen to use the repository tool. To control the visibility of these actions, the plug-in should apply a project nature to the managed resources, and use the project nature attribute in all context menu contributions.
For more information on command filtering, refer to Creating an Eclipse View.
The standard attributes for resources are defined in IResourceActionFilter.java (see below).
public interface IResourceActionFilter extends IActionFilter {
public static final String NAME = "name";
public static final String EXTENSION = "extension";
public static final String PATH = "path";
public static final String READ_ONLY = "readOnly";
public static final String PROJECT_NATURE = "projectNature";
}The standard attributes for project filtering are defined in IProjectActionFilter.java.
public interface IProjectActionFilter extends IResourceActionFilter {
public static final String NATURE = "nature";
public static final String OPEN = "open";
}In Eclipse, the use of a menu:Navigate[Show In] command is a common way to link the selection in one view to the input of another. For instance, a "Show in Package Explorer" command is visible in the context menu for a selected class in the source editor. When invoked, the class in the source editor is selected and revealed in the Package Explorer view. This approach should be used as a general, non intrusive pattern for view or editor linking. It is context sensitive, and reflects the intentions of the user.
A menu:Navigate[Show In Navigator] command should be included in any view where a resource may appear. If invoked, the command should select and reveal the resource in the navigator.
The Tasks view is used to display the current tasks, errors and warnings in the workspace. A plug-in developer may contribute new tasks, errors, and warnings to the workspace, and rely upon the Tasks view to display those objects. You can also contribute new actions to the menu, toolbar, and context menu. This is done by adding an extension to the plug-in registry.
A new task, error or warning can be created using the Marker Manager services from the Core Resources Management plugin.
|
Tip
|
Guideline 14.1 Add markers (tasks, errors and warnings) to the Tasks view using the Marker Manager services from the Core Resources Management plugin. |
The Tasks view is a table, containing columns for the task image, completion status, priority, description, resource, and line number. The description text of each marker should be short and concise, so that it will fit in the status line of Eclipse.
You can contribute new actions to the menu, toolbar, and context menu. This is done by adding an extension to the plug-in registry.
|
Tip
|
Guideline 14.3 Add actions to the Tasks view menu, toolbar, and context menu using the plug-in registry. |
If object contributions are made to the context menu, try to qualify the target object as much as possible,
to avoid adding the command to the wrong objects in the Tasks view.
At an implementation level, each object in the Tasks view is a marker,
a general mechanism for associate notes with a resource.
Use the attributes within IMarkerActionFilter.java to control the visibility of Task object actions (see below).
For more information on command filtering, refer to Creating an Eclipse View.
public interface IMarkerActionFilter extends IActionFilter {
public static final String TYPE = "type";
public static final String SUPER_TYPE = "superType";
public static final String PRIORITY = "priority";
public static final String SEVERITY = "severity";
public static final String DONE = "done";
public static final String MESSAGE = "message";
}In an editor, task objects are commonly used to mark a location within a document. Once a task has been created, it appears in the Task view. If this task is selected (via double clicking), you should reopen the editor at the location defined in the task. The focus should be changed from the Task view to the editor.
If appropriate, support for the creation of new task objects in an editor should be implemented by the editor. For more information on this, see Editors.
Plug-ins should support kbd:[F1] keyboard command and link it to an infopop that gives a detailed description of the selected item in the Task view.
When you want the user to select items from a given list of items, you can use the standard selection dialogs available in Eclipse.
Use
{ContainerSelectionDialog}[ContainerSelectionDialog]
when you want to select an IContainer (IFolder/IProject) from the workspace.
ContainerSelectionDialog dialog = new ContainerSelectionDialog(window.getShell(), null, true, "Select a parent:");
dialog.setTitle("Container Selection");
dialog.open();You can restrict the resource to be within a project/folder by passing the respective object as the second parameter for the constructor.
The ContainerSelectionDialog allowed you to select only one resource that too it should be a container.
If you want to select multiple resources including files,
then {ResourceSelectionDialog}[ResourceSelectionDialog] is the one you should be using.
ResourceSelectionDialog dialog = new ResourceSelectionDialog(window.getShell(), ResourcesPlugin.getWorkspace().getRoot(), "Select Resource:");
dialog.setTitle("Resource Selection");
dialog.open();The ResourceSelectionDialog is good when you want to present the entire set of resources under a parent and allow the user to select multiple resources.
But if you have a set of resources and want the user to select only one from that,
then probably you should be using {ResourceListSelectionDialog}[ResourceListSelectionDialog].
ResourceListSelectionDialog dialog = new ResourceListSelectionDialog(window.getShell(), resourcesArray);
dialog.setTitle("Resource Selection");
dialog.open();The above Dialogs are good to selecting workspace resources.
But what if I have some elements on my own and I want to select from that?
The first dialog you would be using is {ElementListSelectionDialog}[ElementListSelectionDialog].
The user can select an element from the set.
You have to pass the elements as an array and supply a label provider to render the element.
The user can filter using wildcards as well.
ElementListSelectionDialog dialog = new ElementListSelectionDialog(window.getShell(), new LabelProvider());
dialog.setTitle("String Selection");
dialog.setMessage("Select a String (* = any string, ? = any char):");
dialog.setElements(new Object[] { "one", "two", "three" });
dialog.open();If you want the user to select multiple elements from the given set,
then {ListSelectionDialog}[ListSelectionDialog] is the one to use.
It is basically a single column TableViewer with SWT.CHECK style applied.
You have to supply your own ContentProvider and LabelProvider for the TableViewer.
It also has btn:[Select All] and btn:[Deselect All] buttons.
ListSelectionDialog dlg = new ListSelectionDialog(window.getShell(), getInput(), getContentProvider(), getLabelProvider(), "Select the Element:");
dlg.setTitle("Element Selection");
dlg.open();If you have your items in a tree structure and want to select few elements from them,
then {CheckedTreeSelectionDialog}[CheckedTreeSelectionDialog] is your choice.
You have to bring your own content and label provider and the input.
CheckedTreeSelectionDialog dialog = new CheckedTreeSelectionDialog(window.getShell(), getLabelProvider(), getContentProvider());
dialog.setTitle("Tree Selection");
dialog.setMessage("Select the elements from the tree:");
dialog.setInput(getInput());
dialog.open();{ElementTreeSelectionDialog}[ElementTreeSelectionDialog] is the same as the CheckedTreeSelectionDialog
except that it will allow you to select a single element in the whole tree rather than multiple elements.
ElementTreeSelectionDialog dialog = new ElementTreeSelectionDialog(window.getShell(), getLabelProvider(), getContentProvider());
dialog.setTitle("Tree Selection");
dialog.setMessage("Select the elements from the tree:");
dialog.setInput(getInput());
dialog.open();Have you used the Open Type (kbd:[Ctrl + Shift + T]) or Open Resource (kbd:[Ctrl + Shift + R]) dialog?
It’s similar to the ElementListSelectionDialog, but it has more features.
It can select multiple items, display a detail pane about the item that is currently selected,
it can even remember your previous selections;
store them in history and present them before the other choices.
To have that functionality, you have to extend the abstract class {FilteredItemsSelectionDialog}[FilteredItemsSelectionDialog] and provide the necessary implementation.
The Preference Dialog is used to edit the global preference for a feature in the workbench.
A new preference page should be created when you need to expose global options to the user. For instance, the global preferences for Java compilation are exposed as a group of preference pages in the Preference Dialog. If these preferences are changed, they affect the entire Java plug-in.
A preference page should not be used to expose the local options for a particular instance of a view, editor, or window. In this situation, the user will look to the menu and toolbar of the control itself to customize it. If these options are exposed in the Preference Dialog, it will blur the location of customization, and confuse the user.
|
Tip
|
Guideline 15.2 Expose the preferences for a particular view, editor or window in the view itself, via a menu or tool item. |
In the simplest case, any plug-in which needs to expose an option to the user will define a single preference page. This preference page should contain all of the options for the plug-in, until the number of options starts to overload the page. At that point a nested design for preference pages should be adopted.
In a nested design, a root preference page is added to the preference dialog, and then sub pages are added to the root preference page. The root preference page should never be blank. Instead, it should contain the most commonly used preferences, or those preferences which have a wide spread effect upon the plug-in behavior. Beneath the root page, a sub page should be created for each major chunk of functionality within the plug-in.
There is no reason to set the focus in a preference page, because focus is always set to the tree, by the Eclipse platform, after the preference page is made visible.
Each new plug-in should integrate its plug-in preferences, wizards, and views into existing preference, wizard, and view categories where it makes sense, rather than the blind creation of new categories for itself.
In Eclipse, there is a special relationship between an editor and the Outline view. When an editor is opened, the Outline view will connect to the editor, and ask it for an outline model. If the editor answers an outline model, that model will be displayed in the Outline view whenever the editor is active. The outline is used to navigate through the edit data, or interact with the edit data at a higher level of abstraction.
If you are an editor developer, the relationship between an editor and the Outline view is important. For more information on the collaboration between these two, see Editors.
The Properties view shows the properties for the active part in the workbench, or the selection within that part. These properties are supplied by the active part itself. The Properties view is simply a container for their presentation.
Within Eclipse, the properties for an object can be exposed using a Properties dialog, or the Properties view. The Properties view is commonly used to edit the properties for a set of objects in an editor, where quick access to the properties is important, and you switch from one object to another quickly.
For more information on the use of the Properties view, or Properties dialog, refer to Properties.
The Bookmarks view is used to bookmark files, and open them quickly. A plug-in developer may contribute new bookmarks to the workspace, and rely upon the Bookmarks view to display those bookmarks. You can also contribute new actions to the menu, toolbar, and context menu. This is done by adding an extension to the plug-in registry.
In an editor, bookmark objects are commonly used to mark a location within a document. Once a bookmark has been created, it appears in the Bookmarks view. If this bookmark is selected, you may reopen the editor at the location defined in the bookmark.
If appropriate, support for the creation of new bookmark objects should be implemented by the editor. For more information on this, see Editors.
The Text Editor is commonly used to edit text files. A plug-in developer can contribute new actions to the menu, toolbar, and context menu. This is done by adding an extension to the plug-in registry. For more information on this, see Editors.
The Resource perspective contains a Navigator, Outline, Task view, and editor area. Plug-in developers may contribute a new command, action set, or view to the Resource perspective. For more information, refer to Perspectives.