org.eclipse.ui.part.IntroPart Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of workbench Show documentation
This plug-in contains the bulk of the Workbench implementation, and depends on JFace, SWT, and Core Runtime. It cannot be used independently from org.eclipse.ui. Workbench client plug-ins should not depend directly on this plug-in.
The newest version!
/*******************************************************************************
 * Copyright (c) 2004, 2006 IBM Corporation and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.ui.part;

import org.eclipse.core.commands.common.EventManager;
import org.eclipse.core.runtime.Assert;
import org.eclipse.core.runtime.IConfigurationElement;
import org.eclipse.core.runtime.IExecutableExtension;
import org.eclipse.core.runtime.Platform;
import org.eclipse.jface.resource.ImageDescriptor;
import org.eclipse.jface.resource.JFaceResources;
import org.eclipse.jface.util.SafeRunnable;
import org.eclipse.swt.graphics.Image;
import org.eclipse.swt.widgets.Composite;
import org.eclipse.ui.IMemento;
import org.eclipse.ui.IPropertyListener;
import org.eclipse.ui.ISharedImages;
import org.eclipse.ui.PartInitException;
import org.eclipse.ui.PlatformUI;
import org.eclipse.ui.internal.intro.IntroMessages;
import org.eclipse.ui.internal.registry.IWorkbenchRegistryConstants;
import org.eclipse.ui.internal.util.Util;
import org.eclipse.ui.intro.IIntroPart;
import org.eclipse.ui.intro.IIntroSite;
import org.eclipse.ui.plugin.AbstractUIPlugin;

/**
 * Abstract base implementation of an intro part.
 * 
 * Subclasses must implement the following methods:
 * 

 * createPartControl- to create the intro part's controls
 * 
 * setFocus- to accept focus
 * standbyStateChanged- to change the standby mode
 * 
 * 
 * 
 * Subclasses may extend or reimplement the following methods as required:
 * 

 * setInitializationData- extend to provide additional
 * initialization when the intro extension is instantiated
 * init(IIntroSite, IMemento)- extend to provide additional
 * initialization when intro is assigned its site
 * dispose- extend to provide additional cleanup
 * getAdapter- reimplement to make their intro adaptable
 * 
 * 
 * 
 * @since 3.0
 */
public abstract class IntroPart extends EventManager implements IIntroPart,
		IExecutableExtension {

    private IConfigurationElement configElement;

    private ImageDescriptor imageDescriptor;

    private IIntroSite partSite;

    private Image titleImage;

	private String titleLabel;

    /**
     * Creates a new intro part.
     */
    protected IntroPart() {
        super();
    }

    /* (non-Javadoc)
     * @see org.eclipse.ui.intro.IIntroPart#addPropertyListener(org.eclipse.ui.IPropertyListener)
     */
    public void addPropertyListener(IPropertyListener l) {
        addListenerObject(l);
    }

    /*
     * (non-Javadoc) Creates the SWT controls for this intro part. 
     * Subclasses must implement this method. For a detailed description of the
     * requirements see  IIntroPart 
     * 
     * @param parent the parent control
     * 
     * @see IIntroPart
     */
    public abstract void createPartControl(Composite parent);

    /**
     * The IntroPart implementation of this
     * IIntroPart method disposes the title image loaded by
     * setInitializationData. Subclasses may extend.
     */
    public void dispose() {
        if (titleImage != null) {
            JFaceResources.getResources().destroyImage(imageDescriptor);
            titleImage = null;
        }

        // Clear out the property change listeners as we
        // should not be notifying anyone after the part
        // has been disposed.
        clearListeners();
    }

    /**
     * Fires a property changed event.
     * 
     * @param propertyId
     *            the id of the property that changed
     */
    protected void firePropertyChange(final int propertyId) {
        Object[] array = getListeners();
        for (int nX = 0; nX < array.length; nX++) {
            final IPropertyListener l = (IPropertyListener) array[nX];
            Platform.run(new SafeRunnable() {

                public void run() {
                    l.propertyChanged(this, propertyId);
                }
            });
        }
    }

    /**
     * This implementation of the method declared by IAdaptable
     * passes the request along to the platform's adapter manager; roughly
     * Platform.getAdapterManager().getAdapter(this, adapter).
     * Subclasses may override this method (however, if they do so, they should
     * invoke the method on their superclass to ensure that the Platform's
     * adapter manager is consulted).
     */
    public Object getAdapter(Class adapter) {
        return Platform.getAdapterManager().getAdapter(this, adapter);
    }

    /**
     * Returns the configuration element for this part. The configuration
     * element comes from the plug-in registry entry for the extension defining
     * this part.
     * 
     * @return the configuration element for this part
     */
    protected IConfigurationElement getConfigurationElement() {
        return configElement;
    }

    /**
     * Returns the default title image.
     * 
     * @return the default image
     */
    protected Image getDefaultImage() {
        return PlatformUI.getWorkbench().getSharedImages().getImage(
                ISharedImages.IMG_DEF_VIEW);
    }

    /*
     * (non-Javadoc)
     * 
     * @see org.eclipse.ui.intro.IIntroPart#getIntroSite()
     */
    public final IIntroSite getIntroSite() {
        return partSite;
    }

    /* (non-Javadoc)
     * @see org.eclipse.ui.intro.IIntroPart#getTitleImage()
     */
    public Image getTitleImage() {
        if (titleImage != null) {
            return titleImage;
        }
        return getDefaultImage();
    }
    
    /* (non-Javadoc)
     * @see org.eclipse.ui.intro.IIntroPart#getTitle()
     */
    public String getTitle() {
    	if (titleLabel != null) {
    		return titleLabel;
    	}
    	return getDefaultTitle();
    }

    /**
     * Return the default title string.
     * 
	 * @return the default title string
	 */
	private String getDefaultTitle() {
		return IntroMessages.Intro_default_title;
	}

	/**
     * The base implementation of this {@link org.eclipse.ui.intro.IIntroPart}method ignores the
     * memento and initializes the part in a fresh state. Subclasses may extend
     * to perform any state restoration, but must call the super method.
     * 
     * @param site
     *            the intro site
     * @param memento
     *            the intro part state or null if there is no
     *            previous saved state
     * @exception PartInitException
     *                if this part was not initialized successfully
     */
    public void init(IIntroSite site, IMemento memento)
            throws PartInitException {
        setSite(site);
    }

    /**
     * Sets the part site.
     * 
     * Subclasses must invoke this method from {@link org.eclipse.ui.intro.IIntroPart#init(IIntroSite, IMemento)}.
     * 
     *
     * @param site the intro part site
     */
    protected void setSite(IIntroSite site) {
        this.partSite = site;
    }

    /* (non-Javadoc)
     * @see org.eclipse.ui.intro.IIntroPart#removePropertyListener(org.eclipse.ui.IPropertyListener)
     */
    public void removePropertyListener(IPropertyListener l) {
        removeListenerObject(l);
    }

    /**
     * The base implementation of this {@link org.eclipse.ui.intro.IIntroPart} method does nothing.
     * Subclasses may override.
     * 
     * @param memento
     *            a memento to receive the object state
     */
    public void saveState(IMemento memento) {
        //no-op
    }

    /*
     * (non-Javadoc) Asks this part to take focus within the workbench. 
     * 
     * Subclasses must implement this method. For a detailed description of the
     * requirements see IIntroPart
     * 
     * 
     * @see IIntroPart
     */
    public abstract void setFocus();

    /**
     * The IntroPart implementation of this
     * IExecutableExtension records the configuration element in
     * and internal state variable (accessible via getConfigElement).
     * It also loads the title image, if one is specified in the configuration
     * element. Subclasses may extend.
     * 
     * Should not be called by clients. It is called by the core plugin when
     * creating this executable extension.
     */
    public void setInitializationData(IConfigurationElement cfig,
            String propertyName, Object data) {

        // Save config element.
        configElement = cfig;

        titleLabel = cfig.getAttribute(IWorkbenchRegistryConstants.ATT_LABEL);
        
        // Icon.
        String strIcon = cfig.getAttribute(IWorkbenchRegistryConstants.ATT_ICON);
        if (strIcon == null) {
			return;
		}

        imageDescriptor = AbstractUIPlugin.imageDescriptorFromPlugin(
                configElement.getNamespace(), strIcon);

        if (imageDescriptor == null) {
			return;
		}

        Image image = JFaceResources.getResources().createImageWithDefault(imageDescriptor);
        titleImage = image;
    }

    /**
     * Sets or clears the title image of this part.
     * 
     * @param titleImage
     *            the title image, or null to clear
     */
    protected void setTitleImage(Image titleImage) {
        Assert.isTrue(titleImage == null || !titleImage.isDisposed());
        //Do not send changes if they are the same
        if (this.titleImage == titleImage) {
			return;
		}
        this.titleImage = titleImage;
        firePropertyChange(IIntroPart.PROP_TITLE);
    }
    
    /**
     * Set the title string for this part.
     * 
     * @param titleLabel the title string.  Must not be null.
     * @since 3.2
     */
    protected void setTitle(String titleLabel) {
    	Assert.isNotNull(titleLabel);
    	if (Util.equals(this.titleLabel, titleLabel))
    		return;
    	this.titleLabel = titleLabel;
    	firePropertyChange(IIntroPart.PROP_TITLE);
    }
}