| /******************************************************************************* |
| * Copyright (c) 2004, 2007 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.config; |
| |
| import java.io.PrintWriter; |
| |
| import org.eclipse.swt.widgets.Composite; |
| import org.eclipse.ui.forms.widgets.FormToolkit; |
| |
| /** |
| * A content provider for dynamic intro content. It is initialized with the |
| * content provider site because a typical content provider would need to update |
| * its contents dynamically at runtime. And so, the site can be informed of a |
| * need to redraw its content through a call to its reflow(..) method. |
| * <p> |
| * The life cycle of an IIntroContentProvider is as follows: |
| * <ul> |
| * <li>a content provider is defined in the Intro content markup file (ie: |
| * introContent.xml file) as follows: |
| * |
| * <p> |
| * <contentProvider id="roles" |
| * class="x.y.z.ContentProvider"> <br> |
| * <text>Some alternate text for dynamic content</text> <br> |
| * </contentProvider> |
| * </p> |
| * |
| * This defines the content provider as part of the intro content for that page. |
| * </li> |
| * <li>the content provider class is created when the page that contains this |
| * provider is loaded. It is only created once in the life cycle of an open |
| * Intro view, ie: the class instance is cached and only disposed of when the |
| * intro view is closed. |
| * <li>init() is called to initialize the instance of the class on load of the |
| * page. This is where the provider site can be cached for later reuse.</li> |
| * <li>createContent() is then called to give the content provider a chance to |
| * generate the dynamic content. This is when the dynamic content can be cached |
| * for later reuse when the same page is shown again.</li> |
| * <li>it is important to note that there is a difference between when the |
| * createContent() is called in the case of SWT and HTML presentations. The HTML |
| * presentation is dynamic html generated on the fly each time an Intro page |
| * needs to be displayed. SWT presentation on the other hand, is based on SWT |
| * forms widgets, and for performance, each page is only created once and cached |
| * in a pageBook for re-use. With this in mind, createContent() is called every |
| * time a page is shown in the case of HTML presentation. Whereas it is only |
| * called once in the case of the SWT presentation. This is why createContent() |
| * should not be used as a means of refreshing content. Content should only be |
| * created once during this method call, and cached for later re-use. If a |
| * refresh is needed, then reflow() should be called on the contentProviderSite |
| * when the appropriate event happens. |
| * <li>finally, when the intro view is closed, dispose will be called on the |
| * content provider to give it a chance to dispose of any resources.</li> |
| * |
| * @since 3.0.1 |
| */ |
| public interface IIntroContentProvider { |
| /** |
| * Initializes the content provider. An IIntroContentProviderSite is passed, |
| * which will be called on to recompute or layout the content when the |
| * content becomes stale. |
| * |
| * @param site |
| * the site of this IIntroContentProvider |
| */ |
| public void init(IIntroContentProviderSite site); |
| |
| |
| /** |
| * Creates HTML content in the provided PrintWriter. This content will be |
| * included in the generated HTML page when embedded HTML widget is used to |
| * render intro content. |
| * |
| * @param id |
| * the unique identifier of the content element. The same content |
| * provider class can be reused for several elements and the id |
| * can be used to tell them apart. |
| * @param out |
| * the output print writer to generate HTML content into |
| */ |
| public void createContent(String id, PrintWriter out); |
| |
| /** |
| * Creates SWT content in the provided Composite. This method is called when |
| * Eclipse Forms are used to render intro content. |
| * |
| * @param id |
| * the unique identifier of the content element |
| * @param parent |
| * the parent composite that should be used when creating SWT |
| * widgets |
| * @param toolkit |
| * the form toolkit that should be used when creating new widgets |
| */ |
| public void createContent(String id, Composite parent, FormToolkit toolkit); |
| |
| |
| /** |
| * Dispose of the ContentProvider. This will only be called when the Intro |
| * view is closed. In other words, the content provider will not be disposed |
| * of until the last possible minute. This gives the implementor the chance |
| * to cache content and avoid regenerating content on every page switch. |
| */ |
| public void dispose(); |
| |
| } |