How to get UI controls into my plug-in ?

 

This chapter gives an overview about how you get UI controls into the workbench components.

The focus will be to fix the parent objects for UI controls which are provided with our UI Toolkit resources.

In detail, you will learn how to add UI controls

·         for a View component

·         for the Multipage Editor pages

·         a wizard page

·         a dialog window

 

 

Workbench View

A view is a visual component within a workbench page. It is used in a support role for the primary task. You use them to navigate a hierarchy of information, open an editor, or view properties for the active editor. The standard views in the workbench often display some information about an object that the user has selected or is navigating.

 

Appearance

 

 

A view can consists of such elements as:

·         a title bar

·         an action bar

·         an embedded control within the main pane.

The title bar contains an icon and a label, which both are predefined in the plugin.xml file. The final view label in the title bar can extend this prefixed label. That means you can add additional text to the view label in your java class.

The actions bar contains a local menu and the toolbar controls which are initially empty and invisible. They are become visible not until the view adds the items to the toolbar or to the menu.

 

 

View components

The package org.eclipse.ui and its sub packages contain the public interfaces that define the workbench UI API. Many of these interfaces have a default implementation that you can extend to provide your own view classes. The interface of interest is IViewPart, which defines the methods that must be implemented to contribute a new view to workbench. The class ViewPart provides a default implementation of this interface. The view part is responsible for creating UI controls needed to show the view.

 

How to add UI controls in a view component ?

 

To get visual components into a view you need to create a new view class which extends ViewPart and add your UI controls within the createPartControl method.– as is shown in the code fragment below.

 

 

package ui.sample.view;

 

import org.eclipse.ui.part.ViewPart;

import org.eclipse.swt.widgets.*;

import com.tssap.ide.util.ui.pane.*;

 

public class MySampleView extends ViewPart {

 

  // Constructor ...

 

  /**

   * This is a callback that will allow us

   * to create the viewer and initialize it.

   */

   public void createPartControl(Composite parent) {

      /*

       * Add UI controls here ...

       */

  }

  // Additional code

}

 

 

For further information about how you, as a plug-in developer, can add new views to the workbench look at the appropriate article from the Eclipse Corner.

 

 

Multipage editor

Just as any other editor, the multipage editor is a visual component within a workbench page and is used to edit or browse a file, document or other object.

 

Appearance

 

A multipage editor shows more than one page and uses tab controls for page activation.

As any other editor the multipage editor is labeled with the name of file, document or other object being edited.

All of the action implemented for the editor are available in the main window menu bar.

The use of multipage editor is demonstrated by the plugin file editor.

 

 

Components of the multipage editor

There are some components you always need when implementing a multipage editor:

The multipage editor class is responsible for creating and adding of the individual pages and for saving of editor contents. This class is normally a subclass of Workbench class org.eclipse.ui.part.MultiPageEditorPart.

A action bar contributor class is used to manage the contributions for all pages. The contributor must be a subclass of org.eclipse.ui.part.MultiPageEditorActionBarContributor and implements the action integration to the toolbar, to a menu or to a status bar.

 

How to add UI controls to Editor pages?

To get visual components into the individual pages you need to create a new multipage editor class which extends MultiPageEditorPart and add your UI controls within the appropriate createPage# methods.– as is shown in the code fragment below

 

package ui.sample.multipageeditor;

 

import org.eclipse.ui.part.MultiPageEditorPart;

import org.eclipse.swt.widgets.*;

import com.tssap.ide.util.ui.pane.*;

// ...

 

public class MySampleMultiPageEditor extends MultiPageEditorPart {

 

  // Constructor ...

  /**

   * Creates the pages of the multi-page editor.

   */

  protected void createPages() {

     createPage0();

     createPage1();

     createPage2();

     //...

  }

 

  void createPage0() {

      // Add UI controls for this page here ...

  }

 

  void createPage1() {

      // Add UI controls for this page here ...

  }

 

  //...

 

}

 

 

 

Wizard

In Eclipse, a wizard is commonly used for the creation of new resources, resource import, or resource export. It can also be used for the execution of any task involving a sequential series of steps. A wizard should be used if there are many steps in the task, and they must be completed in a specific order.

 

Appearance

 

 

Each wizard page consists of:

·         a page title

·         a header

·         an embedded control within the main pane.

·         standard buttons

A header which is at the top of each wizard page, contains a banner graphic and a text area. The banner graphic contains an image representing the wizard task, and should be created with a white to blue, gray scale palette for consistency with other banners in Eclipse. The text area is used to request the user for information which is absent, and display error messages if filled information is invalid.

The main pane displays the content of the individual page. You can implement the visual components using UI Toolkit resources.

At the bottom of a multi-page wizard, a Back, Next, Finish, and Cancel button should appear. (A single-page wizard shows the Finish and Cancel button only.)

 

 

Wizard components

A wizard is composed of several components:

The wizard dialog org.eclipse.jface.wizard.WizardDialog is the top level dialog in a wizard. It defines the standard buttons and manages a set of pages belonging to it. However, you don’t need to create a wizard dialog explicitly when you contribute to a workbench wizard extension.

The wizard class org.eclipse.jface.wizard.Wizard implements the overall appearance and many of details for standard wizard behavior. You normally extend this class to implement behavior specific for your wizard. Typically you create and add the pages to the wizard here, define the instruction text for the header or implement the activity that should occur when the user presses the Finish button.

The wizard page org.eclipse.jface.wizard.IWizardPage incorporates the UI controls which are used to implement the visual content of the page. The class WizardPage provides a default implementation of this interface. Your wizard pages typically extend this class.

 

How to add UI controls to a wizard page ?

To get visual components into a view you need to create a new wizard page class which extends WizardPage and add your UI controls within the createControl method.– as is shown in the code fragment below.

 

 

package ui.sample.wizard;

 

import org.eclipse.jface.wizard.WizardPage;

import org.eclipse.swt.widgets.*;

import com.tssap.ide.util.ui.pane.*;

 

public class MySampleWizardPage extends WizardPage {

 

  // Constructors ...

 

  public void createControl(Composite parent) {

      /*

       * Add UI controls here ...

       */

  }

  // Additional code

}

 

 

 

 

Dialog window

A dialog window enables a modal interaction with the user. It can be used to ask additional information, or just provide feedback.

Generally, you have two options to create a dialog window:

·         you use a standard dialog window

 

Appearance

 

 

 

Each dialog window consists of:

·         a title bar

·         a border area

The border area contains an embedded control which defines the content of the dialog page. The important part of these page are the interaction buttons.

Some standard dialog components display also an image representing the type of dialog (error message, confirmation popup, …).

 

 

Dialog components

Modal windows should have a parent object responsible for opening the dialog. The examples for this are actions resulting from a button or a menu item.

The dialog class is responsible for visual content of dialog window and furthermore implements the user interaction. If you define your own dialog component, you normally extend the org.eclipse.jface.dialogs.Dialog class.

 

How to add UI controls into the dialog page ?

To bring your own visual components into border area of a dialog page you need to create a new dialog class which extends org.eclipse.jface.dialogs.Dialog and add your UI controls within the createContents method.– as is shown in the code fragment below.

 

 

package ui.sample.popup;

 

import org.eclipse.jface.dialogs.Dialog;

import org.eclipse.swt.widgets.*;

import com.tssap.ide.util.ui.pane.*;

 

public class MyDialogPage extends Dialog {

 

  protected Control createContents(Composite parent) {

      /*

       * Add UI controls here ...

       */

  }

 

  // Additional code

 

}

 

 

 

Standard dialog components

There is a set of standard dialog components available in org.eclipse.jface.dialogs package. It offers such classes like ErrorDialog, MessageDialog, InputDialog or ProgressMonitorDialog.

 

 

If you are interested in Eclipse User Interface Guidelines see also the appropriate document from the Eclipse Corner.