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.config;
011:
012: import java.io.PrintWriter;
013:
014: import org.eclipse.swt.widgets.Composite;
015: import org.eclipse.ui.forms.widgets.FormToolkit;
016:
017: /**
018: * A content provider for dynamic intro content. It is initialized with the
019: * content provider site because a typical content provider would need to update
020: * its contents dynamically at runtime. And so, the site can be informed of a
021: * need to redraw its content through a call to its reflow(..) method.
022: * <p>
023: * The life cycle of an IIntroContentProvider is as follows:
024: * <ul>
025: * <li>a content provider is defined in the Intro content markup file (ie:
026: * introContent.xml file) as follows:
027: *
028: * <p>
029: * <contentProvider id="roles"
030: * class="x.y.z.ContentProvider"> <br>
031: * <text>Some alternate text for dynamic content</text> <br>
032: * </contentProvider>
033: * </p>
034: *
035: * This defines the content provider as part of the intro content for that page.
036: * </li>
037: * <li>the content provider class is created when the page that contains this
038: * provider is loaded. It is only created once in the life cycle of an open
039: * Intro view, ie: the class instance is cached and only disposed of when the
040: * intro view is closed.
041: * <li>init() is called to initialize the instance of the class on load of the
042: * page. This is where the provider site can be cached for later reuse.</li>
043: * <li>createContent() is then called to give the content provider a chance to
044: * generate the dynamic content. This is when the dynamic content can be cached
045: * for later reuse when the same page is shown again.</li>
046: * <li>it is important to note that there is a difference between when the
047: * createContent() is called in the case of SWT and HTML presentations. The HTML
048: * presentation is dynamic html generated on the fly each time an Intro page
049: * needs to be displayed. SWT presentation on the other hand, is based on SWT
050: * forms widgets, and for performance, each page is only created once and cached
051: * in a pageBook for re-use. With this in mind, createContent() is called every
052: * time a page is shown in the case of HTML presentation. Whereas it is only
053: * called once in the case of the SWT presentation. This is why createContent()
054: * should not be used as a means of refreshing content. Content should only be
055: * created once during this method call, and cached for later re-use. If a
056: * refresh is needed, then reflow() should be called on the contentProviderSite
057: * when the appropriate event happens.
058: * <li>finally, when the intro view is closed, dispose will be called on the
059: * content provider to give it a chance to dispose of any resources.</li>
060: *
061: * @since 3.0.1
062: */
063: public interface IIntroContentProvider {
064: /**
065: * Initializes the content provider. An IIntroContentProviderSite is passed,
066: * which will be called on to recompute or layout the content when the
067: * content becomes stale.
068: *
069: * @param site
070: * the site of this IIntroContentProvider
071: */
072: public void init(IIntroContentProviderSite site);
073:
074: /**
075: * Creates HTML content in the provided PrintWriter. This content will be
076: * included in the generated HTML page when embedded HTML widget is used to
077: * render intro content.
078: *
079: * @param id
080: * the unique identifier of the content element. The same content
081: * provider class can be reused for several elements and the id
082: * can be used to tell them apart.
083: * @param out
084: * the output print writer to generate HTML content into
085: */
086: public void createContent(String id, PrintWriter out);
087:
088: /**
089: * Creates SWT content in the provided Composite. This method is called when
090: * Eclipse Forms are used to render intro content.
091: *
092: * @param id
093: * the unique identifier of the content element
094: * @param parent
095: * the parent composite that should be used when creating SWT
096: * widgets
097: * @param toolkit
098: * the form toolkit that should be used when creating new widgets
099: */
100: public void createContent(String id, Composite parent,
101: FormToolkit toolkit);
102:
103: /**
104: * Dispose of the ContentProvider. This will only be called when the Intro
105: * view is closed. In other words, the content provider will not be disposed
106: * of until the last possible minute. This gives the implementor the chance
107: * to cache content and avoid regenerating content on every page switch.
108: */
109: public void dispose();
110:
111: }
|