| /******************************************************************************* |
| * Copyright (c) 2004, 2010 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. |
| * <p> |
| * The intro part implementation is contributed to the workbench via the |
| * <code>org.eclipse.ui.intro</code> 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. |
| * </p> |
| * <p> |
| * This interface in not intended to be directly implemented. Rather, clients |
| * providing a intro part implementation should subclass |
| * {@link org.eclipse.ui.part.IntroPart}. |
| * </p> |
| * |
| * @see org.eclipse.ui.intro.IIntroManager#showIntro(org.eclipse.ui.IWorkbenchWindow, boolean) |
| * @since 1.2 |
| * @noimplement This interface is not intended to be implemented by clients. |
| */ |
| public interface IIntroPart extends IAdaptable { |
| |
| /** |
| * The property id for <code>getTitleImage</code> and |
| * <code>getTitle</code>. |
| * |
| * @since 3.2 this property now covers changes to <code>getTitle</code> in |
| * addition to <code>getTitleImage</code> |
| */ |
| 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. |
| * <p> |
| * 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. |
| * </p> |
| * |
| * @param site the intro site |
| * @param memento the intro part state or <code>null</code> 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. |
| * <p> |
| * 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. |
| * </p> |
| * |
| * @param standby <code>true</code> to put this part in its partially |
| * visible standy mode, and <code>false</code> to make it fully visible |
| */ |
| public void standbyStateChanged(boolean standby); |
| |
| /** |
| * Saves the object state within a memento. |
| * <p> |
| * This method is automatically called by the workbench at appropriate |
| * times. Clients must not call this method directly. |
| * </p> |
| * |
| * @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. |
| * <p> |
| * The properties ids are as follows: |
| * <ul> |
| * <li><code>IIntroPart.PROP_TITLE</code> </li> |
| * </ul> |
| * </p> |
| * |
| * @param listener a property listener |
| */ |
| public void addPropertyListener(IPropertyListener listener); |
| |
| /** |
| * Creates the SWT controls for this intro part. |
| * <p> |
| * Clients should not call this method (the workbench calls this method when |
| * it needs to, which may be never). |
| * </p> |
| * <p> |
| * For implementors this is a multi-step process: |
| * <ol> |
| * <li>Create one or more controls within the parent.</li> |
| * <li>Set the parent layout as needed.</li> |
| * <li>Register any global actions with the <code>IActionService</code>.</li> |
| * <li>Register any popup menus with the <code>IActionService</code>.</li> |
| * <li>Register a selection provider with the <code>ISelectionService</code> |
| * (optional). </li> |
| * </ol> |
| * </p> |
| * |
| * @param parent the parent control |
| */ |
| public void createPartControl(Composite parent); |
| |
| /** |
| * Disposes of this intro part. |
| * <p> |
| * This is the last method called on the <code>IIntroPart</code>. 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. |
| * </p> |
| * <p> |
| * 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. |
| * </p> |
| * <p> |
| * Clients should not call this method (the workbench calls this method at |
| * appropriate times). |
| * </p> |
| */ |
| 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}. |
| * <p> |
| * 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 <b>not</b> dispose the returned image. |
| * </p> |
| * |
| * @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}. |
| * <p> |
| * The title is used to populate the title bar of this part's visual |
| * container. |
| * </p> |
| * |
| * @return the intro part title (not <code>null</code>) |
| */ |
| public String getTitle(); |
| |
| /** |
| * Removes the given property listener from this intro part. |
| * Has no effect 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. |
| * <p> |
| * 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)}. |
| * </p> |
| */ |
| public void setFocus(); |
| } |