JOGL v2.6.0-rc-20250706
JOGL, High-Performance Graphics Binding for Java™ (public API).
AWTAdapter.java
Go to the documentation of this file.
1/**
2 * Copyright 2010 JogAmp Community. All rights reserved.
3 *
4 * Redistribution and use in source and binary forms, with or without modification, are
5 * permitted provided that the following conditions are met:
6 *
7 * 1. Redistributions of source code must retain the above copyright notice, this list of
8 * conditions and the following disclaimer.
9 *
10 * 2. Redistributions in binary form must reproduce the above copyright notice, this list
11 * of conditions and the following disclaimer in the documentation and/or other materials
12 * provided with the distribution.
13 *
14 * THIS SOFTWARE IS PROVIDED BY JogAmp Community ``AS IS'' AND ANY EXPRESS OR IMPLIED
15 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
16 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JogAmp Community OR
17 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
18 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
19 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
20 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
21 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
22 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
23 *
24 * The views and conclusions contained in the software and documentation are those of the
25 * authors and should not be interpreted as representing official policies, either expressed
26 * or implied, of JogAmp Community.
27 */
28
29package com.jogamp.newt.event.awt;
30
31import com.jogamp.nativewindow.NativeSurfaceHolder;
32
33import jogamp.newt.Debug;
34
35/**
36 * Convenient adapter forwarding AWT events to NEWT via the event listener model.<br>
37 * <p>
38 * You may attach an instance of this adapter to an AWT Component. When an event happens,
39 * it is converted to a NEWT event and the given NEWT listener is being called.<br></p>
40 * <p>
41 * This adapter fullfills three use cases. First as a plain utility to write code AWT agnostic,
42 * ie write an {@link com.jogamp.opengl.GLEvenListener} and some appropriate NEWT {@link com.jogamp.newt.event.NEWTEventListener}.<br></p>
43 * <p>
44 * Attach the {@link com.jogamp.opengl.GLEvenListener} to a NEWT {@link com.jogamp.opengl.GLAutoDrawable}, e.g. {@link com.jogamp.newt.opengl.GLWindow},<br>
45 * or to an AWT {@link com.jogamp.opengl.GLAutoDrawable}, e.g. {@link com.jogamp.opengl.awt.GLCanvas}.<br>
46 * <br>
47 * Attach the NEWT {@link com.jogamp.newt.event.NEWTEventListener} to a NEWT component, e.g. {@link com.jogamp.newt.Window},<br>
48 * or to an AWT component, e.g. {@link java.awt.Component}.<br></p>
49 * <p>
50 * Common:<br>
51 * <pre>
52 // your demo/render code
53 com.jogamp.opengl.GLEvenListener demo1 = new com.jogamp.opengl.GLEvenListener() { ... } ;
54
55 // your AWT agnostic NEWT mouse listener code
56 com.jogamp.newt.event.MouseListener mouseListener = new com.jogamp.newt.event.MouseAdapter() { ... } ;
57 * </pre> </p>
58 * <p>
59 * Default NEWT use case, without using the AWTAdapter:<br>
60 * <pre>
61 // the NEWT GLAutoDrawable and Window
62 GLWindow glWindow = GLWindow.create();
63
64 // attach the renderer demo1
65 glWindow.addGLEventListener(demo1);
66
67 // attach the NEWT mouse event listener to glWindow
68 glWindow.addMouseListener(mouseListener);
69 * </pre> </p>
70 * <p>
71 * AWT use case, AWTAdapter used as an AWT event translator and forwarder to your NEWT listener:<br>
72 * <pre>
73 // the AWT GLAutoDrawable and Canvas
74 GLCanvas glCanvas = new GLCanvas();
75
76 // attach the renderer demo1
77 glCanvas.addGLEventListener(demo1);
78
79 // attach the AWTMouseAdapter to glCanvas, which translates and forwards events to the NEWT mouseListener
80 new AWTMouseAdapter(mouseListener).addTo(glCanvas);
81 * </pre> </p>
82 * <p>
83 * Previous code in detail:<br>
84 * <pre>
85 AWTMouseAdapter mouseAdapter = new AWTMouseAdapter(mouseListener);
86 glCanvas.addMouseListener(mouseAdapter);
87 glCanvas.addMouseMotionListener(mouseAdapter);
88 * </pre> </p>
89 *
90 * <p>
91 * Second use case is just a litte variation of the previous use case, where we pass a NEWT Window <br>
92 * to be used as the source of the event.<br></p>
93 * <p>
94 * <pre>
95 com.jogamp.newt.event.MouseListener mouseListener = new com.jogamp.newt.event.MouseAdapter() { ... } ;<br>
96 Component comp = ... ; // the AWT component<br>
97 GLWindow glWindow = GLWindow.create(); // the NEWT component<br>
98 <br>
99 new AWTMouseAdapter(mouseListener, glWindow).addTo(comp);<br>
100 * </pre> </p>
101 *
102 * Last but not least, the AWTAdapter maybe used as a general AWT event forwarder to NEWT.<br>
103 *
104 * <p>
105 * <pre>
106 com.jogamp.newt.event.MouseListener mouseListener = new com.jogamp.newt.event.MouseAdapter() { ... } ;<br>
107 Component comp = ... ; // the AWT component<br>
108 GLWindow glWindow = GLWindow.create(); // the NEWT component<br>
109 glWindow.addMouseListener(mouseListener); // add the custom EventListener to the NEWT component<br>
110 <br>
111 new AWTMouseAdapter(glWindow).addTo(comp); // forward all AWT events to glWindow, as NEWT events<br>
112 * </pre> </p>
113 *
114 * @see #attachTo
115 */
116public abstract class AWTAdapter implements java.util.EventListener
117{
118 public static final boolean DEBUG_IMPLEMENTATION = Debug.debug("Window");
119
121 com.jogamp.newt.Window newtWindow;
122 NativeSurfaceHolder nsHolder;
123 boolean consumeAWTEvent;
124 protected boolean isSetup;
125
126 /**
127 * Create a proxy adapter, wrapping around an NEWT EventListener, exposed as an AWT EventListener,<br>
128 * where the given {@link NativeSurfaceHolder} impersonates the event's source.
129 * The NEWT EventListener will be called when an event happens.<br>
130 */
131 protected AWTAdapter(final com.jogamp.newt.event.NEWTEventListener newtListener, final NativeSurfaceHolder nsProxy) {
132 if(null==newtListener) {
133 throw new IllegalArgumentException("Argument newtListener is null");
134 }
135 if(null==nsProxy) {
136 throw new IllegalArgumentException("Argument nwProxy is null");
137 }
138 this.newtListener = newtListener;
139 this.newtWindow = null;
140 this.nsHolder = nsProxy;
141 this.consumeAWTEvent = false;
142 this.isSetup = true;
143 }
144
145 /**
146 * Create a proxy adapter, wrapping around an NEWT EventListener, exposed as an AWT EventListener,<br>
147 * where the given {@link com.jogamp.newt.Window NEWT Window}, a {@link NativeSurfaceHolder}, impersonates the event's source.
148 * The NEWT EventListener will be called when an event happens.<br>
149 */
150 protected AWTAdapter(final com.jogamp.newt.event.NEWTEventListener newtListener, final com.jogamp.newt.Window newtProxy) {
151 if(null==newtListener) {
152 throw new IllegalArgumentException("Argument newtListener is null");
153 }
154 if(null==newtProxy) {
155 throw new IllegalArgumentException("Argument newtProxy is null");
156 }
157 this.newtListener = newtListener;
158 this.newtWindow = newtProxy;
159 this.nsHolder = newtProxy;
160 this.consumeAWTEvent = false;
161 this.isSetup = true;
162 }
163
164 /**
165 * Create a pipeline adapter, AWT EventListener.<br>
166 * Once attached to an AWT component, it sends the converted AWT events to the NEWT downstream window.<br>
167 * This is only supported with EDT enabled!
168 * @throws IllegalStateException if EDT is not enabled
169 */
170 protected AWTAdapter(final com.jogamp.newt.Window downstream) throws IllegalStateException {
171 this();
172 setDownstream(downstream);
173 }
174
175 public AWTAdapter() {
176 clear();
177 this.consumeAWTEvent = false;
178 }
179
180 /**
181 * Setup a pipeline adapter, AWT EventListener.<br>
182 * Once attached to an AWT component, it sends the converted AWT events to the NEWT downstream window.<br>
183 * This is only supported with EDT enabled!
184 * @throws IllegalStateException if EDT is not enabled
185 */
186 public synchronized AWTAdapter setDownstream(final com.jogamp.newt.Window downstream) throws IllegalStateException {
187 if(null==downstream) {
188 throw new RuntimeException("Argument downstream is null");
189 }
190 this.newtListener = null;
191 this.newtWindow = downstream;
192 this.nsHolder = downstream;
193 if( null == newtWindow.getScreen().getDisplay().getEDTUtil() ) {
194 throw new IllegalStateException("EDT not enabled");
195 }
196 this.isSetup = true;
197 return this;
198 }
199
200 /**
201 * Removes all references, downstream and NEWT-EventListener.
202 * <p>
203 * Also sets the internal <code>setup</code> flag and {@link #setConsumeAWTEvent(boolean)} to <code>false</code>.
204 * </p>
205 */
206 public synchronized AWTAdapter clear() {
207 this.newtListener = null;
208 this.newtWindow = null;
209 this.nsHolder = null;
210 this.isSetup = false;
211 this.consumeAWTEvent = false;
212 return this;
213 }
214
215 public final synchronized void setConsumeAWTEvent(final boolean v) {
216 this.consumeAWTEvent = v;
217 }
218
219 /**
220 * Returns the {@link NativeSurfaceHolder} acting {@link #AWTAdapter(com.jogamp.newt.Window) as downstream},
221 * {@link #AWTAdapter(com.jogamp.newt.event.NEWTEventListener, com.jogamp.newt.Window) NEWT window proxy}
222 * or as an {@link #AWTAdapter(com.jogamp.newt.event.NEWTEventListener, NativeSurfaceHolder) NativeSurfaceHolder proxy}.
223 * <p>
224 * Returned value is never null.
225 * </p>
226 */
227 public final synchronized NativeSurfaceHolder getNativeSurfaceHolder() {
228 return nsHolder;
229 }
230
231 /**
232 * Returns the {@link com.jogamp.newt.Window NEWT Window} acting {@link #AWTAdapter(com.jogamp.newt.Window) as downstream}
233 * or as a {@link #AWTAdapter(com.jogamp.newt.event.NEWTEventListener, com.jogamp.newt.Window) NEWT window proxy}.
234 * <p>
235 * Returned value maybe null if instance is used to be a
236 * {@link #AWTAdapter(com.jogamp.newt.event.NEWTEventListener, NativeSurfaceHolder) NativeSurfaceHolder proxy}.
237 * </p>
238 */
239 public final synchronized com.jogamp.newt.Window getNewtWindow() {
240 return newtWindow;
241 }
242
243 /**
244 * Returns the {@link com.jogamp.newt.event.NEWTEventListener NEWT event-listener} if instance
245 * is used as an {@link #AWTAdapter(com.jogamp.newt.event.NEWTEventListener, NativeSurfaceHolder) NativeSurfaceHolder proxy}
246 * or {@link #AWTAdapter(com.jogamp.newt.event.NEWTEventListener, com.jogamp.newt.Window) NEWT window proxy},
247 * otherwise method returns <code>null</code>.
248 */
250 return newtListener;
251 }
252
253 /**
254 * Due to the fact that some NEWT {@link com.jogamp.newt.event.NEWTEventListener}
255 * are mapped to more than one {@link java.util.EventListener},
256 * this method is for your convenience to use this Adapter as a listener for all types.<br>
257 * E.g. {@link com.jogamp.newt.event.MouseListener} is mapped to {@link java.awt.event.MouseListener} and {@link java.awt.event.MouseMotionListener}.
258 */
259 public abstract AWTAdapter addTo(java.awt.Component awtComponent);
260
261 /** @see #addTo(java.awt.Component) */
262 public abstract AWTAdapter removeFrom(java.awt.Component awtComponent);
263
264 /**
265 * Return value for {@link AWTAdapter#processEvent(boolean, com.jogamp.newt.event.NEWTEvent) event processing}.
266 */
267 static enum EventProcRes {
268 /** Event shall be dispatched appropriately */
269 DISPATCH,
270 /** Event has been enqueued */
271 ENQUEUED,
272 /** No known processing method applies */
273 NOP
274 }
275
276 /**
277 * Process the event.
278 * <p>
279 * If {@link #getNewtEventListener()} is not <code>null</code>,
280 * {@link EventProcRes#DISPATCH DISPATCH} is returned and caller shall dispatch the event appropriately.
281 * </p>
282 * <p>
283 * If {@link #getNewtWindow()} is not <code>null</code>,
284 * {@link EventProcRes#ENQUEUED ENQUEUED} is returned and the event has been {@link com.jogamp.newt.Window#enqueueEvent(boolean, com.jogamp.newt.event.NEWTEvent) enqueued already}.
285 * </p>
286 * <p>
287 * If none of the above matches, {@link EventProcRes#NOP NOP} is returned and none of the above processing method applies.
288 * </p>
289 *
290 * @param wait In case the event will be {@link EventProcRes#ENQUEUED ENQUEUED},
291 * passing <code>true</code> will block until the event has been processed, otherwise method returns immediately.
292 * @param event The {@link com.jogamp.newt.event.NEWTEvent event} to enqueue.
293 * @return One of the {@link EventProcRes} values, see above.
294 */
295 EventProcRes processEvent(final boolean wait, final com.jogamp.newt.event.NEWTEvent event) {
296 if(null != newtListener) {
297 return EventProcRes.DISPATCH;
298 }
299 if( null != newtWindow ) {
300 newtWindow.enqueueEvent(wait, event);
301 return EventProcRes.ENQUEUED;
302 }
303 return EventProcRes.NOP;
304 }
305}
306
abstract EDTUtil getEDTUtil()
abstract Display getDisplay()
Convenient adapter forwarding AWT events to NEWT via the event listener model.
final synchronized void setConsumeAWTEvent(final boolean v)
static final boolean DEBUG_IMPLEMENTATION
synchronized AWTAdapter setDownstream(final com.jogamp.newt.Window downstream)
Setup a pipeline adapter, AWT EventListener.
abstract AWTAdapter addTo(java.awt.Component awtComponent)
Due to the fact that some NEWT com.jogamp.newt.event.NEWTEventListener are mapped to more than one ja...
AWTAdapter(final com.jogamp.newt.Window downstream)
Create a pipeline adapter, AWT EventListener.
AWTAdapter(final com.jogamp.newt.event.NEWTEventListener newtListener, final com.jogamp.newt.Window newtProxy)
Create a proxy adapter, wrapping around an NEWT EventListener, exposed as an AWT EventListener,...
AWTAdapter(final com.jogamp.newt.event.NEWTEventListener newtListener, final NativeSurfaceHolder nsProxy)
Create a proxy adapter, wrapping around an NEWT EventListener, exposed as an AWT EventListener,...
final synchronized com.jogamp.newt.event.NEWTEventListener getNewtEventListener()
Returns the NEWT event-listener if instance is used as an NativeSurfaceHolder proxy or NEWT window pr...
synchronized AWTAdapter clear()
Removes all references, downstream and NEWT-EventListener.
abstract AWTAdapter removeFrom(java.awt.Component awtComponent)
final synchronized NativeSurfaceHolder getNativeSurfaceHolder()
Returns the NativeSurfaceHolder acting as downstream, NEWT window proxy or as an NativeSurfaceHolder ...
final synchronized com.jogamp.newt.Window getNewtWindow()
Returns the NEWT Window acting as downstream or as a NEWT window proxy.
Accessor interface for implementing classes with ownership of a NativeSurface via an is-a or has-a re...
Specifying NEWT's Window functionality:
Definition: Window.java:115
void enqueueEvent(boolean wait, com.jogamp.newt.event.NEWTEvent event)
Enqueues a NEWT event.