org.eclipse.ui.intro.IIntroPart 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.intro;

import org.eclipse.core.runtime.IAdaptable;
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.IWorkbenchPart;
import org.eclipse.ui.IWorkbenchWindow;
import org.eclipse.ui.PartInitException;

/**
 * The intro part is a visual component within the workbench responsible for
 * introducing the product to new users. The intro part is typically shown the
 * first time a product is started up.
 * 
 * The intro part implementation is contributed to the workbench via the
 * org.eclipse.ui.intro extension point.  There can be several
 * intro part implementations, and associations between intro part
 * implementations and products. The workbench will only make use of the intro
 * part implementation for the current product (as given by
 * {@link org.eclipse.core.runtime.Platform#getProduct()}. There is at most one
 * intro part instance in the entire workbench, and it resides in exactly one
 * workbench window at a time.
 * 
 * 
 * This interface in not intended to be directly implemented. Rather, clients
 * providing a intro part implementation should subclass 
 * {@link org.eclipse.ui.part.IntroPart}. 
 * 
 * 
 * @see org.eclipse.ui.intro.IIntroManager#showIntro(org.eclipse.ui.IWorkbenchWindow, boolean)
 * @since 3.0
 */
public interface IIntroPart extends IAdaptable {

    /**
	 * The property id for getTitleImage and
	 * getTitle.
	 * 
	 * @since 3.2 this property now covers changes to getTitle in
	 *        addition to getTitleImage
	 */
	public static final int PROP_TITLE = IWorkbenchPart.PROP_TITLE;

    /**
	 * Returns the site for this intro part.
	 * 
	 * @return the intro site
	 */
    IIntroSite getIntroSite();

    /**
     * Initializes this intro part with the given intro site. A memento is
     * passed to the part which contains a snapshot of the part state from a
     * previous session. Where possible, the part should try to recreate that
     * state.
     * 
     * This method is automatically called by the workbench shortly after
     * part construction.  It marks the start of the intro's lifecycle. Clients
     * must not call this 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;

    /**
     * Sets the standby state of this intro part. An intro part should render
     * itself differently in the full and standby modes. In standby mode, the
     * part should be partially visible to the user but otherwise allow them
     * to work. In full mode, the part should be fully visible and be the center
     * of the user's attention. 
     * 
     * This method is automatically called by the workbench at appropriate
     * times. Clients must not call this method directly (call
     * {@link IIntroManager#setIntroStandby(IIntroPart, boolean)} instead.
     * 
     * 
     * @param standby true to put this part in its partially
     * visible standy mode, and false to make it fully visible
     */
    public void standbyStateChanged(boolean standby);

    /**
     * Saves the object state within a memento.
     * 
     * This method is automatically called by the workbench at appropriate
     * times. Clients must not call this method directly.
     * 
     *
     * @param memento a memento to receive the object state
     */
    public void saveState(IMemento memento);

    /**
     * Adds a listener for changes to properties of this intro part.
     * Has no effect if an identical listener is already registered.
     * 
     * The properties ids are as follows:
     * 

     *   IIntroPart.PROP_TITLE 
     * 
     * 
     *
     * @param listener a property listener
     */
    public void addPropertyListener(IPropertyListener listener);

    /**
     * Creates the SWT controls for this intro part.
     * 
     * Clients should not call this method (the workbench calls this method when
     * it needs to, which may be never).
     * 
     * 
     * For implementors this is a multi-step process:
     * 

     *   Create one or more controls within the parent.
     *   Set the parent layout as needed.
     *   Register any global actions with the IActionService.
     *   Register any popup menus with the IActionService.
     *   Register a selection provider with the ISelectionService
     *     (optional). 
     * 
     * 
     *
     * @param parent the parent control
     */
    public void createPartControl(Composite parent);

    /**
     * Disposes of this intro part.
     * 
     * This is the last method called on the IIntroPart.  At this
     * point the part controls (if they were ever created) have been disposed as part 
     * of an SWT composite.  There is no guarantee that createPartControl() has been 
     * called, so the part controls may never have been created.
     * 
     * 
     * Within this method a part may release any resources, fonts, images, etc.  
     * held by this part.  It is also very important to deregister all listeners
     * from the workbench.
     * 
     * 
     * Clients should not call this method (the workbench calls this method at
     * appropriate times).
     * 
     */
    public void dispose();

    /**
     * Returns the title image of this intro part.  If this value changes 
     * the part must fire a property listener event with 
     * {@link IIntroPart#PROP_TITLE}.
     * 
     * The title image is usually used to populate the title bar of this part's
     * visual container. Since this image is managed by the part itself, callers
     * must not dispose the returned image.
     * 
     *
     * @return the title image
     */
    public Image getTitleImage();
    
    /**
     * Returns the title of this intro part. If this value changes 
     * the part must fire a property listener event with 
     * {@link IIntroPart#PROP_TITLE}.
     * 
     * The title is used to populate the title bar of this part's visual
     * container.  
     * 
     *
     * @return the intro part title (not null)
     * @since 3.2
     */
    public String getTitle();

    /**
     * Removes the given property listener from this intro part.
     * Has no affect if an identical listener is not registered.
     *
     * @param listener a property listener
     */
    public void removePropertyListener(IPropertyListener listener);

    /**
     * Asks this part to take focus within the workbench.
     * 
     * Clients should not call this method (the workbench calls this method at
     * appropriate times).  To have the workbench activate a part, use
     * {@link IIntroManager#showIntro(IWorkbenchWindow, boolean)}.
     * 
     */
    public void setFocus();
}