Instantiating parts

All interaction with a part happens through an ISite. From the point of view of someone creating a part, the ISite is the part. An ISite can either be created from an IPartFactory or by directly instantiating the Site class.

To destroy a part, dispose the control for its ISite.

Instantiating parts using IPartFactory

Views and editors are normally created using an IPartFactory and IPartFactory can only create parts registered with the views or editors extension point. . Parts created by IPartFactory depend on an IWorkbenchPage and cannot outlive the IWorkbenchPage. IPartFactory creates parts by ID and the part's implementation class does not need to be API. An IPartFactory can be obtained from IWorkbenchPage. Parts can also take an IPartFactory in their constructor to create nested children.

This example demonstrates how to create a view using IPartFactory.

/**
 * Used to create instances of editors and views.
 *
 * @since 3.1
 */
public interface IPartFactory {
    /**
     * Creates an instance of a view. Returns an <code>ISite</code> for the newly created view.
     * When the caller is done with the part it should dispose the part's main control. This can
     * be accomplished by calling <code>ISite.getControl().dispose()</code>, or by disposing the
     * parent composite.
     *
     * @param viewId ID of the view, as registered with the org.eclipse.ui.views extension point
     * @param parentComposite parent composite for the view. If the view is successfully created, it
     *        will create exactly one new child control in this composite.
     * @param context local context for the view. This object can override any or all of the view's dependencies.
     *        If the view has a dependency that isn't found in the local context, a default implementation will
     *        be supplied by the org.eclipse.core.component.types extension point.
     * @param savedState previously saved state of the part, or null if none
     * @return an ISite for the newly created view
     * @throws CoreException if unable to create the part
     */
    public ISite createView(String viewId, Composite parentComposite, IContainerContext context, IMemento savedState) throws CoreException;
   
    /**
     * Creates an instance of an editor. Returns an <code>ISite</code> for the newly created editor.
     * When the caller is done with the part it should dispose the part's main control. This can
     * be accomplished by calling <code>ISite.getControl().dispose()</code>, or by disposing the
     * parent composite.
     *
     * @param editorId ID of the editor, as registered with the org.eclipse.ui.editors extension point
     * @param parentComposite parent composite for the editor. If the editor is successfully created,
     *        it will create exactly one new child control in this composite.
     * @param context local context for the editor. This object can override any or all of the part's dependencies.
     *        If the part has a dependency that isn't found in the local context, a default implementation will
     *        be supplied by the org.eclipse.core.component.types extension point.
     * @param input IEditorInput for this editor
     * @param savedState previously saved state for the part, or null if none
     * @return an ISite for the newly created editor
     * @throws CoreException if unable to create the part
     */
    public ISite createEditor(String editorId, Composite parentComposite, IContainerContext context, IEditorInput input, IMemento savedState) throws CoreException;
}


Here is an example of an action that creates a view using IPartFactory

/**
 * Demonstrate how to open a view by its ID from an IWorkbenchPage.
 */
public class CreateViewByIdAction implements IWorkbenchWindowActionDelegate {
    private IWorkbenchWindow window;

    public void run(IAction action) {       
        IWorkbenchPage page = window.getActivePage();
       
        if (page == null) {
           
// ...uninteresting error-handling code removed...
            return;
        }
       
        final Shell tempShell = new Shell(window.getShell(), SWT.DIALOG_TRIM | SWT.RESIZE);
       
        tempShell.setLayout(new FillLayout());
        tempShell.setText("Problems");
       
        IPartFactory factory = page.getPartFactory();
        try {
            factory.createView(IPageLayout.ID_PROBLEM_VIEW, tempShell, new ContainerContext(), null);
        } catch (CoreException e) {
           
// ...uninteresting error-handling code removed...
        }
       
        // Open the dialog
        tempShell.open();
        Display d = tempShell.getDisplay();
        while (!tempShell.isDisposed()) {
            if (!d.readAndDispatch())
                d.sleep();
        }
       
    }

    public void init(IWorkbenchWindow window) {
        this.window = window;
    }

    // ...remaining (empty) methods removed...
}

Instantiating parts using the Site class

Not all parts are views or editors. Clients can also use the part API to create their own reusable components. Such parts are not registered with the view or editor extension points, but can make use of most of the API available to views and editors. Although there is nothing stopping clients from inventing their own API for reusable components, making use of the part pattern allows their components to be embedded inside anything that supports embedding of views or editors.

Parts created using the Site class have the following properties: The Site constructor must be given the part's implementation class and the associated plugin bundle. The plugin bundle determines where log error messages will be logged and where the part should search when looking for resources in its own plugin.

The following example demonstrates how to use the Site class to instantiate a part directly. In this example, we instantiate the NameTestView part in a dialog. Although NameTestView is called a view and can make use of the view API, it doesn't actually need to be registered with the org.eclipse.ui.views extension point unless the workbench is actually supposed to use it as a view.


/**
 * Demonstrate how to open a part programmatically using the Site class.
 */
public class ProgrammaticViewCreationExampleAction implements IWorkbenchWindowActionDelegate {
    private IWorkbenchWindow window;

    public void run(IAction action) {       
        // Create a shell
        final Shell tempShell = new Shell(window.getShell(), SWT.DIALOG_TRIM | SWT.RESIZE);
        tempShell.setLayout(new FillLayout());
        tempShell.setText("Name test view");
       
        Bundle thisPlugin = ComponentExamplesPlugin.getDefault().getBundle();
       
        try {
            // Instantiate the NameTestView part (this line is the whole point of the example)
            // It demonstrates how the Site class can be used instead of calling NameTestView's constructor.
            Site testPart = new Site(tempShell, new ContainerContext(),
                    thisPlugin,
                    NameTestView.class);           
           
        } catch (CoreException e) {
            // ...uninteresting error-handling code removed...
        }
       
        // Open a modal dialog
        tempShell.open();
        Display d = tempShell.getDisplay();
        while (!tempShell.isDisposed()) {
            if (!d.readAndDispatch())
                d.sleep();
        }
       
    }
\
    public void init(IWorkbenchWindow window) {
        this.window = window;
    }

   
// ...remaining (empty) methods removed...
}