com.jogamp.newt.event.awt.AWTAdapter Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of jogl-all-android Show documentation
Java™ Binding for the OpenGL® API (Android)
The newest version!
/**
 * Copyright 2010 JogAmp Community. All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without modification, are
 * permitted provided that the following conditions are met:
 *
 *    1. Redistributions of source code must retain the above copyright notice, this list of
 *       conditions and the following disclaimer.
 *
 *    2. Redistributions in binary form must reproduce the above copyright notice, this list
 *       of conditions and the following disclaimer in the documentation and/or other materials
 *       provided with the distribution.
 *
 * THIS SOFTWARE IS PROVIDED BY JogAmp Community ``AS IS'' AND ANY EXPRESS OR IMPLIED
 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JogAmp Community OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 * The views and conclusions contained in the software and documentation are those of the
 * authors and should not be interpreted as representing official policies, either expressed
 * or implied, of JogAmp Community.
 */

package com.jogamp.newt.event.awt;

import com.jogamp.nativewindow.NativeSurfaceHolder;

import jogamp.newt.Debug;

/**
 * Convenient adapter forwarding AWT events to NEWT via the event listener model.

 * 
 * You may attach an instance of this adapter to an AWT Component. When an event happens,
 * it is converted to a NEWT event and the given NEWT listener is being called.

 * 
 * This adapter fullfills three use cases. First as a plain utility to write code AWT agnostic,
 * ie write an {@link com.jogamp.opengl.GLEvenListener} and some appropriate NEWT {@link com.jogamp.newt.event.NEWTEventListener}.

 * 
 * Attach the {@link com.jogamp.opengl.GLEvenListener} to a NEWT {@link com.jogamp.opengl.GLAutoDrawable}, e.g. {@link com.jogamp.newt.opengl.GLWindow},

 * or to an AWT {@link com.jogamp.opengl.GLAutoDrawable}, e.g. {@link com.jogamp.opengl.awt.GLCanvas}.

 * 

 * Attach the NEWT {@link com.jogamp.newt.event.NEWTEventListener} to a NEWT component, e.g. {@link com.jogamp.newt.Window},

 * or to an AWT component, e.g. {@link java.awt.Component}.

 * 
 * Common:

 * 
    // your demo/render code
    com.jogamp.opengl.GLEvenListener demo1 = new com.jogamp.opengl.GLEvenListener() { ... } ;

    // your AWT agnostic NEWT mouse listener code
    com.jogamp.newt.event.MouseListener mouseListener = new com.jogamp.newt.event.MouseAdapter() { ... } ;
 * 
 
 * 
 * Default NEWT use case, without using the AWTAdapter:

 * 
    // the NEWT GLAutoDrawable and Window
    GLWindow glWindow = GLWindow.create();

    // attach the renderer demo1
    glWindow.addGLEventListener(demo1);

    // attach the NEWT mouse event listener to glWindow
    glWindow.addMouseListener(mouseListener);
 * 
 
 * 
 * AWT use case, AWTAdapter used as an AWT event translator and forwarder to your NEWT listener:

 * 
    // the AWT GLAutoDrawable and Canvas
    GLCanvas glCanvas = new GLCanvas();

    // attach the renderer demo1
    glCanvas.addGLEventListener(demo1);

    // attach the AWTMouseAdapter to glCanvas, which translates and forwards events to the NEWT mouseListener
    new AWTMouseAdapter(mouseListener).addTo(glCanvas);
 * 
 
 * 
 * Previous code in detail:

 * 
    AWTMouseAdapter mouseAdapter = new AWTMouseAdapter(mouseListener);
    glCanvas.addMouseListener(mouseAdapter);
    glCanvas.addMouseMotionListener(mouseAdapter);
 * 
 
 *
 * 
 * Second use case is just a litte variation of the previous use case, where we pass a NEWT Window 

 * to be used as the source of the event.

 * 
 * 
    com.jogamp.newt.event.MouseListener mouseListener = new com.jogamp.newt.event.MouseAdapter() { ... } ;

    Component comp = ... ;                 // the AWT  component

    GLWindow glWindow = GLWindow.create(); // the NEWT component

    

    new AWTMouseAdapter(mouseListener, glWindow).addTo(comp);

 * 
 
 *
 * Last but not least, the AWTAdapter maybe used as a general AWT event forwarder to NEWT.

 *
 * 
 * 
    com.jogamp.newt.event.MouseListener mouseListener = new com.jogamp.newt.event.MouseAdapter() { ... } ;

    Component comp = ... ;                 // the AWT  component

    GLWindow glWindow = GLWindow.create(); // the NEWT component

    glWindow.addMouseListener(mouseListener); // add the custom EventListener to the NEWT component

    

    new AWTMouseAdapter(glWindow).addTo(comp); // forward all AWT events to glWindow, as NEWT events

 * 
 
 *
 * @see #attachTo
 */
public abstract class AWTAdapter implements java.util.EventListener
{
    public static final boolean DEBUG_IMPLEMENTATION = Debug.debug("Window");

    com.jogamp.newt.event.NEWTEventListener newtListener;
    com.jogamp.newt.Window newtWindow;
    NativeSurfaceHolder nsHolder;
    boolean consumeAWTEvent;
    protected boolean isSetup;

    /**
     * Create a proxy adapter, wrapping around an NEWT EventListener, exposed as an AWT EventListener,

     * where the given {@link NativeSurfaceHolder} impersonates the event's source.
     * The NEWT EventListener will be called when an event happens.

     */
    protected AWTAdapter(final com.jogamp.newt.event.NEWTEventListener newtListener, final NativeSurfaceHolder nsProxy) {
        if(null==newtListener) {
            throw new IllegalArgumentException("Argument newtListener is null");
        }
        if(null==nsProxy) {
            throw new IllegalArgumentException("Argument nwProxy is null");
        }
        this.newtListener = newtListener;
        this.newtWindow = null;
        this.nsHolder = nsProxy;
        this.consumeAWTEvent = false;
        this.isSetup = true;
    }

    /**
     * Create a proxy adapter, wrapping around an NEWT EventListener, exposed as an AWT EventListener,

     * where the given {@link com.jogamp.newt.Window NEWT Window}, a  {@link NativeSurfaceHolder}, impersonates the event's source.
     * The NEWT EventListener will be called when an event happens.

     */
    protected AWTAdapter(final com.jogamp.newt.event.NEWTEventListener newtListener, final com.jogamp.newt.Window newtProxy) {
        if(null==newtListener) {
            throw new IllegalArgumentException("Argument newtListener is null");
        }
        if(null==newtProxy) {
            throw new IllegalArgumentException("Argument newtProxy is null");
        }
        this.newtListener = newtListener;
        this.newtWindow = newtProxy;
        this.nsHolder = newtProxy;
        this.consumeAWTEvent = false;
        this.isSetup = true;
    }

    /**
     * Create a pipeline adapter, AWT EventListener.

     * Once attached to an AWT component, it sends the converted AWT events to the NEWT downstream window.

     * This is only supported with EDT enabled!
     * @throws IllegalStateException if EDT is not enabled
     */
    protected AWTAdapter(final com.jogamp.newt.Window downstream) throws IllegalStateException {
        this();
        setDownstream(downstream);
    }

    public AWTAdapter() {
        clear();
        this.consumeAWTEvent = false;
    }

    /**
     * Setup a pipeline adapter, AWT EventListener.

     * Once attached to an AWT component, it sends the converted AWT events to the NEWT downstream window.

     * This is only supported with EDT enabled!
     * @throws IllegalStateException if EDT is not enabled
     */
    public synchronized AWTAdapter setDownstream(final com.jogamp.newt.Window downstream) throws IllegalStateException {
        if(null==downstream) {
            throw new RuntimeException("Argument downstream is null");
        }
        this.newtListener = null;
        this.newtWindow = downstream;
        this.nsHolder = downstream;
        if( null == newtWindow.getScreen().getDisplay().getEDTUtil() ) {
            throw new IllegalStateException("EDT not enabled");
        }
        this.isSetup = true;
        return this;
    }

    /**
     * Removes all references, downstream and NEWT-EventListener.
     * 
     * Also sets the internal setup flag and {@link #setConsumeAWTEvent(boolean)} to false.
     * 
     */
    public synchronized AWTAdapter clear() {
        this.newtListener = null;
        this.newtWindow = null;
        this.nsHolder = null;
        this.isSetup = false;
        this.consumeAWTEvent = false;
        return this;
    }

    public final synchronized void setConsumeAWTEvent(final boolean v) {
        this.consumeAWTEvent = v;
    }

    /**
     * Returns the {@link NativeSurfaceHolder} acting {@link #AWTAdapter(com.jogamp.newt.Window) as downstream},
     * {@link #AWTAdapter(com.jogamp.newt.event.NEWTEventListener, com.jogamp.newt.Window) NEWT window proxy}
     * or as an {@link #AWTAdapter(com.jogamp.newt.event.NEWTEventListener, NativeSurfaceHolder) NativeSurfaceHolder proxy}.
     * 
     * Returned value is never null.
     * 
     */
    public final synchronized NativeSurfaceHolder getNativeSurfaceHolder() {
        return nsHolder;
    }

    /**
     * Returns the {@link com.jogamp.newt.Window NEWT Window} acting {@link #AWTAdapter(com.jogamp.newt.Window) as downstream}
     * or as a {@link #AWTAdapter(com.jogamp.newt.event.NEWTEventListener, com.jogamp.newt.Window) NEWT window proxy}.
     * 
     * Returned value maybe null if instance is used to be a
     * {@link #AWTAdapter(com.jogamp.newt.event.NEWTEventListener, NativeSurfaceHolder) NativeSurfaceHolder proxy}.
     * 
     */
    public final synchronized com.jogamp.newt.Window getNewtWindow() {
        return newtWindow;
    }

    /**
     * Returns the {@link com.jogamp.newt.event.NEWTEventListener NEWT event-listener} if instance
     * is used as an {@link #AWTAdapter(com.jogamp.newt.event.NEWTEventListener, NativeSurfaceHolder) NativeSurfaceHolder proxy}
     * or {@link #AWTAdapter(com.jogamp.newt.event.NEWTEventListener, com.jogamp.newt.Window) NEWT window proxy},
     * otherwise method returns null.
     */
    public final synchronized com.jogamp.newt.event.NEWTEventListener getNewtEventListener() {
        return newtListener;
    }

    /**
     * Due to the fact that some NEWT {@link com.jogamp.newt.event.NEWTEventListener}
     * are mapped to more than one {@link java.util.EventListener},
     * this method is for your convenience to use this Adapter as a listener for all types.

     * E.g. {@link com.jogamp.newt.event.MouseListener} is mapped to {@link java.awt.event.MouseListener} and {@link java.awt.event.MouseMotionListener}.
     */
    public abstract AWTAdapter addTo(java.awt.Component awtComponent);

    /** @see #addTo(java.awt.Component) */
    public abstract AWTAdapter removeFrom(java.awt.Component awtComponent);

    /**
     * Return value for {@link AWTAdapter#processEvent(boolean, com.jogamp.newt.event.NEWTEvent) event processing}.
     */
    static enum EventProcRes {
        /** Event shall be dispatched appropriately */
        DISPATCH,
        /** Event has been enqueued */
        ENQUEUED,
        /** No known processing method applies */
        NOP
    }

    /**
     * Process the event.
     * 
     * If {@link #getNewtEventListener()} is not null,
     * {@link EventProcRes#DISPATCH DISPATCH} is returned and caller shall dispatch the event appropriately.
     * 
     * 
     * If {@link #getNewtWindow()} is not null,
     * {@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}.
     * 
     * 
     * If none of the above matches, {@link EventProcRes#NOP NOP} is returned and none of the above processing method applies.
     * 
     *
     * @param wait In case the event will be {@link EventProcRes#ENQUEUED ENQUEUED},
     *             passing true will block until the event has been processed, otherwise method returns immediately.
     * @param event The {@link com.jogamp.newt.event.NEWTEvent event} to enqueue.
     * @return One of the {@link EventProcRes} values, see above.
     */
    EventProcRes processEvent(final boolean wait, final com.jogamp.newt.event.NEWTEvent event) {
        if(null != newtListener) {
            return EventProcRes.DISPATCH;
        }
        if( null != newtWindow ) {
            newtWindow.enqueueEvent(wait, event);
            return EventProcRes.ENQUEUED;
        }
        return EventProcRes.NOP;
    }
}