IIntroContentProvider


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.config;
12  
13  import java.io.PrintWriter  ;
14  
15  import org.eclipse.swt.widgets.Composite;
16  import org.eclipse.ui.forms.widgets.FormToolkit;
17  
18  /**
19   * A content provider for dynamic intro content. It is initialized with the
20   * content provider site because a typical content provider would need to update
21   * its contents dynamically at runtime. And so, the site can be informed of a
22   * need to redraw its content through a call to its reflow(..) method.
23   * <p>
24   * The life cycle of an IIntroContentProvider is as follows:
25   * <ul>
26   * <li>a content provider is defined in the Intro content markup file (ie:
27   * introContent.xml file) as follows:
28   * 
29   * <p>
30   * &lt;contentProvider id=&quot;roles&quot;
31   * class=&quot;x.y.z.ContentProvider&quot;&gt; <br>
32   * &lt;text&gt;Some alternate text for dynamic content&lt;/text&gt; <br>
33   * &lt;/contentProvider&gt;
34   * </p>
35   * 
36   * This defines the content provider as part of the intro content for that page.
37   * </li>
38   * <li>the content provider class is created when the page that contains this
39   * provider is loaded. It is only created once in the life cycle of an open
40   * Intro view, ie: the class instance is cached and only disposed of when the
41   * intro view is closed.
42   * <li>init() is called to initialize the instance of the class on load of the
43   * page. This is where the provider site can be cached for later reuse.</li>
44   * <li>createContent() is then called to give the content provider a chance to
45   * generate the dynamic content. This is when the dynamic content can be cached
46   * for later reuse when the same page is shown again.</li>
47   * <li>it is important to note that there is a difference between when the
48   * createContent() is called in the case of SWT and HTML presentations. The HTML
49   * presentation is dynamic html generated on the fly each time an Intro page
50   * needs to be displayed. SWT presentation on the other hand, is based on SWT
51   * forms widgets, and for performance, each page is only created once and cached
52   * in a pageBook for re-use. With this in mind, createContent() is called every
53   * time a page is shown in the case of HTML presentation. Whereas it is only
54   * called once in the case of the SWT presentation. This is why createContent()
55   * should not be used as a means of refreshing content. Content should only be
56   * created once during this method call, and cached for later re-use. If a
57   * refresh is needed, then reflow() should be called on the contentProviderSite
58   * when the appropriate event happens.
59   * <li>finally, when the intro view is closed, dispose will be called on the
60   * content provider to give it a chance to dispose of any resources.</li>
61   * 
62   * @since 3.0.1
63   */
64  public interface IIntroContentProvider {
65      /**
66       * Initializes the content provider. An IIntroContentProviderSite is passed,
67       * which will be called on to recompute or layout the content when the
68       * content becomes stale.
69       * 
70       * @param site
71       *            the site of this IIntroContentProvider
72       */
73      public void init(IIntroContentProviderSite site);
74  
75  
76      /**
77       * Creates HTML content in the provided PrintWriter. This content will be
78       * included in the generated HTML page when embedded HTML widget is used to
79       * render intro content.
80       * 
81       * @param id
82       *            the unique identifier of the content element. The same content
83       *            provider class can be reused for several elements and the id
84       *            can be used to tell them apart.
85       * @param out
86       *            the output print writer to generate HTML content into
87       */
88      public void createContent(String   id, PrintWriter   out);
89  
90      /**
91       * Creates SWT content in the provided Composite. This method is called when
92       * Eclipse Forms are used to render intro content.
93       * 
94       * @param id
95       *            the unique identifier of the content element
96       * @param parent
97       *            the parent composite that should be used when creating SWT
98       *            widgets
99       * @param toolkit
100      *            the form toolkit that should be used when creating new widgets
101      */
102     public void createContent(String   id, Composite parent, FormToolkit toolkit);
103 
104 
105     /**
106      * Dispose of the ContentProvider. This will only be called when the Intro
107      * view is closed. In other words, the content provider will not be disposed
108      * of until the last possible minute. This gives the implementor the chance
109      * to cache content and avoid regenerating content on every page switch.
110      */
111     public void dispose();
112 
113 }
114
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags