Jogamp
Bug 741 HiDPI: Add ScalableSurface interface to get/set pixelScale w/ full OSX impl.
[jogl.git] / src / newt / classes / com / jogamp / newt / Window.java
CommitLineData
0feca163
SG
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.
a959c53b
KR
27 */
28
2d57c252 29package com.jogamp.newt;
a959c53b 30
6ebf649d
SG
31import java.util.List;
32
e7ffa68b 33import com.jogamp.newt.Display.PointerIcon;
bc72e232 34import com.jogamp.newt.event.GestureHandler;
808a9a27 35import com.jogamp.newt.event.WindowEvent;
0feca163
SG
36import com.jogamp.newt.event.WindowListener;
37import com.jogamp.newt.event.KeyListener;
3db4e89c
SG
38import com.jogamp.newt.event.KeyEvent;
39import com.jogamp.newt.event.InputEvent;
0feca163 40import com.jogamp.newt.event.MouseListener;
bc72e232 41
360b6716 42import jogamp.newt.Debug;
808a9a27
SG
43import jogamp.newt.WindowImpl;
44
7c159772 45import javax.media.nativewindow.CapabilitiesChooser;
e4913066 46import javax.media.nativewindow.CapabilitiesImmutable;
0feca163 47import javax.media.nativewindow.NativeWindow;
2571ed0b 48import javax.media.nativewindow.ScalableSurface;
2cbab63b 49import javax.media.nativewindow.WindowClosingProtocol;
98ed02cd 50import javax.media.nativewindow.util.Rectangle;
6ebf649d 51import javax.media.nativewindow.util.RectangleImmutable;
4fe426ca 52
0feca163 53/**
20bf031d
SG
54 * Specifying NEWT's Window functionality:
55 * <ul>
56 * <li>On- and offscreen windows</li>
57 * <li>Keyboard and multi-pointer input</li>
58 * <li>Native reparenting</li>
59 * <li>Toggable fullscreen and decoration mode</li>
60 * <li>Transparency</li>
61 * <li>... and more</li>
62 * </ul>
63 * <p>
5e9c02bc
HH
64 * One use case is {@link com.jogamp.newt.opengl.GLWindow}, which delegates
65 * window operation to an instance of this interface while providing OpenGL
20bf031d
SG
66 * functionality.
67 * </p>
56d60b36
SG
68 * <p>
69 * All values of this interface are represented in window units, if not stated otherwise.
70 * </p>
71 *
72 * <a name="coordinateSystem"><h5>Coordinate System</h5></a>
73 * <p>
74 * <ul>
75 * <li>Screen space has it's origin in the top-left corner, and may not be at 0/0.</li>
76 * <li>Window origin is in it's top-left corner, see {@link #getX()} and {@link #getY()}. </li>
77 * <li>Window client-area excludes {@link #getInsets() insets}, i.e. window decoration.</li>
78 * <li>Window origin is relative to it's parent window if exist, or the screen position (top-level).</li>
79 * </ul>
80 * See {@link NativeWindow} and {@link Screen}.
81 * </p>
5a661f47
SG
82 * <a name="customwindowicons"><h5>Custom Window Icons</h5></a>
83 * <p>
84 * Custom window icons can be defined via system property <code>newt.window.icons</code>,
85 * which shall contain a space separated list of PNG icon locations from low- to high-resolution.
86 * The location must be resolvable via classpath, i.e. shall reference a location within the jar file.
87 * Example (our default):
88 * <pre>
89 * -Dnewt.window.icons="newt/data/jogamp-16x16.png newt/data/jogamp-32x32.png"
90 * -Djnlp.newt.window.icons="newt/data/jogamp-16x16.png newt/data/jogamp-32x32.png"
91 * </pre>
92 * The property can also be set programmatically, which must happen before any NEWT classes are <i>touched</i>:
93 * <pre>
94 * System.setProperty("newt.window.icons", "newt/data/jogamp-16x16.png newt/data/jogamp-32x32.png");
95 * </pre>
96 * </p>
0feca163 97 */
2571ed0b 98public interface Window extends NativeWindow, WindowClosingProtocol, ScalableSurface {
a959c53b
KR
99 public static final boolean DEBUG_MOUSE_EVENT = Debug.debug("Window.MouseEvent");
100 public static final boolean DEBUG_KEY_EVENT = Debug.debug("Window.KeyEvent");
a959c53b 101 public static final boolean DEBUG_IMPLEMENTATION = Debug.debug("Window");
a4b16ad5 102
701cc44d
SG
103 /** A 1s timeout while waiting for a native action response, ie {@link #setVisible(boolean)}. */
104 public static final long TIMEOUT_NATIVEWINDOW = 1000;
18bf27fa 105
a959c53b 106 //
0feca163 107 // Lifecycle
a959c53b
KR
108 //
109
0feca163 110 /**
0feca163 111 * @return true if the native window handle is valid and ready to operate, ie
28b0df6c 112 * if the native window has been created via {@link #setVisible(boolean) setVisible(true)}, otherwise false.
63be4a40
SG
113 *
114 * @see #setVisible(boolean)
115 * @see #destroy(boolean)
116 */
0feca163 117 boolean isNativeValid();
a959c53b 118
29b675c2 119 /**
6ebf649d 120 * @return The associated {@link Screen}
29b675c2 121 */
0feca163 122 Screen getScreen();
a959c53b 123
29b675c2 124 /**
56d60b36
SG
125 * Returns the {@link MonitorDevice} with the highest {@link MonitorDevice#getViewportInWindowUnits() viewport}
126 * {@link RectangleImmutable#coverage(RectangleImmutable) coverage} of this window.
6ebf649d 127 * <p>
5e9c02bc 128 * If no coverage is detected the first {@link MonitorDevice} is returned.
6ebf649d
SG
129 * </p>
130 */
131 MonitorDevice getMainMonitor();
5e9c02bc 132
6ebf649d 133 /**
7c159772 134 * Set the CapabilitiesChooser to help determine the native visual type.
6bff4302 135 *
7c159772
SG
136 * @param chooser the new CapabilitiesChooser
137 * @return the previous CapabilitiesChooser
138 */
139 CapabilitiesChooser setCapabilitiesChooser(CapabilitiesChooser chooser);
140
141 /**
e4913066
SV
142 * Gets an immutable set of requested capabilities.
143 *
144 * @return the requested capabilities
29b675c2 145 */
e4913066 146 CapabilitiesImmutable getRequestedCapabilities();
29b675c2 147
e4913066
SV
148 /**
149 * Gets an immutable set of chosen capabilities.
6bff4302 150 *
e4913066
SV
151 * @return the chosen capabilities
152 */
153 CapabilitiesImmutable getChosenCapabilities();
1d333a77 154
811bd23e 155 /**
808a9a27
SG
156 * {@inheritDoc}
157 * <p>
158 * Also iterates through this window's children and destroys them.
159 * </p>
160 * <p>
161 * Visibility is set to false.
162 * </p>
163 * <p>
5e9c02bc 164 * Method sends out {@link WindowEvent#EVENT_WINDOW_DESTROY_NOTIFY pre-} and
808a9a27
SG
165 * {@link WindowEvent#EVENT_WINDOW_DESTROYED post-} destruction events
166 * to all of it's {@link WindowListener}.
167 * </p>
0feca163 168 * <p>
db4d7d19
SG
169 * This method invokes {@link Screen#removeReference()} after it's own destruction,<br>
170 * which will issue {@link Screen#destroy()} if the reference count becomes 0.<br>
171 * This destruction sequence shall end up in {@link Display#destroy()}, if all reference counts become 0.
172 * </p>
808a9a27
SG
173 * <p>
174 * The Window can be recreate via {@link #setVisible(boolean) setVisible(true)}.
175 * </p>
f47230cb 176 * @see #destroy()
db4d7d19 177 * @see #setVisible(boolean)
811bd23e 178 */
6bff4302 179 @Override
0feca163 180 void destroy();
811bd23e 181
0feca163 182 /**
808a9a27
SG
183 * Set a custom action handling destruction issued by a {@link WindowImpl#windowDestroyNotify(boolean) toolkit triggered window destroy}
184 * replacing the default {@link #destroy()} action.
185 * <p>
5e9c02bc 186 * The custom action shall call {@link #destroy()}
808a9a27
SG
187 * but may perform further tasks before and after.
188 * </p>
189 */
190 void setWindowDestroyNotifyAction(Runnable r);
191
192 /**
24eab4dc
SG
193 * Calls {@link #setVisible(boolean, boolean) setVisible(true, visible)},
194 * i.e. blocks until the window becomes visible.
195 * @see #setVisible(boolean, boolean)
196 */
197 void setVisible(boolean visible);
198
199 /**
200 * <code>setVisible(..)</code> makes the window and children visible if <code>visible</code> is true,
533e072a 201 * otherwise the window and children becomes invisible.
6e599a26 202 * <p>
24eab4dc
SG
203 * <code>setVisible(wait, true)</code> is responsible to actual create the native window.
204 * </p>
205 * <p>
206 * If <code>wait</code> is true, method blocks until window is {@link #isVisible() visible} and {@link #isNativeValid() valid},
207 * otherwise method returns immediately.
533e072a 208 * </p>
6e599a26 209 * <p>
811bd23e
SG
210 * Zero size semantics are respected, see {@link #setSize(int,int)}:<br>
211 * <pre>
0feca163 212 * if ( 0 == windowHandle && visible ) {
d4670328 213 * this.visible = visible;
a3cb6bb1 214 * if( 0 &lt; width && 0 &lt; height ) {
d4670328
SG
215 * createNative();
216 * }
811bd23e 217 * } else if ( this.visible != visible ) {
d4670328
SG
218 * this.visible = visible;
219 * setNativeSizeImpl();
811bd23e
SG
220 * }
221 * </pre></p>
222 * <p>
533e072a 223 * In case this window is a child window and has a {@link javax.media.nativewindow.NativeWindow} parent,<br>
24eab4dc 224 * <code>setVisible(wait, true)</code> has no effect as long the parent's is not valid yet,
533e072a 225 * i.e. {@link javax.media.nativewindow.NativeWindow#getWindowHandle()} returns <code>null</code>.<br>
24eab4dc 226 * <code>setVisible(wait, true)</code> shall be repeated when the parent becomes valid.
533e072a 227 * </p>
6e599a26 228 */
24eab4dc 229 void setVisible(boolean wait, boolean visible);
0feca163
SG
230
231 boolean isVisible();
232
6bff4302
SG
233 /**
234 * If the implementation uses delegation, return the delegated {@link Window} instance,
76562bc5
SG
235 * otherwise return <code>this</code> instance. */
236 Window getDelegatedWindow();
6bff4302 237
0feca163
SG
238 //
239 // Child Window Management
6bff4302 240 //
0feca163 241
cb4e7318 242 boolean addChild(NativeWindow win);
0feca163 243
cb4e7318 244 boolean removeChild(NativeWindow win);
0feca163
SG
245
246 //
247 // Modes / States
248 //
76137530 249
29b675c2 250 /**
98ed02cd
SG
251 * Returns a newly created {@link Rectangle} containing window origin, {@link #getX()} & {@link #getY()},
252 * and size, {@link #getWidth()} & {@link #getHeight()}, in window units.
253 */
254 Rectangle getBounds();
255
256 /**
257 * Returns a newly created {@link Rectangle} containing the scaled window origin, {@link #getX()} & {@link #getY()},
258 * and size, {@link #getSurfaceWidth()} & {@link #getSurfaceHeight()}, in pixel units.
56d60b36
SG
259 *
260 * @deprecated The returned position in pixel units might be erroneous in case of multiple monitor setup where a mixed pixel-scale exist,
261 * since this method currently does not take the monitor viewport and each of it's pixel-scale into account (expensive).
262 * Either we fix this issue or remove this method at a later time.
98ed02cd
SG
263 */
264 Rectangle getSurfaceBounds();
265
266 /**
f9a00b91 267 * Sets the size of the window's client area in window units, excluding decorations.
6bff4302 268 *
811bd23e
SG
269 * <p>
270 * Zero size semantics are respected, see {@link #setVisible(boolean)}:<br>
271 * <pre>
a3cb6bb1 272 * if ( visible && 0 != windowHandle && ( 0 &ge; width || 0 &ge; height ) ) {
d4670328 273 * setVisible(false);
a3cb6bb1 274 * } else if ( visible && 0 == windowHandle && 0 &lt; width && 0 &lt; height ) {
d4670328 275 * setVisible(true);
811bd23e 276 * } else {
d4670328 277 * // as expected ..
811bd23e
SG
278 * }
279 * </pre></p>
280 * <p>
281 * This call is ignored if in fullscreen mode.<br></p>
76137530 282 *
f9a00b91
SG
283 * @param width of the window's client area in window units
284 * @param height of the window's client area in window units
6bff4302 285 *
fb57c652
SG
286 * @see #setSurfaceSize(int, int)
287 * @see #setTopLevelSize(int, int)
d4670328 288 * @see #getInsets()
29b675c2 289 */
0feca163
SG
290 void setSize(int width, int height);
291
292 /**
fb57c652
SG
293 * Sets the size of the window's surface in pixel units which claims the window's client area excluding decorations.
294 *
295 * <p>
296 * Zero size semantics are respected, see {@link #setVisible(boolean)}:<br>
297 * <pre>
298 * if ( visible && 0 != windowHandle && ( 0 &ge; width || 0 &ge; height ) ) {
299 * setVisible(false);
300 * } else if ( visible && 0 == windowHandle && 0 &lt; width && 0 &lt; height ) {
301 * setVisible(true);
302 * } else {
303 * // as expected ..
304 * }
305 * </pre></p>
306 * <p>
307 * This call is ignored if in fullscreen mode.<br></p>
308 *
309 * @param pixelWidth of the window's client area in pixel units
310 * @param pixelHeight of the window's client area in pixel units
311 *
312 * @see #setSize(int, int)
313 * @see #getInsets()
314 */
315 void setSurfaceSize(int pixelWidth, int pixelHeight);
316
317 /**
f9a00b91 318 * Sets the size of the top-level window including insets (window decorations) in window units.
6bff4302 319 *
7ea8aa31
SG
320 * <p>
321 * Note: Insets (if supported) are available only after the window is set visible and hence has been created.
322 * </p>
323 *
f9a00b91
SG
324 * @param width of the top-level window area in window units
325 * @param height of the top-level window area in window units
6bff4302 326 *
d4670328
SG
327 * @see #setSize(int, int)
328 * @see #getInsets()
0feca163 329 */
d4670328 330 void setTopLevelSize(int width, int height);
6bff4302 331
d4670328 332 /**
f9a00b91 333 * Sets the location of the window's client area excluding insets (window decorations) in window units.<br>
6bff4302 334 *
d4670328
SG
335 * This call is ignored if in fullscreen mode.<br>
336 *
f9a00b91
SG
337 * @param x coord of the client-area's top left corner in window units
338 * @param y coord of the client-area's top left corner in window units
6bff4302 339 *
d4670328
SG
340 * @see #getInsets()
341 */
342 void setPosition(int x, int y);
6bff4302 343
0feca163 344 /**
f9a00b91 345 * Sets the location of the top-level window inclusive insets (window decorations) in window units.<br>
6bff4302 346 *
7ea8aa31
SG
347 * <p>
348 * Note: Insets (if supported) are available only after the window is set visible and hence has been created.
349 * </p>
6bff4302 350 *
d4670328
SG
351 * This call is ignored if in fullscreen mode.<br>
352 *
f9a00b91
SG
353 * @param x coord of the top-level left corner in window units
354 * @param y coord of the top-level left corner in window units
6bff4302 355 *
d4670328
SG
356 * @see #setPosition(int, int)
357 * @see #getInsets()
0feca163 358 */
d4670328
SG
359 void setTopLevelPosition(int x, int y);
360
fb57c652
SG
361 /**
362 * Converts the given pixel units into window units <i>in place</i>.
98ed02cd 363 * @param pixelUnitsAndResult rectangle storage holding the pixel units to convert
fb57c652 364 * and the resulting conversion.
98ed02cd 365 * @return resulting rectangle storage pixelUnitsAndResult for chaining holding the converted values
fb57c652 366 */
98ed02cd 367 Rectangle convertToWindowUnits(final Rectangle pixelUnitsAndResult);
fb57c652
SG
368
369 /**
370 * Converts the given window units into pixel units <i>in place</i>.
98ed02cd 371 * @param windowUnitsAndResult rectangle storage holding the window units to convert
fb57c652 372 * and the resulting conversion.
98ed02cd 373 * @return resulting rectangle storage windowUnitsAndResult for chaining holding the converted values
fb57c652 374 */
98ed02cd 375 Rectangle convertToPixelUnits(final Rectangle windowUnitsAndResult);
fb57c652 376
d4670328 377 void setUndecorated(boolean value);
6bff4302 378
d4670328 379 boolean isUndecorated();
6bff4302 380
a245d530 381 void setAlwaysOnTop(boolean value);
6bff4302 382
a245d530 383 boolean isAlwaysOnTop();
6bff4302 384
d4670328
SG
385 void setTitle(String title);
386
387 String getTitle();
0feca163 388
646714d3 389 /** @see #setPointerVisible(boolean) */
24e0591b 390 boolean isPointerVisible();
6bff4302 391
24e0591b
SG
392 /**
393 * Makes the pointer visible or invisible.
6bff4302 394 *
24e0591b
SG
395 * @param pointerVisible defaults to <code>true</code> for platforms w/ visible pointer,
396 * otherwise defaults to <code>true</code>, eg. Android.
397 * @see #confinePointer(boolean)
398 */
399 void setPointerVisible(boolean pointerVisible);
400
e7ffa68b
SG
401 /**
402 * Returns the current {@link PointerIcon}, which maybe <code>null</code> for the default.
403 * @see #setPointerIcon(PointerIcon)
404 */
405 PointerIcon getPointerIcon();
406
407 /**
408 * @param pi Valid {@link PointerIcon} reference or <code>null</code> to reset the pointer icon to default.
409 *
410 * @see PointerIcon
411 * @see Display#createPointerIcon(com.jogamp.common.util.IOUtil.ClassResources, int, int)
412 */
413 void setPointerIcon(final PointerIcon pi);
414
646714d3 415 /** @see #confinePointer(boolean) */
24e0591b 416 boolean isPointerConfined();
6bff4302 417
24e0591b
SG
418 /**
419 * Confine the pointer to this window, ie. pointer jail.
420 * <p>
6bff4302 421 * Before jailing the mouse pointer,
600ebcac
SG
422 * the window request the focus and the pointer is centered in the window.
423 * </p>
424 * <p>
6bff4302 425 * In combination w/ {@link #warpPointer(int, int)}
24e0591b
SG
426 * and maybe {@link #setPointerVisible(boolean)} a simple mouse
427 * navigation can be realized.</p>
6bff4302 428 *
24e0591b
SG
429 * @param confine defaults to <code>false</code>.
430 */
431 void confinePointer(boolean confine);
6bff4302 432
24e0591b 433 /**
f9a00b91 434 * Moves the pointer to x/y relative to this window's origin in pixel units.
6bff4302 435 *
f9a00b91
SG
436 * @param x relative pointer x position within this window in pixel units
437 * @param y relative pointer y position within this window in pixel units
6bff4302 438 *
24e0591b
SG
439 * @see #confinePointer(boolean)
440 */
441 void warpPointer(int x, int y);
6bff4302 442
c9faebb8
SG
443 /** Reparenting operation types */
444 public enum ReparentOperation {
0feca163 445 /** No native reparenting valid */
c9faebb8 446 ACTION_INVALID,
0feca163
SG
447
448 /** No native reparenting action required, no change*/
c9faebb8 449 ACTION_NOP,
0feca163
SG
450
451 /** Native reparenting incl. Window tree */
c9faebb8 452 ACTION_NATIVE_REPARENTING,
0feca163
SG
453
454 /** Native window creation after tree change - instead of reparenting. */
c9faebb8 455 ACTION_NATIVE_CREATION,
0feca163
SG
456
457 /** Change Window tree only, native creation is pending */
6bff4302 458 ACTION_NATIVE_CREATION_PENDING;
811bd23e 459 }
0feca163 460
a00406f2
SG
461 /** Reparenting hint (bitfield value): Force destroy and hence {@link ReparentOperation#ACTION_NATIVE_CREATION re-creating} the window. */
462 public static final int REPARENT_HINT_FORCE_RECREATION = 1 << 0;
463 /** Reparenting hint (bitfield value): Claim window becomes visible after reparenting, which is important for e.g. preserving the GL-states in case window is invisible while reparenting. */
464 public static final int REPARENT_HINT_BECOMES_VISIBLE = 1 << 1;
465
0feca163
SG
466 /**
467 * Change this window's parent window.<br>
468 * <P>
469 * In case the old parent is not null and a Window,
470 * this window is removed from it's list of children.<br>
471 * In case the new parent is not null and a Window,
472 * this window is added to it's list of children.<br></P>
473 *
474 * @param newParent The new parent NativeWindow. If null, this Window becomes a top level window.
475 *
476 * @return The issued reparent action type (strategy) as defined in Window.ReparentAction
8be1fc98 477 * @see #reparentWindow(NativeWindow, int, int, boolean)
a00406f2 478 * @deprecated Use {@link #reparentWindow(NativeWindow, int, int, int)}
0feca163 479 */
c9faebb8 480 ReparentOperation reparentWindow(NativeWindow newParent);
0feca163 481
8be1fc98
SG
482 /**
483 * Change this window's parent window.<br>
484 * <P>
485 * In case the old parent is not null and a Window,
486 * this window is removed from it's list of children.<br>
487 * In case the new parent is not null and a Window,
488 * this window is added to it's list of children.<br></P>
489 *
490 * @param newParent The new parent NativeWindow. If null, this Window becomes a top level window.
491 * @param x new top-level position, use -1 for default position.
492 * @param y new top-level position, use -1 for default position.
493 * @param forceDestroyCreate if true, uses re-creation strategy for reparenting, default is <code>false</code>.
5e9c02bc 494 *
8be1fc98 495 * @return The issued reparent action type (strategy) as defined in Window.ReparentAction
a00406f2 496 * @deprecated Use {@link #reparentWindow(NativeWindow, int, int, int)}
8be1fc98
SG
497 */
498 ReparentOperation reparentWindow(NativeWindow newParent, int x, int y, boolean forceDestroyCreate);
0feca163 499
6ebf649d 500 /**
a00406f2
SG
501 * Change this window's parent window.<br>
502 * <P>
503 * In case the old parent is not null and a Window,
504 * this window is removed from it's list of children.<br>
505 * In case the new parent is not null and a Window,
506 * this window is added to it's list of children.<br></P>
507 *
508 * @param newParent The new parent NativeWindow. If null, this Window becomes a top level window.
f9a00b91
SG
509 * @param x new top-level position in window units, use -1 for default position.
510 * @param y new top-level position in window units, use -1 for default position.
a00406f2
SG
511 * @param hints May contain hints (bitfield values) like {@link #REPARENT_HINT_FORCE_RECREATION} or {@link #REPARENT_HINT_BECOMES_VISIBLE}.
512 *
513 * @return The issued reparent action type (strategy) as defined in Window.ReparentAction
514 */
515 ReparentOperation reparentWindow(NativeWindow newParent, int x, int y, int hints);
516
517 /**
6ebf649d
SG
518 * Enable or disable fullscreen mode for this window.
519 * <p>
5e9c02bc 520 * Fullscreen mode is established on the {@link #getMainMonitor() main monitor}.
6ebf649d
SG
521 * </p>
522 * @param fullscreen enable or disable fullscreen mode
523 * @return success
524 * @see #setFullscreen(List)
525 * @see #isFullscreen()
526 */
0feca163 527 boolean setFullscreen(boolean fullscreen);
6bff4302 528
6ebf649d
SG
529 /**
530 * Enable fullscreen mode for this window spanning across the given {@link MonitorDevice}s
531 * or across all {@link MonitorDevice}s.
532 * <p>
533 * Disable fullscreen via {@link #setFullscreen(boolean)}.
534 * </p>
5e9c02bc 535 * @param monitors if <code>null</code> fullscreen will be spanned across all {@link MonitorDevice}s,
6ebf649d
SG
536 * otherwise across the given list of {@link MonitorDevice}.
537 * @return success
538 * @see #setFullscreen(boolean)
539 * @see #isFullscreen()
540 */
541 boolean setFullscreen(List<MonitorDevice> monitors);
5e9c02bc 542
0feca163 543 boolean isFullscreen();
76137530 544
0feca163
SG
545 static interface FocusRunnable {
546 /**
547 * @return false if NEWT shall proceed requesting the focus,
548 * true if NEWT shall not request the focus.
549 */
550 public boolean run();
811bd23e
SG
551 }
552
0feca163 553 /**
6bff4302 554 * Sets a {@link FocusRunnable},
3db4e89c
SG
555 * which {@link FocusRunnable#run()} method is executed before the native focus is requested.
556 * <p>
0feca163
SG
557 * This allows notifying a covered window toolkit like AWT that the focus is requested,
558 * hence focus traversal can be made transparent.
3db4e89c 559 * </p>
0feca163
SG
560 */
561 void setFocusAction(FocusRunnable focusAction);
6bff4302 562
3db4e89c
SG
563 /**
564 * Sets a {@link KeyListener} allowing focus traversal with a covered window toolkit like AWT.
565 * <p>
566 * The {@link KeyListener} methods are invoked prior to all other {@link KeyListener}'s
415f5c29
SG
567 * allowing to suppress the {@link KeyEvent} via the {@link InputEvent#consumedTag}
568 * and to perform focus traversal with a 3rd party toolkit.
569 * </p>
570 * <p>
5e9c02bc 571 * The {@link KeyListener} methods are not invoked for {@link KeyEvent#isAutoRepeat() auto-repeat} events.
3db4e89c
SG
572 * </p>
573 * @param l
574 */
575 void setKeyboardFocusHandler(KeyListener l);
969e4276 576
6bff4302 577 /**
3db4e89c
SG
578 * Request focus for this native window
579 * <p>
580 * The request is handled on this Window EDT and blocked until finished.
581 * </p>
6bff4302 582 *
3db4e89c
SG
583 * @see #requestFocus(boolean)
584 */
0feca163 585 void requestFocus();
969e4276 586
6bff4302 587 /**
3db4e89c
SG
588 * Request focus for this native window
589 * <p>
6bff4302 590 * The request is handled on this Window EDT.
3db4e89c 591 * </p>
6bff4302 592 *
3db4e89c
SG
593 * @param wait true if waiting until the request is executed, otherwise false
594 * @see #requestFocus()
595 */
596 void requestFocus(boolean wait);
6bff4302 597
f9a00b91
SG
598 /**
599 * Trigger window repaint while passing the dirty region in pixel units.
600 * @param x dirty-region y-pos in pixel units
601 * @param y dirty-region x-pos in pixel units
602 * @param width dirty-region width in pixel units
603 * @param height dirty-region height in pixel units
604 */
0feca163 605 void windowRepaint(int x, int y, int width, int height);
811bd23e 606
026cade9
SG
607 /**
608 * Enqueues a {@link com.jogamp.newt.event.NEWTEvent NEWT event}.
609 * @param wait Passing <code>true</code> will block until the event has been processed, otherwise method returns immediately.
610 * @param event The {@link com.jogamp.newt.event.NEWTEvent event} to enqueue.
611 */
0feca163
SG
612 void enqueueEvent(boolean wait, com.jogamp.newt.event.NEWTEvent event);
613
614 void runOnEDTIfAvail(boolean wait, final Runnable task);
ce8c3735 615
a959c53b
KR
616
617 //
0feca163 618 // WindowListener
a959c53b 619 //
1d333a77 620
808a9a27
SG
621 /**
622 * Send a {@link WindowEvent} to all {@link WindowListener}.
5e9c02bc 623 * @param eventType a {@link WindowEvent} type, e.g. {@link WindowEvent#EVENT_WINDOW_REPAINT}.
808a9a27 624 */
0feca163 625 public void sendWindowEvent(int eventType);
1d333a77 626
0feca163 627 /**
0feca163 628 * Appends the given {@link com.jogamp.newt.event.WindowListener} to the end of
302f183c
SG
629 * the list.
630 */
0feca163 631 void addWindowListener(WindowListener l);
302f183c 632
0feca163
SG
633 /**
634 *
635 * Inserts the given {@link com.jogamp.newt.event.WindowListener} at the
302f183c 636 * specified position in the list.<br>
0feca163
SG
637 *
638 * @param index Position where the listener will be inserted.
639 * Should be within (0 <= index && index <= size()).
640 * An index value of -1 is interpreted as the end of the list, size().
302f183c
SG
641 * @param l The listener object to be inserted
642 * @throws IndexOutOfBoundsException If the index is not within (0 <= index && index <= size()), or -1
643 */
0feca163 644 void addWindowListener(int index, WindowListener l) throws IndexOutOfBoundsException;
1d333a77 645
0feca163 646 void removeWindowListener(WindowListener l);
302f183c 647
0feca163 648 WindowListener getWindowListener(int index);
a959c53b 649
0feca163 650 WindowListener[] getWindowListeners();
a959c53b
KR
651
652 //
0feca163 653 // KeyListener
a959c53b
KR
654 //
655
533e072a
SG
656 /**
657 * In case the platform supports or even requires a virtual on-screen keyboard,
658 * this method shows or hide it depending on whether <code>visible</code> is <code>true</code>
659 * or <code>false</code>.
660 * <p>
661 * One known platform where NEWT supports this feature is <code>Android</code>.
662 * </p>
663 */
664 void setKeyboardVisible(boolean visible);
1d333a77 665
6bff4302 666 /**
533e072a
SG
667 * Return <code>true</code> if the virtual on-screen keyboard is visible, otherwise <code>false</code>.
668 * <p>
669 * Currently on <code>Android</code>, the only supported platform right now,
670 * there is no way to reliably be notified of the current keyboard state.<br>
671 * It would be best, if your code does not rely on this information.
672 * </p>
673 * @see #setKeyboardVisible(boolean)
674 */
675 boolean isKeyboardVisible();
6bff4302 676
0feca163
SG
677 /**
678 *
679 * Appends the given {@link com.jogamp.newt.event.KeyListener} to the end of
302f183c
SG
680 * the list.
681 */
0feca163 682 void addKeyListener(KeyListener l);
302f183c 683
0feca163
SG
684 /**
685 *
686 * Inserts the given {@link com.jogamp.newt.event.KeyListener} at the
302f183c 687 * specified position in the list.<br>
0feca163
SG
688 *
689 * @param index Position where the listener will be inserted.
690 * Should be within (0 <= index && index <= size()).
691 * An index value of -1 is interpreted as the end of the list, size().
302f183c
SG
692 * @param l The listener object to be inserted
693 * @throws IndexOutOfBoundsException If the index is not within (0 <= index && index <= size()), or -1
694 */
0feca163 695 void addKeyListener(int index, KeyListener l);
a959c53b 696
0feca163 697 void removeKeyListener(KeyListener l);
a959c53b 698
0feca163 699 KeyListener getKeyListener(int index);
302f183c 700
0feca163 701 KeyListener[] getKeyListeners();
a959c53b 702
a959c53b
KR
703
704 //
0feca163 705 // MouseListener
a959c53b
KR
706 //
707
0feca163 708 /**
bc72e232 709 * Appends the given {@link MouseListener} to the end of the list.
302f183c 710 */
0feca163 711 void addMouseListener(MouseListener l);
302f183c 712
0feca163 713 /**
bc72e232 714 * Inserts the given {@link MouseListener} at the
302f183c 715 * specified position in the list.<br>
0feca163
SG
716 *
717 * @param index Position where the listener will be inserted.
718 * Should be within (0 <= index && index <= size()).
719 * An index value of -1 is interpreted as the end of the list, size().
302f183c
SG
720 * @param l The listener object to be inserted
721 * @throws IndexOutOfBoundsException If the index is not within (0 <= index && index <= size()), or -1
722 */
0feca163 723 void addMouseListener(int index, MouseListener l);
a959c53b 724
bc72e232
SG
725 /**
726 * Removes the given {@link MouseListener} from the list.
727 */
0feca163 728 void removeMouseListener(MouseListener l);
302f183c 729
bc72e232
SG
730 /**
731 * Returns the {@link MouseListener} from the list at the given index.
732 */
0feca163 733 MouseListener getMouseListener(int index);
17655454 734
bc72e232
SG
735 /**
736 * Returns all {@link MouseListener}
737 */
0feca163 738 MouseListener[] getMouseListeners();
5e9c02bc
HH
739
740 /** Enable or disable default {@link GestureHandler}. Default is enabled. */
bc72e232
SG
741 void setDefaultGesturesEnabled(boolean enable);
742 /** Return true if default {@link GestureHandler} are enabled. */
743 boolean areDefaultGesturesEnabled();
744 /**
745 * Appends the given {@link GestureHandler} to the end of the list.
746 */
747 void addGestureHandler(GestureHandler gh);
748 /**
749 * Inserts the given {@link GestureHandler} at the
750 * specified position in the list.<br>
751 *
752 * @param index Position where the listener will be inserted.
753 * Should be within (0 <= index && index <= size()).
754 * An index value of -1 is interpreted as the end of the list, size().
755 * @param l The listener object to be inserted
756 * @throws IndexOutOfBoundsException If the index is not within (0 <= index && index <= size()), or -1
757 */
758 void addGestureHandler(int index, GestureHandler gh);
759 /**
760 * Removes the given {@link GestureHandler} from the list.
761 */
762 void removeGestureHandler(GestureHandler gh);
763 /**
764 * Appends the given {@link GestureHandler.GestureListener} to the end of the list.
765 */
766 void addGestureListener(GestureHandler.GestureListener gl);
767 /**
768 * Inserts the given {@link GestureHandler.GestureListener} at the
769 * specified position in the list.<br>
770 *
771 * @param index Position where the listener will be inserted.
772 * Should be within (0 <= index && index <= size()).
773 * An index value of -1 is interpreted as the end of the list, size().
774 * @param l The listener object to be inserted
775 * @throws IndexOutOfBoundsException If the index is not within (0 <= index && index <= size()), or -1
776 */
777 void addGestureListener(int index, GestureHandler.GestureListener gl);
778 /**
779 * Removes the given {@link GestureHandler.GestureListener} from the list.
780 */
5e9c02bc 781 void removeGestureListener(GestureHandler.GestureListener gl);
a959c53b 782}
http://JogAmp.org git info: FAQ, tutorial and man pages.