001: /*******************************************************************************
002: * Copyright (c) 2004, 2006 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.ui.intro;
011:
012: import org.eclipse.core.runtime.IAdaptable;
013: import org.eclipse.swt.graphics.Image;
014: import org.eclipse.swt.widgets.Composite;
015: import org.eclipse.ui.IMemento;
016: import org.eclipse.ui.IPropertyListener;
017: import org.eclipse.ui.IWorkbenchPart;
018: import org.eclipse.ui.IWorkbenchWindow;
019: import org.eclipse.ui.PartInitException;
020:
021: /**
022: * The intro part is a visual component within the workbench responsible for
023: * introducing the product to new users. The intro part is typically shown the
024: * first time a product is started up.
025: * <p>
026: * The intro part implementation is contributed to the workbench via the
027: * <code>org.eclipse.ui.intro</code> extension point. There can be several
028: * intro part implementations, and associations between intro part
029: * implementations and products. The workbench will only make use of the intro
030: * part implementation for the current product (as given by
031: * {@link org.eclipse.core.runtime.Platform#getProduct()}. There is at most one
032: * intro part instance in the entire workbench, and it resides in exactly one
033: * workbench window at a time.
034: * </p>
035: * <p>
036: * This interface in not intended to be directly implemented. Rather, clients
037: * providing a intro part implementation should subclass
038: * {@link org.eclipse.ui.part.IntroPart}.
039: * </p>
040: *
041: * @see org.eclipse.ui.intro.IIntroManager#showIntro(org.eclipse.ui.IWorkbenchWindow, boolean)
042: * @since 3.0
043: */
044: public interface IIntroPart extends IAdaptable {
045:
046: /**
047: * The property id for <code>getTitleImage</code> and
048: * <code>getTitle</code>.
049: *
050: * @since 3.2 this property now covers changes to <code>getTitle</code> in
051: * addition to <code>getTitleImage</code>
052: */
053: public static final int PROP_TITLE = IWorkbenchPart.PROP_TITLE;
054:
055: /**
056: * Returns the site for this intro part.
057: *
058: * @return the intro site
059: */
060: IIntroSite getIntroSite();
061:
062: /**
063: * Initializes this intro part with the given intro site. A memento is
064: * passed to the part which contains a snapshot of the part state from a
065: * previous session. Where possible, the part should try to recreate that
066: * state.
067: * <p>
068: * This method is automatically called by the workbench shortly after
069: * part construction. It marks the start of the intro's lifecycle. Clients
070: * must not call this method.
071: * </p>
072: *
073: * @param site the intro site
074: * @param memento the intro part state or <code>null</code> if there is no previous
075: * saved state
076: * @exception PartInitException if this part was not initialized
077: * successfully
078: */
079: public void init(IIntroSite site, IMemento memento)
080: throws PartInitException;
081:
082: /**
083: * Sets the standby state of this intro part. An intro part should render
084: * itself differently in the full and standby modes. In standby mode, the
085: * part should be partially visible to the user but otherwise allow them
086: * to work. In full mode, the part should be fully visible and be the center
087: * of the user's attention.
088: * <p>
089: * This method is automatically called by the workbench at appropriate
090: * times. Clients must not call this method directly (call
091: * {@link IIntroManager#setIntroStandby(IIntroPart, boolean)} instead.
092: * </p>
093: *
094: * @param standby <code>true</code> to put this part in its partially
095: * visible standy mode, and <code>false</code> to make it fully visible
096: */
097: public void standbyStateChanged(boolean standby);
098:
099: /**
100: * Saves the object state within a memento.
101: * <p>
102: * This method is automatically called by the workbench at appropriate
103: * times. Clients must not call this method directly.
104: * </p>
105: *
106: * @param memento a memento to receive the object state
107: */
108: public void saveState(IMemento memento);
109:
110: /**
111: * Adds a listener for changes to properties of this intro part.
112: * Has no effect if an identical listener is already registered.
113: * <p>
114: * The properties ids are as follows:
115: * <ul>
116: * <li><code>IIntroPart.PROP_TITLE</code> </li>
117: * </ul>
118: * </p>
119: *
120: * @param listener a property listener
121: */
122: public void addPropertyListener(IPropertyListener listener);
123:
124: /**
125: * Creates the SWT controls for this intro part.
126: * <p>
127: * Clients should not call this method (the workbench calls this method when
128: * it needs to, which may be never).
129: * </p>
130: * <p>
131: * For implementors this is a multi-step process:
132: * <ol>
133: * <li>Create one or more controls within the parent.</li>
134: * <li>Set the parent layout as needed.</li>
135: * <li>Register any global actions with the <code>IActionService</code>.</li>
136: * <li>Register any popup menus with the <code>IActionService</code>.</li>
137: * <li>Register a selection provider with the <code>ISelectionService</code>
138: * (optional). </li>
139: * </ol>
140: * </p>
141: *
142: * @param parent the parent control
143: */
144: public void createPartControl(Composite parent);
145:
146: /**
147: * Disposes of this intro part.
148: * <p>
149: * This is the last method called on the <code>IIntroPart</code>. At this
150: * point the part controls (if they were ever created) have been disposed as part
151: * of an SWT composite. There is no guarantee that createPartControl() has been
152: * called, so the part controls may never have been created.
153: * </p>
154: * <p>
155: * Within this method a part may release any resources, fonts, images, etc.
156: * held by this part. It is also very important to deregister all listeners
157: * from the workbench.
158: * </p>
159: * <p>
160: * Clients should not call this method (the workbench calls this method at
161: * appropriate times).
162: * </p>
163: */
164: public void dispose();
165:
166: /**
167: * Returns the title image of this intro part. If this value changes
168: * the part must fire a property listener event with
169: * {@link IIntroPart#PROP_TITLE}.
170: * <p>
171: * The title image is usually used to populate the title bar of this part's
172: * visual container. Since this image is managed by the part itself, callers
173: * must <b>not</b> dispose the returned image.
174: * </p>
175: *
176: * @return the title image
177: */
178: public Image getTitleImage();
179:
180: /**
181: * Returns the title of this intro part. If this value changes
182: * the part must fire a property listener event with
183: * {@link IIntroPart#PROP_TITLE}.
184: * <p>
185: * The title is used to populate the title bar of this part's visual
186: * container.
187: * </p>
188: *
189: * @return the intro part title (not <code>null</code>)
190: * @since 3.2
191: */
192: public String getTitle();
193:
194: /**
195: * Removes the given property listener from this intro part.
196: * Has no affect if an identical listener is not registered.
197: *
198: * @param listener a property listener
199: */
200: public void removePropertyListener(IPropertyListener listener);
201:
202: /**
203: * Asks this part to take focus within the workbench.
204: * <p>
205: * Clients should not call this method (the workbench calls this method at
206: * appropriate times). To have the workbench activate a part, use
207: * {@link IIntroManager#showIntro(IWorkbenchWindow, boolean)}.
208: * </p>
209: */
210: public void setFocus();
211: }
|