com.jogamp.newt.event.GestureHandler Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of jogl-all Show documentation
Java™ Binding for the OpenGL® API
The newest version!
/**
 * Copyright 2013 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;

import jogamp.newt.Debug;

/**
 * Generic gesture handler interface designed to allow pass-through
 * filtering of {@link InputEvent}s.
 * 
 * To avoid negative impact on event processing,
 * implementation shall restrict computation as much as possible
 * and only within it's appropriate gesture states.
 * 
 * 
 * To allow custom user events, other than the normal {@link InputEvent}s,
 * a user may return a {@link GestureEvent} in it's implementation.
 * 
 */
public interface GestureHandler {
    public static final boolean DEBUG = Debug.debug("Window.MouseEvent");

    /** A custom gesture event */
    @SuppressWarnings("serial")
    public static class GestureEvent extends InputEvent {
        /** A gesture has been detected. */
        public static final short EVENT_GESTURE_DETECTED = 400;

        private final GestureHandler handler;
        private final InputEvent ie;

        /**
         * Creates a gesture event with default type {@link #EVENT_GESTURE_DETECTED}.
         *
         * @param source
         * @param when
         * @param modifiers
         * @param handler
         * @param trigger TODO
         */
        public GestureEvent(final Object source, final long when, final int modifiers, final GestureHandler handler, final InputEvent trigger) {
            super(EVENT_GESTURE_DETECTED, source, when, modifiers);
            this.handler = handler;
            this.ie = trigger;
        }

        /**
         * Creates a gesture event with custom event_type !
         * @param event_type must lie within [400..599]
         * @param source
         * @param when
         * @param modifiers
         * @param handler
         * @param trigger TODO
         */
        public GestureEvent(final short event_type, final Object source, final long when, final int modifiers, final GestureHandler handler, final InputEvent trigger) {
            super(event_type, source, when, modifiers);
            this.handler = handler;
            this.ie = trigger;
        }

        /** Return the {@link GestureHandler}, which produced the event. */
        public final GestureHandler getHandler() { return handler; }

        /** Triggering {@link InputEvent} */
        public final InputEvent getTrigger() { return ie; }

        public String toString() {
            return "GestureEvent[handler "+handler+"]";
        }
    }

    /**
     * Listener for {@link GestureEvent}s.
     *
     * @see GestureEvent
     */
    public static interface GestureListener extends NEWTEventListener
    {
        /** {@link GestureHandler} {@link GestureHandler#hasGesture() has detected} the gesture. */
        public void gestureDetected(GestureEvent gh);
    }

    /**
     * Clears state of handler, i.e. resets all states incl. previous detected gesture.
     * @param clearStarted if true, also clears {@link #isWithinGesture() started} state,
     *                     otherwise stay within gesture - if appropriate.
     *                     Staying within a gesture allows fluent continuous gesture sequence,
     *                     e.g. for scrolling.
     */
    public void clear(boolean clearStarted);

    /**
     * Returns true if a previous {@link #process(InputEvent)} command produced a gesture,
     * which has not been {@link #clear(boolean) cleared}.
     * Otherwise returns false.
     */
    public boolean hasGesture();

    /**
     * Returns the corresponding {@link InputEvent} for the gesture as detected by
     * a previous {@link #process(InputEvent)}, which has not been {@link #clear(boolean) cleared}.
     * Otherwise returns null.
     * 
     * Only implemented for gestures mapping to {@link InputEvent}s.
     * 
     */
    public InputEvent getGestureEvent();

    /**
     * Returns true if within a gesture as detected by a previous {@link #process(InputEvent)} command,
     * which has not been {@link #clear(boolean) cleared}.
     * Otherwise returns false.
     */
    public boolean isWithinGesture();

    /**
     * Process the given {@link InputEvent} and returns true if it produced the gesture.
     * Otherwise returns false.
     * 
     * If a gesture was already detected previously and has not been cleared,
     * method does not process the event and returns true.
     * 
     * 
     * Besides validation of the event's details,
     * the handler may also validate the {@link InputEvent.InputClass} and/or {@link InputEvent.InputType}.
     * 
     */
    public boolean process(InputEvent e);
}