JOGL v2.6.0-rc-20250712
JOGL, High-Performance Graphics Binding for Java™ (public API).
Window.java
Go to the documentation of this file.
1/**
2 * Copyright 2010-2023 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;
30
31import java.util.List;
32
33import com.jogamp.newt.Display.PointerIcon;
34import com.jogamp.newt.event.GestureHandler;
35import com.jogamp.newt.event.WindowEvent;
36import com.jogamp.newt.event.WindowListener;
37import com.jogamp.newt.event.KeyListener;
38import com.jogamp.newt.event.KeyEvent;
39import com.jogamp.newt.event.InputEvent;
40import com.jogamp.newt.event.MouseListener;
41
42import jogamp.newt.Debug;
43import jogamp.newt.WindowImpl;
44
45import com.jogamp.nativewindow.CapabilitiesChooser;
46import com.jogamp.nativewindow.CapabilitiesImmutable;
47import com.jogamp.nativewindow.NativeWindow;
48import com.jogamp.nativewindow.ScalableSurface;
49import com.jogamp.nativewindow.WindowClosingProtocol;
50import com.jogamp.nativewindow.util.RectangleImmutable;
51import com.jogamp.nativewindow.util.SurfaceSize;
52
53/**
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>
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
66 * functionality.
67 * </p>
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>
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 list of PNG icon locations from low- to high-resolution,
86 * separated by one whitespace or one comma character.
87 * The location must be resolvable via classpath, i.e. shall reference a location within the jar file.
88 * Example (our default):
89 * <pre>
90 * -Dnewt.window.icons="jogamp/newt/assets/jogamp-16x16.png,jogamp/newt/assets/jogamp-32x32.png"
91 * -Djnlp.newt.window.icons="jogamp/newt/assets/jogamp-16x16.png,jogamp/newt/assets/jogamp-32x32.png"
92 * </pre>
93 * The property can also be set programmatically, which must happen before any NEWT classes are <i>touched</i>:
94 * <pre>
95 * System.setProperty("newt.window.icons", "jogamp/newt/assets/jogamp-16x16.png,jogamp/newt/assets/jogamp-32x32.png");
96 * </pre>
97 * To disable even Jogamp's own window icons in favor of system icons,
98 * simply set a non-existing location, e.g.:
99 * <pre>
100 * -Dnewt.window.icons="null,null"
101 * </pre>
102 * </p>
103 *
104 * <a name="lifecycleHeavy"><h5>Use of Lifecycle Heavy functions</h5></a>
105 * <p>
106 * Some of the methods specified here are lifecycle-heavy. That is, they are able
107 * to destroy and/or reattach resources to/from the window. Because of this, the methods
108 * are <i>not safe</i> to be called from EDT related threads. For example, it is not
109 * safe for a method in an attached {@link KeyListener} to call {@link #setFullscreen(boolean)}
110 * on a {@link Window} directly. It is safe, however, for that method to spawn a background
111 * worker thread which calls the method directly. The documentation for individual methods
112 * indicates whether or not they are lifecycle-heavy.
113 * </p>
114 */
116 public static final boolean DEBUG_MOUSE_EVENT = Debug.debugExplicit("Window.MouseEvent");
117 public static final boolean DEBUG_KEY_EVENT = Debug.debugExplicit("Window.KeyEvent");
118 public static final boolean DEBUG_IMPLEMENTATION = Debug.debug("Window");
119
120 /** A 1s timeout while waiting for a native action response, ie {@link #setVisible(boolean)}. */
121 public static final long TIMEOUT_NATIVEWINDOW = 1000;
122
123 //
124 // States (keep in sync w/ src/newt/native/Window.h)
125 //
126 /**
127 * Visibility of this instance.
128 * <p>Native instance gets created at first visibility, following NEWT's lazy creation pattern.</p>
129 * <p>Changing this state is <a href="#lifecycleHeavy">lifecycle heavy</a>.</p>
130 * <p>Bit number {@value}.</p>
131 * <p>Defaults to {@code false}.</p>
132 * @see #getSupportedStateMask()
133 * @see #getStateMask()
134 * @since 2.3.2
135 */
136 public static final int STATE_BIT_VISIBLE = 0; // reconfig-flag
137 /**
138 * Hinting that no custom position has been set before first {@link #STATE_BIT_VISIBLE visibility} of this instance.
139 * <p>If kept {@code false} at creation, this allows the WM to choose the top-level window position,
140 * otherwise the custom position is being enforced.</p>
141 * <p>Bit number {@value}.</p>
142 * <p>Defaults to {@code true}.</p>
143 * @see #getSupportedStateMask()
144 * @see #getStateMask()
145 * @since 2.3.2
146 */
147 public static final int STATE_BIT_AUTOPOSITION = 1;
148 /**
149 * Set if window is a <i>child window</i>, i.e. has been {@link #reparentWindow(NativeWindow, int, int, int) reparented}.
150 * <p>
151 * Otherwise bit is cleared, i.e. window is <i>top-level</i>.
152 * </p>
153 * <p>Changing this state is <a href="#lifecycleHeavy">lifecycle heavy</a>.</p>
154 * <p>Bit number {@value}.</p>
155 * <p>Defaults to {@code false}.</p>
156 * @see #getSupportedStateMask()
157 * @see #getStateMask()
158 * @since 2.3.2
159 */
160 public static final int STATE_BIT_CHILDWIN = 2; // reconfig-flag
161 /**
162 * Set if window has <i>the input focus</i>, otherwise cleared.
163 * <p>Bit number {@value}.</p>
164 * <p>Defaults to {@code false}.</p>
165 * @see #getSupportedStateMask()
166 * @see #getStateMask()
167 * @since 2.3.2
168 */
169 public static final int STATE_BIT_FOCUSED = 3;
170 /**
171 * Set if window has <i>window decorations</i>, otherwise cleared.
172 * <p>Bit number {@value}.</p>
173 * <p>Defaults to {@code false}.</p>
174 * @see #getSupportedStateMask()
175 * @see #getStateMask()
176 * @since 2.3.2
177 */
178 public static final int STATE_BIT_UNDECORATED = 4; // reconfig-flag
179 /**
180 * Set if window is <i>always on top</i>, otherwise cleared.
181 * <p>Bit number {@value}.</p>
182 * <p>Defaults to {@code false}.</p>
183 * @see #getSupportedStateMask()
184 * @see #getStateMask()
185 * @since 2.3.2
186 */
187 public static final int STATE_BIT_ALWAYSONTOP = 5; // reconfig-flag
188 /**
189 * Set if window is <i>always on bottom</i>, otherwise cleared.
190 * <p>Bit number {@value}.</p>
191 * <p>Defaults to {@code false}.</p>
192 * @see #getSupportedStateMask()
193 * @see #getStateMask()
194 * @since 2.3.2
195 */
196 public static final int STATE_BIT_ALWAYSONBOTTOM = 6; // reconfig-flag
197 /**
198 * Set if window is <i>sticky</i>, i.e. visible <i>on all virtual desktop</i>, otherwise cleared.
199 * <p>Bit number {@value}.</p>
200 * <p>Defaults to {@code false}.</p>
201 * @see #getSupportedStateMask()
202 * @see #getStateMask()
203 * @since 2.3.2
204 */
205 public static final int STATE_BIT_STICKY = 7; // reconfig-flag
206 /**
207 * Set if window is <i>resizable</i> after creation, otherwise cleared.
208 * <p>Bit number {@value}.</p>
209 * <p>Defaults to {@code true}.</p>
210 * @see #getStateMask()
211 * @since 2.3.2
212 */
213 public static final int STATE_BIT_RESIZABLE = 8; // reconfig-flag
214 /**
215 * Set if window is <i>maximized vertically</i>, otherwise cleared.
216 * <p>Bit number {@value}.</p>
217 * <p>Defaults to {@code false}.</p>
218 * @see #getSupportedStateMask()
219 * @see #getStateMask()
220 * @since 2.3.2
221 */
222 public static final int STATE_BIT_MAXIMIZED_VERT = 9; // reconfig-flag
223 /**
224 * Set if window is <i>maximized horizontally</i>, otherwise cleared.
225 * <p>Bit number {@value}.</p>
226 * <p>Defaults to {@code false}.</p>
227 * @see #getSupportedStateMask()
228 * @see #getStateMask()
229 * @since 2.3.2
230 */
231 public static final int STATE_BIT_MAXIMIZED_HORZ = 10; // reconfig-flag
232 /**
233 * Set if window is in <i>fullscreen mode</i>, otherwise cleared.
234 * <p>
235 * Usually fullscreen mode implies {@link #STATE_BIT_UNDECORATED},
236 * however, an implementation is allowed to ignore this if unavailable.
237 * </p>
238 * <p>Bit number {@value}.</p>
239 * <p>Defaults to {@code false}.</p>
240 * @see #getSupportedStateMask()
241 * @see #getStateMask()
242 * @since 2.3.2
243 */
244 public static final int STATE_BIT_FULLSCREEN = 11; // reconfig-flag
245
246 /**
247 * Set if the <i>pointer is visible</i> when inside the window, otherwise cleared.
248 * <p>Bit number {@value}.</p>
249 * <p>Defaults to {@code true}.</p>
250 * @see #getSupportedStateMask()
251 * @see #getStateMask()
252 * @since 2.3.2
253 */
254 public static final int STATE_BIT_POINTERVISIBLE = 12;
255 /**
256 * Set if the <i>pointer is confined</i> to the window, otherwise cleared.
257 * <p>Bit number {@value}.</p>
258 * <p>Defaults to {@code false}.</p>
259 * @see #getSupportedStateMask()
260 * @see #getStateMask()
261 * @since 2.3.2
262 */
263 public static final int STATE_BIT_POINTERCONFINED = 13;
264
265 /**
266 * Set if window is <i>repositionable</i> after creation, otherwise cleared.
267 * <p>Bit number {@value}.</p>
268 * <p>Defaults to {@code true}.</p>
269 * @see #getSupportedStateMask()
270 * @see #getStateMask()
271 * @since 2.4.0
272 */
273 public static final int STATE_BIT_REPOSITIONABLE = 14; // reconfig-flag
274
275 /**
276 * Bitmask for {@link #STATE_BIT_VISIBLE}, {@value}.
277 * @see #getSupportedStateMask()
278 * @see #getStateMask()
279 * @since 2.3.2
280 */
281 public static final int STATE_MASK_VISIBLE = 1 << STATE_BIT_VISIBLE;
282 /**
283 * Bitmask for {@link #STATE_BIT_AUTOPOSITION}, {@value}.
284 * @see #getSupportedStateMask()
285 * @see #getStateMask()
286 * @since 2.3.2
287 */
288 public static final int STATE_MASK_AUTOPOSITION = 1 << STATE_BIT_AUTOPOSITION;
289 /**
290 * Bitmask for {@link #STATE_BIT_CHILDWIN}, {@value}.
291 * @see #getSupportedStateMask()
292 * @see #getStateMask()
293 * @since 2.3.2
294 */
295 public static final int STATE_MASK_CHILDWIN = 1 << STATE_BIT_CHILDWIN;
296 /**
297 * Bitmask for {@link #STATE_BIT_FOCUSED}, {@value}.
298 * @see #getSupportedStateMask()
299 * @see #getStateMask()
300 * @since 2.3.2
301 */
302 public static final int STATE_MASK_FOCUSED = 1 << STATE_BIT_FOCUSED;
303 /**
304 * Bitmask for {@link #STATE_BIT_UNDECORATED}, {@value}.
305 * @see #getSupportedStateMask()
306 * @see #getStateMask()
307 * @since 2.3.2
308 */
309 public static final int STATE_MASK_UNDECORATED = 1 << STATE_BIT_UNDECORATED;
310 /**
311 * Bitmask for {@link #STATE_BIT_ALWAYSONTOP}, {@value}.
312 * @see #getSupportedStateMask()
313 * @see #getStateMask()
314 * @since 2.3.2
315 */
316 public static final int STATE_MASK_ALWAYSONTOP = 1 << STATE_BIT_ALWAYSONTOP;
317 /**
318 * Bitmask for {@link #STATE_BIT_ALWAYSONBOTTOM}, {@value}.
319 * @see #getSupportedStateMask()
320 * @see #getStateMask()
321 * @since 2.3.2
322 */
324 /**
325 * Bitmask for {@link #STATE_BIT_STICKY}, {@value}.
326 * @see #getSupportedStateMask()
327 * @see #getStateMask()
328 * @since 2.3.2
329 */
330 public static final int STATE_MASK_STICKY = 1 << STATE_BIT_STICKY;
331 /**
332 * Bitmask for {@link #STATE_BIT_RESIZABLE}, {@value}.
333 * @see #getSupportedStateMask()
334 * @see #getStateMask()
335 * @since 2.3.2
336 */
337 public static final int STATE_MASK_RESIZABLE = 1 << STATE_BIT_RESIZABLE;
338 /**
339 * Bitmask for {@link #STATE_BIT_MAXIMIZED_VERT}, {@value}.
340 * @see #getSupportedStateMask()
341 * @see #getStateMask()
342 * @since 2.3.2
343 */
345 /**
346 * Bitmask for {@link #STATE_BIT_MAXIMIZED_HORZ}, {@value}.
347 * @see #getSupportedStateMask()
348 * @see #getStateMask()
349 * @since 2.3.2
350 */
352 /**
353 * Bitmask for {@link #STATE_BIT_FULLSCREEN}, {@value}.
354 * @see #getSupportedStateMask()
355 * @see #getStateMask()
356 * @since 2.3.2
357 */
358 public static final int STATE_MASK_FULLSCREEN = 1 << STATE_BIT_FULLSCREEN;
359 /**
360 * Bitmask for {@link #STATE_BIT_POINTERVISIBLE}, {@value}.
361 * @see #getSupportedStateMask()
362 * @see #getStateMask()
363 * @since 2.3.2
364 */
366 /**
367 * Bitmask for {@link #STATE_BIT_POINTERCONFINED}, {@value}.
368 * @see #getSupportedStateMask()
369 * @see #getStateMask()
370 * @since 2.3.2
371 */
373 /**
374 * Bitmask for {@link #STATE_BIT_REPOSITIONABLE}, {@value}.
375 * @see #getSupportedStateMask()
376 * @see #getStateMask()
377 * @since 2.4.0
378 */
380
381 /**
382 * Number of all public state bits.
383 * @see #getSupportedStateMask()
384 * @see #getStateMask()
385 * @since 2.3.2
386 */
388
389 /**
390 * Bitmask covering all public state bits.
391 * @see #getSupportedStateMask()
392 * @see #getStateMask()
393 * @since 2.3.2
394 */
396
397 /**
398 * Returns the current status mask of this instance.
399 * @see #getSupportedStateMask()
400 * @see #STATE_MASK_VISIBLE
401 * @see #STATE_MASK_AUTOPOSITION
402 * @see #STATE_MASK_CHILDWIN
403 * @see #STATE_MASK_FOCUSED
404 * @see #STATE_MASK_UNDECORATED
405 * @see #STATE_MASK_ALWAYSONTOP
406 * @see #STATE_MASK_ALWAYSONBOTTOM
407 * @see #STATE_MASK_STICKY
408 * @see #STATE_MASK_RESIZABLE
409 * @see #STATE_MASK_MAXIMIZED_VERT
410 * @see #STATE_MASK_MAXIMIZED_HORZ
411 * @see #STATE_MASK_FULLSCREEN
412 * @see #STATE_MASK_POINTERVISIBLE
413 * @see #STATE_MASK_POINTERCONFINED
414 * @see #STATE_MASK_REPOSITIONABLE
415 * @since 2.3.2
416 */
418
419 /**
420 * Returns a string representation of the {@link #getStateMask() current state mask}.
421 * @since 2.3.2
422 */
424
425 /**
426 * Returns the supported {@link #getStateMask() state mask} of the implementation.
427 * <p>
428 * Implementation provides supported {@link #getStateMask() state mask} values at runtime
429 * <i>after</i> native window creation, i.e. first visibility.
430 * </p>
431 * <p>
432 * Please note that a window's size shall also be allowed to change, i.e. {@link #setSize(int, int)}.
433 * </p>
434 * <p>
435 * Default minimum value is {@link #STATE_MASK_VISIBLE} | {@link #STATE_MASK_FOCUSED},
436 * i.e. the <b>minimum requirement</b> for all implementations.
437 * </p>
438 * <p>
439 * Usual desktop minimum value is {@link #STATE_MASK_VISIBLE} | {@link #STATE_MASK_FOCUSED} | {@link STATE_MASK_FULLSCREEN} | {@link STATE_MASK_RESIZABLE} | {@link STATE_MASK_REPOSITIONABLE}.
440 * </p>
441 * <p>
442 * Before native window creation {@link #getStatePublicBitmask()} is returned,
443 * i.e. it is assumed all features are supported.
444 * </p>
445 * <p>
446 * Semantic of the supported state-mask bits (after native creation, i.e. 1st visibility):
447 * <ul>
448 * <li>{@link #STATE_MASK_VISIBLE}: {@link #setVisible(boolean) Visibility} can be toggled. <b>Minimum requirement</b>.</li>
449 * <li>{@link #STATE_MASK_CHILDWIN}: {@link #reparentWindow(NativeWindow, int, int, int) Native window parenting} is supported.</li>
450 * <li>{@link #STATE_MASK_FOCUSED}: Window {@link #requestFocus() focus management} is supported. <b>Minimum requirement</b>.</li>
451 * <li>{@link #STATE_MASK_UNDECORATED}: {@link #setUndecorated(boolean) Window decoration} can be toggled.</li>
452 * <li>{@link #STATE_MASK_ALWAYSONTOP}: Window can be set {@link #setAlwaysOnTop(boolean) always-on-top}. </li>
453 * <li>{@link #STATE_MASK_ALWAYSONBOTTOM}: Window can be set {@link #setAlwaysOnBottom(boolean) always-on-bottom}. </li>
454 * <li>{@link #STATE_MASK_STICKY}: Window can be set {@link #setSticky(boolean) sticky}.</li>
455 * <li>{@link #STATE_MASK_RESIZABLE}: Window {@link #setResizable(boolean) resizability} can be toggled and it's {@link #setSize(int, int) size} can be changed.</li>
456 * <li>{@link #STATE_MASK_MAXIMIZED_VERT}: Window can be {@link #setMaximized(boolean, boolean) maximized-vertically}. </li>
457 * <li>{@link #STATE_MASK_MAXIMIZED_HORZ}: Window can be {@link #setMaximized(boolean, boolean) maximized-horizontally}. </li>
458 * <li>{@link #STATE_MASK_FULLSCREEN}: Window {@link #setFullscreen(boolean) fullscreen} can be toggled. </li>
459 * <li>{@link #STATE_MASK_POINTERVISIBLE}: Window {@link #setPointerVisible(boolean) pointer visibility} can be toggled. </li>
460 * <li>{@link #STATE_MASK_POINTERCONFINED}: Window {@link #confinePointer(boolean) pointer can be confined}. </li>
461 * <li>{@link #STATE_MASK_REPOSITIONABLE}: Window {@link #setPosition(int, int) position} can be changed.</li>
462 * </ul>
463 * </p>
464 * @see #getStateMask()
465 * @since 2.3.2
466 */
468
469 /**
470 * Returns a string representation of the {@link #getSupportedStateMask() supported state mask}.
471 * @since 2.3.2
472 */
474
475 //
476 // Lifecycle
477 //
478
479 /**
480 * @return true if the native window handle is valid and ready to operate, ie
481 * if the native window has been created via {@link #setVisible(boolean) setVisible(true)}, otherwise false.
482 *
483 * @see #setVisible(boolean)
484 * @see #destroy(boolean)
485 */
486 boolean isNativeValid();
487
488 /**
489 * @return The associated {@link Screen}
490 */
492
493 /**
494 * Returns the {@link MonitorDevice} with the highest {@link MonitorDevice#getViewportInWindowUnits() viewport}
495 * {@link RectangleImmutable#coverage(RectangleImmutable) coverage} of this window.
496 * <p>
497 * If no coverage is detected the first {@link MonitorDevice} is returned.
498 * </p>
499 */
501
502 /**
503 * Set the CapabilitiesChooser to help determine the native visual type.
504 *
505 * @param chooser the new CapabilitiesChooser
506 * @return the previous CapabilitiesChooser
507 */
509
510 /**
511 * Gets an immutable set of requested capabilities.
512 *
513 * @return the requested capabilities
514 */
516
517 /**
518 * Gets an immutable set of chosen capabilities.
519 *
520 * @return the chosen capabilities
521 */
523
524 /**
525 * {@inheritDoc}
526 * <p>
527 * Also iterates through this window's children and destroys them.
528 * </p>
529 * <p>
530 * Visibility is set to false.
531 * </p>
532 * <p>
533 * Method sends out {@link WindowEvent#EVENT_WINDOW_DESTROY_NOTIFY pre-} and
534 * {@link WindowEvent#EVENT_WINDOW_DESTROYED post-} destruction events
535 * to all of it's {@link WindowListener}.
536 * </p>
537 * <p>
538 * This method invokes {@link Screen#removeReference()} after it's own destruction,<br>
539 * which will issue {@link Screen#destroy()} if the reference count becomes 0.<br>
540 * This destruction sequence shall end up in {@link Display#destroy()}, if all reference counts become 0.
541 * </p>
542 * <p>
543 * The Window can be recreate via {@link #setVisible(boolean) setVisible(true)}.
544 * </p>
545 * <p>This method is <a href="#lifecycleHeavy">lifecycle heavy</a>.</p>
546 * @see #destroy()
547 * @see #setVisible(boolean)
548 */
549 @Override
550 void destroy();
551
552 /**
553 * Set a custom action handling destruction issued by a {@link WindowImpl#windowDestroyNotify(boolean) toolkit triggered window destroy}
554 * replacing the default {@link #destroy()} action.
555 * <p>
556 * The custom action shall call {@link #destroy()}
557 * but may perform further tasks before and after.
558 * </p>
559 */
561
562 /**
563 * Calls {@link #setVisible(boolean, boolean) setVisible(true, visible)},
564 * i.e. blocks until the window becomes visible.
565 * <p>This method is <a href="#lifecycleHeavy">lifecycle heavy</a>.</p>
566 * @see #setVisible(boolean, boolean)
567 * @see #STATE_BIT_VISIBLE
568 */
569 void setVisible(boolean visible);
570
571 /**
572 * <code>setVisible(..)</code> makes the window and children visible if <code>visible</code> is true,
573 * otherwise the window and children becomes invisible.
574 * <p>Native instance gets created at first visibility, following NEWT's lazy creation pattern.</p>
575 * <p>
576 * If <code>wait</code> is true, method blocks until window is {@link #isVisible() visible} and {@link #isNativeValid() valid},
577 * otherwise method returns immediately.
578 * </p>
579 * <p>
580 * Zero size semantics are respected, see {@link #setSize(int,int)}:<br>
581 * <pre>
582 * if ( 0 == windowHandle && visible ) {
583 * this.visible = visible;
584 * if( 0 &lt; width && 0 &lt; height ) {
585 * createNative();
586 * }
587 * } else if ( this.visible != visible ) {
588 * this.visible = visible;
589 * setNativeSizeImpl();
590 * }
591 * </pre></p>
592 * <p>
593 * In case this window is {@link #isChildWindow() a child window} and has a {@link com.jogamp.nativewindow.NativeWindow} parent,<br>
594 * <code>setVisible(wait, true)</code> has no effect as long the parent's is not valid yet,
595 * i.e. {@link com.jogamp.nativewindow.NativeWindow#getWindowHandle()} returns <code>null</code>.<br>
596 * <code>setVisible(wait, true)</code> shall be repeated when the parent becomes valid.
597 * </p>
598 * <p>This method is <a href="#lifecycleHeavy">lifecycle heavy</a>.</p>
599 * @see #STATE_BIT_VISIBLE
600 */
601 void setVisible(boolean wait, boolean visible);
602
603 /**
604 * @see #STATE_BIT_VISIBLE
605 * @see #setVisible(boolean, boolean)
606 */
607 boolean isVisible();
608
609 /**
610 * If the implementation uses delegation, return the delegated {@link Window} instance,
611 * otherwise return <code>this</code> instance. */
613
614 //
615 // Child Window Management
616 //
617
618 boolean addChild(NativeWindow win);
619
621
622 //
623 // Modes / States
624 //
625
626 /**
627 * Returns the <i>pixels per millimeter</i> of this window's {@link NativeSurface}
628 * according to the {@link #getMainMonitor() main monitor}'s <i>current</i> {@link MonitorMode mode}'s
629 * {@link SurfaceSize#getResolution() surface resolution}.
630 * <p>
631 * Method takes the {@link #getCurrentSurfaceScale(float[]) current surface-scale} and {@link #getMaximumSurfaceScale(float[]) native surface-scale}
632 * into account, i.e.:
633 * <pre>
634 * surfacePpMM = monitorPpMM * currentSurfaceScale / nativeSurfaceScale,
635 * with PpMM == pixel per millimeter
636 * </pre>
637 * </p>
638 * <p>
639 * To convert the result to <i>dpi</i>, i.e. dots-per-inch, multiply both components with <code>25.4f</code>.
640 * </p>
641 * @param ppmmStore float[2] storage for the ppmm result
642 * @return the passed storage containing the ppmm for chaining
643 */
644 float[] getPixelsPerMM(final float[] ppmmStore);
645
646 /**
647 * Sets the size of the window's client area in window units, excluding decorations.
648 *
649 * <p>
650 * Zero size semantics are respected, see {@link #setVisible(boolean)}:<br>
651 * <pre>
652 * if ( visible && 0 != windowHandle && ( 0 &ge; width || 0 &ge; height ) ) {
653 * setVisible(false);
654 * } else if ( visible && 0 == windowHandle && 0 &lt; width && 0 &lt; height ) {
655 * setVisible(true);
656 * } else {
657 * // as expected ..
658 * }
659 * </pre></p>
660 * <p>
661 * This call is ignored if in fullscreen mode.<br></p>
662 *
663 * @param width of the window's client area in window units
664 * @param height of the window's client area in window units
665 *
666 * @see {@link #STATE_BIT_RESIZABLE}
667 * @see {@link #STATE_MASK_RESIZABLE}
668 * @see #setSurfaceSize(int, int)
669 * @see #setTopLevelSize(int, int)
670 * @see #getInsets()
671 */
672 void setSize(int width, int height);
673
674 /**
675 * Sets the size of the window's surface in pixel units which claims the window's client area excluding decorations.
676 *
677 * <p>
678 * In multiple monitor mode, setting the window's surface size in pixel units
679 * might not be possible due to unknown <i>scale</i> values of the target display.
680 * Hence re-setting the pixel unit size after window creation is recommended.
681 * </p>
682 * <p>
683 * Zero size semantics are respected, see {@link #setVisible(boolean)}:<br>
684 * <pre>
685 * if ( visible && 0 != windowHandle && ( 0 &ge; width || 0 &ge; height ) ) {
686 * setVisible(false);
687 * } else if ( visible && 0 == windowHandle && 0 &lt; width && 0 &lt; height ) {
688 * setVisible(true);
689 * } else {
690 * // as expected ..
691 * }
692 * </pre></p>
693 * <p>
694 * This call is ignored if in fullscreen mode.<br></p>
695 *
696 * @param pixelWidth of the window's client area in pixel units
697 * @param pixelHeight of the window's client area in pixel units
698 *
699 * @see #setSize(int, int)
700 * @see #getInsets()
701 */
702 void setSurfaceSize(int pixelWidth, int pixelHeight);
703
704 /**
705 * Sets the size of the top-level window including insets (window decorations) in window units.
706 *
707 * <p>
708 * Note: Insets (if supported) are available only after the window is set visible and hence has been created.
709 * </p>
710 *
711 * @param width of the top-level window area in window units
712 * @param height of the top-level window area in window units
713 *
714 * @see #setSize(int, int)
715 * @see #getInsets()
716 */
717 void setTopLevelSize(int width, int height);
718
719 /**
720 * Sets the location of the window's client area excluding insets (window decorations) in window units.<br>
721 *
722 * This call is ignored if in fullscreen mode.<br>
723 *
724 * @param x coord of the client-area's top left corner in window units
725 * @param y coord of the client-area's top left corner in window units
726 *
727 * @see #getInsets()
728 */
729 void setPosition(int x, int y);
730
731 /**
732 * Sets the location of the top-level window inclusive insets (window decorations) in window units.<br>
733 *
734 * <p>
735 * Note: Insets (if supported) are available only after the window is set visible and hence has been created.
736 * </p>
737 *
738 * This call is ignored if in fullscreen mode.<br>
739 *
740 * @param x coord of the top-level left corner in window units
741 * @param y coord of the top-level left corner in window units
742 *
743 * @see #setPosition(int, int)
744 * @see #getInsets()
745 */
746 void setTopLevelPosition(int x, int y);
747
748 /**
749 * @see {@link #STATE_BIT_UNDECORATED}
750 * @see {@link #STATE_MASK_UNDECORATED}
751 */
752 void setUndecorated(boolean value);
753 /**
754 * @see {@link #STATE_BIT_UNDECORATED}
755 * @see {@link #STATE_MASK_UNDECORATED}
756 */
757 boolean isUndecorated();
758
759 /**
760 * <p>Operation is ignored if this instance {@link #isChildWindow() is a child window}.</p>
761 * @see {@link #STATE_BIT_ALWAYSONTOP}
762 * @see {@link #STATE_MASK_ALWAYSONTOP}
763 */
764 void setAlwaysOnTop(boolean value);
765 /**
766 * @see {@link #STATE_BIT_ALWAYSONTOP}
767 * @see {@link #STATE_MASK_ALWAYSONTOP}
768 */
769 boolean isAlwaysOnTop();
770
771 /**
772 * <p>Operation is ignored if this instance {@link #isChildWindow() is a child window}.</p>
773 * @see {@link #STATE_BIT_ALWAYSONBOTTOM}
774 * @see {@link #STATE_MASK_ALWAYSONBOTTOM}
775 * @since 2.3.2
776 */
777 void setAlwaysOnBottom(boolean value);
778 /**
779 * @see {@link #STATE_BIT_ALWAYSONBOTTOM}
780 * @see {@link #STATE_MASK_ALWAYSONBOTTOM}
781 * @since 2.3.2
782 */
784
785 /**
786 * <p>Operation is ignored if this instance {@link #isChildWindow() is a child window}.</p>
787 * @see {@link #STATE_BIT_RESIZABLE}
788 * @see {@link #STATE_MASK_RESIZABLE}
789 * @since 2.3.2
790 */
791 void setResizable(final boolean value);
792 /**
793 * @see {@link #STATE_BIT_RESIZABLE}
794 * @see {@link #STATE_MASK_RESIZABLE}
795 * @since 2.3.2
796 */
797 boolean isResizable();
798
799 /**
800 * <p>Operation is ignored if this instance {@link #isChildWindow() is a child window}.</p>
801 * @see {@link #STATE_BIT_STICKY}
802 * @see {@link #STATE_MASK_STICKY}
803 * @since 2.3.2
804 */
805 void setSticky(final boolean value);
806 /**
807 * @see {@link #STATE_BIT_STICKY}
808 * @see {@link #STATE_MASK_STICKY}
809 * @since 2.3.2
810 */
811 boolean isSticky();
812
813 /**
814 * <p>Operation is ignored if this instance {@link #isChildWindow() is a child window}.</p>
815 * @see {@link #STATE_BIT_MAXIMIZED_HORZ}
816 * @see {@link #STATE_BIT_MAXIMIZED_VERT}
817 * @see {@link #STATE_MASK_MAXIMIZED_HORZ}
818 * @see {@link #STATE_MASK_MAXIMIZED_VERT}
819 * @since 2.3.2
820 */
821 void setMaximized(final boolean horz, final boolean vert);
822 /**
823 * @see {@link #STATE_BIT_MAXIMIZED_VERT}
824 * @see {@link #STATE_MASK_MAXIMIZED_VERT}
825 * @since 2.3.2
826 */
828 /**
829 * @see {@link #STATE_BIT_MAXIMIZED_HORZ}
830 * @see {@link #STATE_MASK_MAXIMIZED_HORZ}
831 * @since 2.3.2
832 */
834
835 void setTitle(String title);
836
837 String getTitle();
838
839 /** @see #setPointerVisible(boolean) */
841
842 /**
843 * Makes the pointer visible or invisible.
844 *
845 * @param pointerVisible defaults to <code>true</code> for platforms w/ visible pointer,
846 * otherwise defaults to <code>true</code>, eg. Android.
847 * @see #confinePointer(boolean)
848 */
849 void setPointerVisible(boolean pointerVisible);
850
851 /**
852 * Returns the current {@link PointerIcon}, which maybe <code>null</code> for the default.
853 * @see #setPointerIcon(PointerIcon)
854 */
856
857 /**
858 * @param pi Valid {@link PointerIcon} reference or <code>null</code> to reset the pointer icon to default.
859 *
860 * @see PointerIcon
861 * @see Display#createPointerIcon(com.jogamp.common.util.IOUtil.ClassResources, int, int)
862 */
864
865 /** @see #confinePointer(boolean) */
867
868 /**
869 * Confine the pointer to this window, ie. pointer jail.
870 * <p>
871 * Before jailing the mouse pointer,
872 * the window request the focus and the pointer is centered in the window.
873 * </p>
874 * <p>
875 * In combination w/ {@link #warpPointer(int, int)}
876 * and maybe {@link #setPointerVisible(boolean)} a simple mouse
877 * navigation can be realized.</p>
878 *
879 * @param confine defaults to <code>false</code>.
880 */
881 void confinePointer(boolean confine);
882
883 /**
884 * Moves the pointer to x/y relative to this window's origin in pixel units.
885 *
886 * @param x relative pointer x position within this window in pixel units
887 * @param y relative pointer y position within this window in pixel units
888 *
889 * @see #confinePointer(boolean)
890 */
891 void warpPointer(int x, int y);
892
893 /** Reparenting operation types */
894 public enum ReparentOperation {
895 /** No native reparenting valid */
897
898 /** No native reparenting action required, no change*/
900
901 /** Native reparenting incl. Window tree */
903
904 /** Native window creation after tree change - instead of reparenting. */
906
907 /** Change Window tree only, native creation is pending */
909 }
910
911 /** Reparenting hint (bitfield value): Force destroy and hence {@link ReparentOperation#ACTION_NATIVE_CREATION re-creating} the window. */
912 public static final int REPARENT_HINT_FORCE_RECREATION = 1 << 0;
913 /** 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. */
914 public static final int REPARENT_HINT_BECOMES_VISIBLE = 1 << 1;
915
916 /**
917 * Change this window's parent window.<br>
918 * <P>
919 * In case the old parent is not null and a Window,
920 * this window is removed from it's list of children.<br>
921 * In case the new parent is not null and a Window,
922 * this window is added to it's list of children.<br></P>
923 * <p>This method is <a href="#lifecycleHeavy">lifecycle heavy</a>.</p>
924 *
925 * @param newParent The new parent NativeWindow. If null, this Window becomes a top level window.
926 * @param x new top-level position in window units, use -1 for default position.
927 * @param y new top-level position in window units, use -1 for default position.
928 * @param hints May contain hints (bitfield values) like {@link #REPARENT_HINT_FORCE_RECREATION} or {@link #REPARENT_HINT_BECOMES_VISIBLE}.
929 *
930 * @return The issued reparent action type (strategy) as defined in Window.ReparentAction
931 */
932 ReparentOperation reparentWindow(NativeWindow newParent, int x, int y, int hints);
933
934 /**
935 * Returns {@code true} if this window is a child window,
936 * i.e. has been {@link #reparentWindow(NativeWindow, int, int, int) reparented}.
937 * <p>
938 * Otherwise return {@code false}, i.e. this window is a top-level window.
939 * </p>
940 */
941 boolean isChildWindow();
942
943 /**
944 * Enable or disable fullscreen mode for this window.
945 * <p>
946 * Fullscreen mode is established on the {@link #getMainMonitor() main monitor}.
947 * </p>
948 * <p>This method is <a href="#lifecycleHeavy">lifecycle heavy</a>.</p>
949 * @param fullscreen enable or disable fullscreen mode
950 * @return success
951 * @see #setFullscreen(List)
952 * @see #isFullscreen()
953 */
954 boolean setFullscreen(boolean fullscreen);
955
956 /**
957 * Enable fullscreen mode for this window spanning across the given {@link MonitorDevice}s
958 * or across all {@link MonitorDevice}s.
959 * <p>
960 * Disable fullscreen via {@link #setFullscreen(boolean)}.
961 * </p>
962 * <p>This method is <a href="#lifecycleHeavy">lifecycle heavy</a>.</p>
963 * @param monitors if <code>null</code> fullscreen will be spanned across all {@link MonitorDevice}s,
964 * otherwise across the given list of {@link MonitorDevice}.
965 * @return success
966 * @see #setFullscreen(boolean)
967 * @see #isFullscreen()
968 */
969 boolean setFullscreen(List<MonitorDevice> monitors);
970
971 boolean isFullscreen();
972
973 static interface FocusRunnable {
974 /**
975 * @return false if NEWT shall proceed requesting the focus,
976 * true if NEWT shall not request the focus.
977 */
978 public boolean run();
979 }
980
981 /**
982 * Sets a {@link FocusRunnable},
983 * which {@link FocusRunnable#run()} method is executed before the native focus is requested.
984 * <p>
985 * This allows notifying a covered window toolkit like AWT that the focus is requested,
986 * hence focus traversal can be made transparent.
987 * </p>
988 */
989 void setFocusAction(FocusRunnable focusAction);
990
991 /**
992 * Sets a {@link KeyListener} allowing focus traversal with a covered window toolkit like AWT.
993 * <p>
994 * The {@link KeyListener} methods are invoked prior to all other {@link KeyListener}'s
995 * allowing to suppress the {@link KeyEvent} via the {@link InputEvent#consumedTag}
996 * and to perform focus traversal with a 3rd party toolkit.
997 * </p>
998 * <p>
999 * The {@link KeyListener} methods are not invoked for {@link KeyEvent#isAutoRepeat() auto-repeat} events.
1000 * </p>
1001 * @param l
1002 */
1004
1005 /**
1006 * Request focus for this native window
1007 * <p>
1008 * The request is handled on this Window EDT and blocked until finished.
1009 * </p>
1010 *
1011 * @see #requestFocus(boolean)
1012 */
1014
1015 /**
1016 * Request focus for this native window
1017 * <p>
1018 * The request is handled on this Window EDT.
1019 * </p>
1020 *
1021 * @param wait true if waiting until the request is executed, otherwise false
1022 * @see #requestFocus()
1023 */
1024 void requestFocus(boolean wait);
1025
1026 /**
1027 * Trigger window repaint while passing the dirty region in pixel units.
1028 * @param x dirty-region y-pos in pixel units
1029 * @param y dirty-region x-pos in pixel units
1030 * @param width dirty-region width in pixel units
1031 * @param height dirty-region height in pixel units
1032 * @return true if window {@link #isNativeValid()}
1033 */
1034 boolean windowRepaint(int x, int y, int width, int height);
1035
1036 /**
1037 * Enqueues a {@link com.jogamp.newt.event.NEWTEvent NEWT event}.
1038 * @param wait Passing <code>true</code> will block until the event has been processed, otherwise method returns immediately.
1039 * @param event The {@link com.jogamp.newt.event.NEWTEvent event} to enqueue.
1040 */
1041 void enqueueEvent(boolean wait, com.jogamp.newt.event.NEWTEvent event);
1042
1043 void runOnEDTIfAvail(boolean wait, final Runnable task);
1044
1045 /**
1046 * Appends this class simple string one-line representation to the given {@link StringBuilder} instance
1047 * @param sb given instance where this class simple string representation is added to
1048 * @return the given {@link StringBuilder} for chaining
1049 */
1050 StringBuilder toSimpleString(StringBuilder sb);
1051
1052 /**
1053 * Returns a simple string one-line representation of this instance using {@link #toSimpleString(StringBuilder)}.
1054 */
1056
1057 /**
1058 * Appends this class full string multi-line representation to the given {@link StringBuilder} instance
1059 * @param sb given instance where this class full string representation is added to
1060 * @return the given {@link StringBuilder} for chaining
1061 */
1062 StringBuilder toString(StringBuilder sb);
1063
1064 /**
1065 * Returns a full string multi-line representation of this instance using {@link #toString(StringBuilder)}.
1066 * <p>
1067 * {@inheritDoc}
1068 * </p>
1069 */
1070 @Override
1071 String toString();
1072
1073 //
1074 // WindowListener
1075 //
1076
1077 /**
1078 * Send a {@link WindowEvent} to all {@link WindowListener}.
1079 * @param eventType a {@link WindowEvent} type, e.g. {@link WindowEvent#EVENT_WINDOW_REPAINT}.
1080 */
1081 public void sendWindowEvent(int eventType);
1082
1083 /**
1084 * Appends the given {@link com.jogamp.newt.event.WindowListener} to the end of
1085 * the list.
1086 */
1088
1089 /**
1090 *
1091 * Inserts the given {@link com.jogamp.newt.event.WindowListener} at the
1092 * specified position in the list.<br>
1093 *
1094 * @param index Position where the listener will be inserted.
1095 * Should be within (0 <= index && index <= size()).
1096 * An index value of -1 is interpreted as the end of the list, size().
1097 * @param l The listener object to be inserted
1098 * @throws IndexOutOfBoundsException If the index is not within (0 <= index && index <= size()), or -1
1099 */
1100 void addWindowListener(int index, WindowListener l) throws IndexOutOfBoundsException;
1101
1103
1105
1107
1108 //
1109 // KeyListener
1110 //
1111
1112 /**
1113 * In case the platform supports or even requires a virtual on-screen keyboard,
1114 * this method shows or hide it depending on whether <code>visible</code> is <code>true</code>
1115 * or <code>false</code>.
1116 * <p>
1117 * One known platform where NEWT supports this feature is <code>Android</code>.
1118 * </p>
1119 */
1120 void setKeyboardVisible(boolean visible);
1121
1122 /**
1123 * Return <code>true</code> if the virtual on-screen keyboard is visible, otherwise <code>false</code>.
1124 * <p>
1125 * Currently on <code>Android</code>, the only supported platform right now,
1126 * there is no way to reliably be notified of the current keyboard state.<br>
1127 * It would be best, if your code does not rely on this information.
1128 * </p>
1129 * @see #setKeyboardVisible(boolean)
1130 */
1132
1133 /**
1134 *
1135 * Appends the given {@link com.jogamp.newt.event.KeyListener} to the end of
1136 * the list.
1137 */
1139
1140 /**
1141 *
1142 * Inserts the given {@link com.jogamp.newt.event.KeyListener} at the
1143 * specified position in the list.<br>
1144 *
1145 * @param index Position where the listener will be inserted.
1146 * Should be within (0 <= index && index <= size()).
1147 * An index value of -1 is interpreted as the end of the list, size().
1148 * @param l The listener object to be inserted
1149 * @throws IndexOutOfBoundsException If the index is not within (0 <= index && index <= size()), or -1
1150 */
1151 void addKeyListener(int index, KeyListener l);
1152
1154
1156
1158
1159
1160 //
1161 // MouseListener
1162 //
1163
1164 /**
1165 * Appends the given {@link MouseListener} to the end of the list.
1166 */
1168
1169 /**
1170 * Inserts the given {@link MouseListener} at the
1171 * specified position in the list.<br>
1172 *
1173 * @param index Position where the listener will be inserted.
1174 * Should be within (0 <= index && index <= size()).
1175 * An index value of -1 is interpreted as the end of the list, size().
1176 * @param l The listener object to be inserted
1177 * @throws IndexOutOfBoundsException If the index is not within (0 <= index && index <= size()), or -1
1178 */
1180
1181 /**
1182 * Removes the given {@link MouseListener} from the list.
1183 */
1185
1186 /**
1187 * Returns the {@link MouseListener} from the list at the given index.
1188 */
1190
1191 /**
1192 * Returns all {@link MouseListener}
1193 */
1195
1196 /** Enable or disable default {@link GestureHandler}. Default is enabled. */
1197 void setDefaultGesturesEnabled(boolean enable);
1198 /** Return true if default {@link GestureHandler} are enabled. */
1200 /**
1201 * Appends the given {@link GestureHandler} to the end of the list.
1202 */
1204 /**
1205 * Inserts the given {@link GestureHandler} at the
1206 * specified position in the list.<br>
1207 *
1208 * @param index Position where the listener will be inserted.
1209 * Should be within (0 <= index && index <= size()).
1210 * An index value of -1 is interpreted as the end of the list, size().
1211 * @param l The listener object to be inserted
1212 * @throws IndexOutOfBoundsException If the index is not within (0 <= index && index <= size()), or -1
1213 */
1215 /**
1216 * Removes the given {@link GestureHandler} from the list.
1217 */
1219 /**
1220 * Appends the given {@link GestureHandler.GestureListener} to the end of the list.
1221 */
1223 /**
1224 * Inserts the given {@link GestureHandler.GestureListener} at the
1225 * specified position in the list.<br>
1226 *
1227 * @param index Position where the listener will be inserted.
1228 * Should be within (0 <= index && index <= size()).
1229 * An index value of -1 is interpreted as the end of the list, size().
1230 * @param l The listener object to be inserted
1231 * @throws IndexOutOfBoundsException If the index is not within (0 <= index && index <= size()), or -1
1232 */
1234 /**
1235 * Removes the given {@link GestureHandler.GestureListener} from the list.
1236 */
1238}
Visual output device, i.e.
A screen may span multiple MonitorDevices representing their combined virtual size.
Definition: Screen.java:58
Reparenting operation types.
Definition: Window.java:894
ACTION_NATIVE_CREATION
Native window creation after tree change - instead of reparenting.
Definition: Window.java:905
ACTION_NATIVE_CREATION_PENDING
Change Window tree only, native creation is pending.
Definition: Window.java:908
ACTION_NOP
No native reparenting action required, no change.
Definition: Window.java:899
ACTION_INVALID
No native reparenting valid.
Definition: Window.java:896
ACTION_NATIVE_REPARENTING
Native reparenting incl.
Definition: Window.java:902
Provides a mechanism by which applications can customize the window type selection for a given Capabi...
Specifies an immutable set of capabilities that a window's rendering context must support,...
Extend the NativeSurface interface with windowing information such as window-handle,...
Adding mutable surface pixel scale property to implementing class, usually to a NativeSurface impleme...
Protocol for handling window closing events.
Native PointerIcon handle.
Definition: Display.java:92
Specifying NEWT's Window functionality:
Definition: Window.java:115
void confinePointer(boolean confine)
Confine the pointer to this window, ie.
Window getDelegatedWindow()
If the implementation uses delegation, return the delegated Window instance, otherwise return this in...
static final boolean DEBUG_MOUSE_EVENT
Definition: Window.java:116
boolean removeChild(NativeWindow win)
static final int STATE_BIT_UNDECORATED
Set if window has window decorations, otherwise cleared.
Definition: Window.java:178
static final int STATE_BIT_FULLSCREEN
Set if window is in fullscreen mode, otherwise cleared.
Definition: Window.java:244
int getStatePublicBitmask()
Bitmask covering all public state bits.
boolean areDefaultGesturesEnabled()
Return true if default GestureHandler are enabled.
void addGestureListener(GestureHandler.GestureListener gl)
Appends the given GestureHandler.GestureListener to the end of the list.
void requestFocus(boolean wait)
Request focus for this native window.
void sendWindowEvent(int eventType)
Send a WindowEvent to all WindowListener.
void setKeyboardFocusHandler(KeyListener l)
Sets a KeyListener allowing focus traversal with a covered window toolkit like AWT.
void setPointerVisible(boolean pointerVisible)
Makes the pointer visible or invisible.
void addKeyListener(KeyListener l)
Appends the given com.jogamp.newt.event.KeyListener to the end of the list.
static final int STATE_BIT_ALWAYSONTOP
Set if window is always on top, otherwise cleared.
Definition: Window.java:187
static final int STATE_MASK_ALWAYSONTOP
Bitmask for STATE_BIT_ALWAYSONTOP, {@value}.
Definition: Window.java:316
String getSupportedStateMaskString()
Returns a string representation of the supported state mask.
boolean isAlwaysOnBottom()
void addGestureHandler(int index, GestureHandler gh)
Inserts the given GestureHandler at the specified position in the list.
static final boolean DEBUG_KEY_EVENT
Definition: Window.java:117
static final int STATE_BIT_POINTERCONFINED
Set if the pointer is confined to the window, otherwise cleared.
Definition: Window.java:263
void setTitle(String title)
boolean addChild(NativeWindow win)
static final int STATE_MASK_FOCUSED
Bitmask for STATE_BIT_FOCUSED, {@value}.
Definition: Window.java:302
PointerIcon getPointerIcon()
Returns the current PointerIcon, which maybe null for the default.
static final int STATE_MASK_RESIZABLE
Bitmask for STATE_BIT_RESIZABLE, {@value}.
Definition: Window.java:337
KeyListener[] getKeyListeners()
static final int STATE_MASK_REPOSITIONABLE
Bitmask for STATE_BIT_REPOSITIONABLE, {@value}.
Definition: Window.java:379
static final int STATE_MASK_POINTERCONFINED
Bitmask for STATE_BIT_POINTERCONFINED, {@value}.
Definition: Window.java:372
MouseListener[] getMouseListeners()
Returns all MouseListener.
KeyListener getKeyListener(int index)
static final long TIMEOUT_NATIVEWINDOW
A 1s timeout while waiting for a native action response, ie setVisible(boolean).
Definition: Window.java:121
ReparentOperation reparentWindow(NativeWindow newParent, int x, int y, int hints)
Change this window's parent window.
void setTopLevelPosition(int x, int y)
Sets the location of the top-level window inclusive insets (window decorations) in window units.
static final int STATE_BIT_ALWAYSONBOTTOM
Set if window is always on bottom, otherwise cleared.
Definition: Window.java:196
void setAlwaysOnBottom(boolean value)
StringBuilder toSimpleString(StringBuilder sb)
Appends this class simple string one-line representation to the given StringBuilder instance.
int getSupportedStateMask()
Returns the supported state mask of the implementation.
static final int REPARENT_HINT_BECOMES_VISIBLE
Reparenting hint (bitfield value): Claim window becomes visible after reparenting,...
Definition: Window.java:914
static final int STATE_MASK_CHILDWIN
Bitmask for STATE_BIT_CHILDWIN, {@value}.
Definition: Window.java:295
WindowListener[] getWindowListeners()
static final int STATE_MASK_POINTERVISIBLE
Bitmask for STATE_BIT_POINTERVISIBLE, {@value}.
Definition: Window.java:365
static final int REPARENT_HINT_FORCE_RECREATION
Reparenting hint (bitfield value): Force destroy and hence re-creating the window.
Definition: Window.java:912
int getStateMask()
Returns the current status mask of this instance.
CapabilitiesImmutable getChosenCapabilities()
Gets an immutable set of chosen capabilities.
void addWindowListener(WindowListener l)
Appends the given com.jogamp.newt.event.WindowListener to the end of the list.
CapabilitiesChooser setCapabilitiesChooser(CapabilitiesChooser chooser)
Set the CapabilitiesChooser to help determine the native visual type.
boolean windowRepaint(int x, int y, int width, int height)
Trigger window repaint while passing the dirty region in pixel units.
void setSticky(final boolean value)
void setDefaultGesturesEnabled(boolean enable)
Enable or disable default GestureHandler.
void addMouseListener(int index, MouseListener l)
Inserts the given MouseListener at the specified position in the list.
static final boolean DEBUG_IMPLEMENTATION
Definition: Window.java:118
void setAlwaysOnTop(boolean value)
static final int STATE_BIT_AUTOPOSITION
Hinting that no custom position has been set before first visibility of this instance.
Definition: Window.java:147
static final int STATE_BIT_FOCUSED
Set if window has the input focus, otherwise cleared.
Definition: Window.java:169
void requestFocus()
Request focus for this native window.
boolean setFullscreen(List< MonitorDevice > monitors)
Enable fullscreen mode for this window spanning across the given MonitorDevices or across all Monitor...
boolean isPointerConfined()
void removeGestureHandler(GestureHandler gh)
Removes the given GestureHandler from the list.
static final int STATE_MASK_UNDECORATED
Bitmask for STATE_BIT_UNDECORATED, {@value}.
Definition: Window.java:309
void setMaximized(final boolean horz, final boolean vert)
static final int STATE_BIT_MAXIMIZED_VERT
Set if window is maximized vertically, otherwise cleared.
Definition: Window.java:222
void setTopLevelSize(int width, int height)
Sets the size of the top-level window including insets (window decorations) in window units.
void addWindowListener(int index, WindowListener l)
Inserts the given com.jogamp.newt.event.WindowListener at the specified position in the list.
void setResizable(final boolean value)
String toSimpleString()
Returns a simple string one-line representation of this instance using toSimpleString(StringBuilder).
void setFocusAction(FocusRunnable focusAction)
Sets a FocusRunnable, which FocusRunnable#run() method is executed before the native focus is request...
void removeKeyListener(KeyListener l)
void setWindowDestroyNotifyAction(Runnable r)
Set a custom action handling destruction issued by a toolkit triggered window destroy replacing the d...
void setSize(int width, int height)
Sets the size of the window's client area in window units, excluding decorations.
static final int STATE_BIT_POINTERVISIBLE
Set if the pointer is visible when inside the window, otherwise cleared.
Definition: Window.java:254
MouseListener getMouseListener(int index)
Returns the MouseListener from the list at the given index.
static final int STATE_MASK_MAXIMIZED_VERT
Bitmask for STATE_BIT_MAXIMIZED_VERT, {@value}.
Definition: Window.java:344
WindowListener getWindowListener(int index)
void setVisible(boolean visible)
Calls setVisible(true, visible), i.e.
boolean setFullscreen(boolean fullscreen)
Enable or disable fullscreen mode for this window.
float[] getPixelsPerMM(final float[] ppmmStore)
Returns the pixels per millimeter of this window's NativeSurface according to the main monitor's curr...
static final int STATE_MASK_STICKY
Bitmask for STATE_BIT_STICKY, {@value}.
Definition: Window.java:330
void addMouseListener(MouseListener l)
Appends the given MouseListener to the end of the list.
MonitorDevice getMainMonitor()
Returns the MonitorDevice with the highest viewport coverage of this window.
boolean isPointerVisible()
void enqueueEvent(boolean wait, com.jogamp.newt.event.NEWTEvent event)
Enqueues a NEWT event.
boolean isKeyboardVisible()
Return true if the virtual on-screen keyboard is visible, otherwise false.
static final int STATE_BIT_CHILDWIN
Set if window is a child window, i.e.
Definition: Window.java:160
void setPosition(int x, int y)
Sets the location of the window's client area excluding insets (window decorations) in window units.
static final int STATE_MASK_VISIBLE
Bitmask for STATE_BIT_VISIBLE, {@value}.
Definition: Window.java:281
void warpPointer(int x, int y)
Moves the pointer to x/y relative to this window's origin in pixel units.
static final int STATE_BIT_MAXIMIZED_HORZ
Set if window is maximized horizontally, otherwise cleared.
Definition: Window.java:231
static final int STATE_BIT_STICKY
Set if window is sticky, i.e.
Definition: Window.java:205
void setKeyboardVisible(boolean visible)
In case the platform supports or even requires a virtual on-screen keyboard, this method shows or hid...
CapabilitiesImmutable getRequestedCapabilities()
Gets an immutable set of requested capabilities.
void removeWindowListener(WindowListener l)
int getStatePublicBitCount()
Number of all public state bits.
void setPointerIcon(final PointerIcon pi)
void setSurfaceSize(int pixelWidth, int pixelHeight)
Sets the size of the window's surface in pixel units which claims the window's client area excluding ...
static final int STATE_BIT_RESIZABLE
Set if window is resizable after creation, otherwise cleared.
Definition: Window.java:213
void addGestureListener(int index, GestureHandler.GestureListener gl)
Inserts the given GestureHandler.GestureListener at the specified position in the list.
void removeGestureListener(GestureHandler.GestureListener gl)
Removes the given GestureHandler.GestureListener from the list.
String getStateMaskString()
Returns a string representation of the current state mask.
static final int STATE_MASK_ALWAYSONBOTTOM
Bitmask for STATE_BIT_ALWAYSONBOTTOM, {@value}.
Definition: Window.java:323
void setUndecorated(boolean value)
static final int STATE_BIT_REPOSITIONABLE
Set if window is repositionable after creation, otherwise cleared.
Definition: Window.java:273
String toString()
Returns a full string multi-line representation of this instance using toString(StringBuilder).
void destroy()
Destroys this window incl.releasing all related resources.
void addGestureHandler(GestureHandler gh)
Appends the given GestureHandler to the end of the list.
void setVisible(boolean wait, boolean visible)
setVisible(..) makes the window and children visible if visible is true, otherwise the window and chi...
static final int STATE_MASK_FULLSCREEN
Bitmask for STATE_BIT_FULLSCREEN, {@value}.
Definition: Window.java:358
static final int STATE_MASK_AUTOPOSITION
Bitmask for STATE_BIT_AUTOPOSITION, {@value}.
Definition: Window.java:288
void removeMouseListener(MouseListener l)
Removes the given MouseListener from the list.
StringBuilder toString(StringBuilder sb)
Appends this class full string multi-line representation to the given StringBuilder instance.
void addKeyListener(int index, KeyListener l)
Inserts the given com.jogamp.newt.event.KeyListener at the specified position in the list.
boolean isChildWindow()
Returns true if this window is a child window, i.e.
static final int STATE_BIT_VISIBLE
Visibility of this instance.
Definition: Window.java:136
void runOnEDTIfAvail(boolean wait, final Runnable task)
static final int STATE_MASK_MAXIMIZED_HORZ
Bitmask for STATE_BIT_MAXIMIZED_HORZ, {@value}.
Definition: Window.java:351
Generic gesture handler interface designed to allow pass-through filtering of InputEvents.
Listener for KeyEvents.