JOGL v2.6.0-rc-20250706
JOGL, High-Performance Graphics Binding for Java™ (public API).
GestureHandler.java
Go to the documentation of this file.
1/**
2 * Copyright 2013 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 */
28package com.jogamp.newt.event;
29
30import jogamp.newt.Debug;
31
32/**
33 * Generic gesture handler interface designed to allow pass-through
34 * filtering of {@link InputEvent}s.
35 * <p>
36 * To avoid negative impact on event processing,
37 * implementation shall restrict computation as much as possible
38 * and only within it's appropriate gesture states.
39 * </p>
40 * <p>
41 * To allow custom user events, other than the <i>normal</i> {@link InputEvent}s,
42 * a user may return a {@link GestureEvent} in it's implementation.
43 * </p>
44 */
45public interface GestureHandler {
46 public static final boolean DEBUG = Debug.debug("Window.MouseEvent");
47
48 /** A custom gesture event */
49 @SuppressWarnings("serial")
50 public static class GestureEvent extends InputEvent {
51 /** A gesture has been detected. */
52 public static final short EVENT_GESTURE_DETECTED = 400;
53
54 private final GestureHandler handler;
55 private final InputEvent ie;
56
57 /**
58 * Creates a gesture event with default type {@link #EVENT_GESTURE_DETECTED}.
59 *
60 * @param source
61 * @param when
62 * @param modifiers
63 * @param handler
64 * @param trigger TODO
65 */
66 public GestureEvent(final Object source, final long when, final int modifiers, final GestureHandler handler, final InputEvent trigger) {
67 super(EVENT_GESTURE_DETECTED, source, when, modifiers);
68 this.handler = handler;
69 this.ie = trigger;
70 }
71
72 /**
73 * Creates a gesture event with custom <i>event_type</i> !
74 * @param event_type must lie within [400..599]
75 * @param source
76 * @param when
77 * @param modifiers
78 * @param handler
79 * @param trigger TODO
80 */
81 public GestureEvent(final short event_type, final Object source, final long when, final int modifiers, final GestureHandler handler, final InputEvent trigger) {
82 super(event_type, source, when, modifiers);
83 this.handler = handler;
84 this.ie = trigger;
85 }
86
87 /** Return the {@link GestureHandler}, which produced the event. */
88 public final GestureHandler getHandler() { return handler; }
89
90 /** Triggering {@link InputEvent} */
91 public final InputEvent getTrigger() { return ie; }
92
93 public String toString() {
94 return "GestureEvent[handler "+handler+"]";
95 }
96 }
97
98 /**
99 * Listener for {@link GestureEvent}s.
100 *
101 * @see GestureEvent
102 */
103 public static interface GestureListener extends NEWTEventListener
104 {
105 /** {@link GestureHandler} {@link GestureHandler#hasGesture() has detected} the gesture. */
107 }
108
109 /**
110 * Clears state of handler, i.e. resets all states incl. previous detected gesture.
111 * @param clearStarted if true, also clears {@link #isWithinGesture() started} state,
112 * otherwise stay within gesture - if appropriate.
113 * Staying within a gesture allows fluent continuous gesture sequence,
114 * e.g. for scrolling.
115 */
116 public void clear(boolean clearStarted);
117
118 /**
119 * Returns true if a previous {@link #process(InputEvent)} command produced a gesture,
120 * which has not been {@link #clear(boolean) cleared}.
121 * Otherwise returns false.
122 */
123 public boolean hasGesture();
124
125 /**
126 * Returns the corresponding {@link InputEvent} for the gesture as detected by
127 * a previous {@link #process(InputEvent)}, which has not been {@link #clear(boolean) cleared}.
128 * Otherwise returns null.
129 * <p>
130 * Only implemented for gestures mapping to {@link InputEvent}s.
131 * </p>
132 */
134
135 /**
136 * Returns true if within a gesture as detected by a previous {@link #process(InputEvent)} command,
137 * which has not been {@link #clear(boolean) cleared}.
138 * Otherwise returns false.
139 */
140 public boolean isWithinGesture();
141
142 /**
143 * Process the given {@link InputEvent} and returns true if it produced the gesture.
144 * Otherwise returns false.
145 * <p>
146 * If a gesture was already detected previously and has not been cleared,
147 * method does not process the event and returns true.
148 * </p>
149 * <p>
150 * Besides validation of the event's details,
151 * the handler may also validate the {@link InputEvent.InputClass} and/or {@link InputEvent.InputType}.
152 * </p>
153 */
154 public boolean process(InputEvent e);
155}
GestureEvent(final short event_type, final Object source, final long when, final int modifiers, final GestureHandler handler, final InputEvent trigger)
Creates a gesture event with custom event_type !
final InputEvent getTrigger()
Triggering InputEvent.
final GestureHandler getHandler()
Return the GestureHandler, which produced the event.
GestureEvent(final Object source, final long when, final int modifiers, final GestureHandler handler, final InputEvent trigger)
Creates a gesture event with default type EVENT_GESTURE_DETECTED.
void gestureDetected(GestureEvent gh)
GestureHandler has detected the gesture.
Generic gesture handler interface designed to allow pass-through filtering of InputEvents.
boolean isWithinGesture()
Returns true if within a gesture as detected by a previous process(InputEvent) command,...
void clear(boolean clearStarted)
Clears state of handler, i.e.
InputEvent getGestureEvent()
Returns the corresponding InputEvent for the gesture as detected by a previous process(InputEvent),...
boolean process(InputEvent e)
Process the given InputEvent and returns true if it produced the gesture.
boolean hasGesture()
Returns true if a previous process(InputEvent) command produced a gesture, which has not been cleared...