Skip to main content
aboutsummaryrefslogtreecommitdiffstats
blob: b8e14e1a10584e72bb3761822ef9a2d6ea2b73e2 (plain) (blame)
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
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
/*******************************************************************************
 * Copyright (c) 2004, 2011 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.debug.ui.memory;

import org.eclipse.core.runtime.IAdaptable;
import org.eclipse.debug.core.model.IMemoryBlock;
import org.eclipse.jface.util.IPropertyChangeListener;
import org.eclipse.swt.graphics.Image;
import org.eclipse.swt.widgets.Composite;
import org.eclipse.swt.widgets.Control;

/**
 * An arbitrary rendering of a memory block. A memory rendering is contributed
 * via the <code>memoryRenderings</code> extension point.
 * <p>
 * Following is an example definition of a memory renderings extension.
 * <pre>
 * &lt;extension point="org.eclipse.debug.ui.memoryRenderings"&gt;
 *   &lt;memoryRenderingType
 *      id="com.example.asciiRendering"
 *      name="ASCII"
 *      class="com.example.RenderingFactory"&gt;
 *   &lt;/memoryRenderingType&gt;
 * &lt;/extension&gt;
 * </pre>
 * The attributes are specified as follows:
 * <ul>
 * <li><code>id</code> specifies a unique identifier for a type of memory rendering</li>
 * <li><code>name</code> specifies a human readable label for a rendering type</li>
 * <li><code>class</code> specifies the fully qualified name of the Java class
 *   that implements <code>IMemoryRenderingTypeDelegate</code>. Renderings are created
 *   via this factory.</li>
 * </ul>
 * </p>
 * <p>
 * A rendering provides an image and label. To support dynamic labels and images, property
 * change notification is used with the following property constants defined in
 * <code>IBasicPropertyConstants</code>:
 * <ul>
 * <li><code>P_TEXT</code> - indicates a label change</li>
 * <li><code>P_IMAGE</code> - indicates a image change</li>
 * </ul>
 * </p>
 * <p>
 * Renderings needing to synchronize with other renderings are intended to use
 * property change notifications via its synchronization service. For example, when a
 * rendering becomes visible, it can register for property change events with its rendering
 * site's synchronization service, and when it becomes hidden it can unregister. When a
 * rendering is activated, it should set itself as the synchrnoization provider in its
 * rendering site and fire property change events to communicate information to
 * interested listeners.
 * </p>
 * <p>
 * Clients contributing a memory rendering type are intended to implement this interface
 * and <code>IMemoryRenderingTypeDelegate</code>. The factory will be used to create instances
 * of <code>IMemoryRendering</code>.
 * </p>
 * @since 3.1
 */
public interface IMemoryRendering extends IAdaptable{

    /**
     * Initializes this rendering to be hosted in the given container, displaying
     * the given memory block. This method is called before this rendering's control
     * has been created.
     *
     * @param container container hosting this rendering
     * @param block the memory block to render
     */
    public void init(IMemoryRenderingContainer container, IMemoryBlock block);

    /**
     * Creates the top level control for this rendering under the given parent composite.
     * This method is called after this rendering's <code>init</code> method has been
     * called.
     * <p>
     * Implementors are responsible for ensuring that
     * the created control can be accessed via <code>getControl</code>
     * </p>
     * @param parent the parent composite
     * @return the new top level control
     */
    public Control createControl(Composite parent);

    /**
     * Returns the top level control for this rendering.
     * <p>
     * May return <code>null</code> if the control
     * has not been created yet.
     * </p>
     * @return the top level control or <code>null</code>
     */
    public Control getControl();

    /**
     * Disposes this rendering.
     */
    public void dispose();

    /**
     * Notification this rendering has become the active rendering. Only one
     * rendering can be active at once. Generally, the active rendering is
     * visible and has focus.
     */
    public void activated();

    /**
     * Notification this rendering is no longer the active rendering.
     */
    public void deactivated();

    /**
     * Notification this rendering has become visible in its container.
     * Note that a rendering does not have to be active to be visible.
     */
    public void becomesVisible();

    /**
     * Notification this rendering has become hidden in its container.
     */
    public void becomesHidden();

    /**
     * Returns the memory block displayed by this rendering.
     *
     * @return the memory block displayed by this rendering
     */
    public IMemoryBlock getMemoryBlock();

    /**
     * Returns the identifier associated with this rendering's type.
     *
     * @return the identifier associated with this rendering's type
     * @see IMemoryRenderingType
     */
    public String getRenderingId();

    /**
     * Adds a listener for property changes to this rendering.
     * Has no effect if an identical listener is already registered.
     *
     * @param listener a property change listener
     */
    public void addPropertyChangeListener(IPropertyChangeListener listener);

    /**
     * Removes the given property change listener from this rendering.
     * Has no effect if the identical listener is not registered.
     *
     * @param listener a property change listener
     */
    public void removePropertyChangeListener(IPropertyChangeListener listener);

    /**
     * Returns an image for this rendering. Clients should not dispose
     * this image. This rendering will dispose the image if required when
     * this rendering is disposed.
     *
     * @return an image for this rendering
     */
    public Image getImage();

    /**
     * Returns a label for this rendering.
     *
     * @return a label for this rendering
     */
    public String getLabel();
}

Back to the top