1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
|
/*******************************************************************************
* 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();
}
|
