IIntroPart


1   /*******************************************************************************
2    * Copyright (c) 2004, 2006 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.ui.intro;
12  
13  import org.eclipse.core.runtime.IAdaptable;
14  import org.eclipse.swt.graphics.Image;
15  import org.eclipse.swt.widgets.Composite;
16  import org.eclipse.ui.IMemento;
17  import org.eclipse.ui.IPropertyListener;
18  import org.eclipse.ui.IWorkbenchPart;
19  import org.eclipse.ui.IWorkbenchWindow;
20  import org.eclipse.ui.PartInitException;
21  
22  /**
23   * The intro part is a visual component within the workbench responsible for
24   * introducing the product to new users. The intro part is typically shown the
25   * first time a product is started up.
26   * <p>
27   * The intro part implementation is contributed to the workbench via the
28   * <code>org.eclipse.ui.intro</code> extension point.  There can be several
29   * intro part implementations, and associations between intro part
30   * implementations and products. The workbench will only make use of the intro
31   * part implementation for the current product (as given by
32   * {@link org.eclipse.core.runtime.Platform#getProduct()}. There is at most one
33   * intro part instance in the entire workbench, and it resides in exactly one
34   * workbench window at a time.
35   * </p>
36   * <p>
37   * This interface in not intended to be directly implemented. Rather, clients
38   * providing a intro part implementation should subclass 
39   * {@link org.eclipse.ui.part.IntroPart}. 
40   * </p>
41   * 
42   * @see org.eclipse.ui.intro.IIntroManager#showIntro(org.eclipse.ui.IWorkbenchWindow, boolean)
43   * @since 3.0
44   */
45  public interface IIntroPart extends IAdaptable {
46  
47      /**
48       * The property id for <code>getTitleImage</code> and
49       * <code>getTitle</code>.
50       * 
51       * @since 3.2 this property now covers changes to <code>getTitle</code> in
52       *        addition to <code>getTitleImage</code>
53       */
54      public static final int PROP_TITLE = IWorkbenchPart.PROP_TITLE;
55  
56      /**
57       * Returns the site for this intro part.
58       * 
59       * @return the intro site
60       */
61      IIntroSite getIntroSite();
62  
63      /**
64       * Initializes this intro part with the given intro site. A memento is
65       * passed to the part which contains a snapshot of the part state from a
66       * previous session. Where possible, the part should try to recreate that
67       * state.
68       * <p>
69       * This method is automatically called by the workbench shortly after
70       * part construction.  It marks the start of the intro's lifecycle. Clients
71       * must not call this method.
72       * </p>
73       *
74       * @param site the intro site
75       * @param memento the intro part state or <code>null</code> if there is no previous
76       * saved state
77       * @exception PartInitException if this part was not initialized
78       * successfully
79       */
80      public void init(IIntroSite site, IMemento memento)
81              throws PartInitException;
82  
83      /**
84       * Sets the standby state of this intro part. An intro part should render
85       * itself differently in the full and standby modes. In standby mode, the
86       * part should be partially visible to the user but otherwise allow them
87       * to work. In full mode, the part should be fully visible and be the center
88       * of the user's attention. 
89       * <p>
90       * This method is automatically called by the workbench at appropriate
91       * times. Clients must not call this method directly (call
92       * {@link IIntroManager#setIntroStandby(IIntroPart, boolean)} instead.
93       * </p>
94       * 
95       * @param standby <code>true</code> to put this part in its partially
96       * visible standy mode, and <code>false</code> to make it fully visible
97       */
98      public void standbyStateChanged(boolean standby);
99  
100     /**
101      * Saves the object state within a memento.
102      * <p>
103      * This method is automatically called by the workbench at appropriate
104      * times. Clients must not call this method directly.
105      * </p>
106      *
107      * @param memento a memento to receive the object state
108      */
109     public void saveState(IMemento memento);
110 
111     /**
112      * Adds a listener for changes to properties of this intro part.
113      * Has no effect if an identical listener is already registered.
114      * <p>
115      * The properties ids are as follows:
116      * <ul>
117      *   <li><code>IIntroPart.PROP_TITLE</code> </li>
118      * </ul>
119      * </p>
120      *
121      * @param listener a property listener
122      */
123     public void addPropertyListener(IPropertyListener listener);
124 
125     /**
126      * Creates the SWT controls for this intro part.
127      * <p>
128      * Clients should not call this method (the workbench calls this method when
129      * it needs to, which may be never).
130      * </p>
131      * <p>
132      * For implementors this is a multi-step process:
133      * <ol>
134      *   <li>Create one or more controls within the parent.</li>
135      *   <li>Set the parent layout as needed.</li>
136      *   <li>Register any global actions with the <code>IActionService</code>.</li>
137      *   <li>Register any popup menus with the <code>IActionService</code>.</li>
138      *   <li>Register a selection provider with the <code>ISelectionService</code>
139      *     (optional). </li>
140      * </ol>
141      * </p>
142      *
143      * @param parent the parent control
144      */
145     public void createPartControl(Composite parent);
146 
147     /**
148      * Disposes of this intro part.
149      * <p>
150      * This is the last method called on the <code>IIntroPart</code>.  At this
151      * point the part controls (if they were ever created) have been disposed as part 
152      * of an SWT composite.  There is no guarantee that createPartControl() has been 
153      * called, so the part controls may never have been created.
154      * </p>
155      * <p>
156      * Within this method a part may release any resources, fonts, images, etc.&nbsp; 
157      * held by this part.  It is also very important to deregister all listeners
158      * from the workbench.
159      * </p>
160      * <p>
161      * Clients should not call this method (the workbench calls this method at
162      * appropriate times).
163      * </p>
164      */
165     public void dispose();
166 
167     /**
168      * Returns the title image of this intro part.  If this value changes 
169      * the part must fire a property listener event with 
170      * {@link IIntroPart#PROP_TITLE}.
171      * <p>
172      * The title image is usually used to populate the title bar of this part's
173      * visual container. Since this image is managed by the part itself, callers
174      * must <b>not</b> dispose the returned image.
175      * </p>
176      *
177      * @return the title image
178      */
179     public Image getTitleImage();
180     
181     /**
182      * Returns the title of this intro part. If this value changes 
183      * the part must fire a property listener event with 
184      * {@link IIntroPart#PROP_TITLE}.
185      * <p>
186      * The title is used to populate the title bar of this part's visual
187      * container.  
188      * </p>
189      *
190      * @return the intro part title (not <code>null</code>)
191      * @since 3.2
192      */
193     public String   getTitle();
194 
195     /**
196      * Removes the given property listener from this intro part.
197      * Has no affect if an identical listener is not registered.
198      *
199      * @param listener a property listener
200      */
201     public void removePropertyListener(IPropertyListener listener);
202 
203     /**
204      * Asks this part to take focus within the workbench.
205      * <p>
206      * Clients should not call this method (the workbench calls this method at
207      * appropriate times).  To have the workbench activate a part, use
208      * {@link IIntroManager#showIntro(IWorkbenchWindow, boolean)}.
209      * </p>
210      */
211     public void setFocus();
212 }
213
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags