JOGL v2.6.0-rc-20250706
JOGL, High-Performance Graphics Binding for Java™ (public API).
NativeWindow.java
Go to the documentation of this file.
1/*
2 * Copyright (c) 2003 Sun Microsystems, Inc. All Rights Reserved.
3 * Copyright (c) 2010 JogAmp Community. All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions are
7 * met:
8 *
9 * - Redistribution of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 *
12 * - Redistribution in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
15 *
16 * Neither the name of Sun Microsystems, Inc. or the names of
17 * contributors may be used to endorse or promote products derived from
18 * this software without specific prior written permission.
19 *
20 * This software is provided "AS IS," without a warranty of any kind. ALL
21 * EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES,
22 * INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A
23 * PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE HEREBY EXCLUDED. SUN
24 * MICROSYSTEMS, INC. ("SUN") AND ITS LICENSORS SHALL NOT BE LIABLE FOR
25 * ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR
26 * DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES. IN NO EVENT WILL SUN OR
27 * ITS LICENSORS BE LIABLE FOR ANY LOST REVENUE, PROFIT OR DATA, OR FOR
28 * DIRECT, INDIRECT, SPECIAL, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE
29 * DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY,
30 * ARISING OUT OF THE USE OF OR INABILITY TO USE THIS SOFTWARE, EVEN IF
31 * SUN HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
32 *
33 * You acknowledge that this software is not designed or intended for use
34 * in the design, construction, operation or maintenance of any nuclear
35 * facility.
36 *
37 * Sun gratefully acknowledges that this software was originally authored
38 * and developed by Kenneth Bradley Russell and Christopher John Kline.
39 */
40
41package com.jogamp.nativewindow;
42
43import com.jogamp.nativewindow.util.InsetsImmutable;
44import com.jogamp.nativewindow.util.Point;
45import com.jogamp.nativewindow.util.Rectangle;
46
47/**
48 * Extend the {@link NativeSurface} interface with windowing
49 * information such as {@link #getWindowHandle() window-handle},
50 * {@link #getWidth() window-size} and {@link #getX() window-position}.
51 * <p>
52 * All values of this interface are represented in window units, if not stated otherwise.
53 * See {@link NativeSurface}.
54 * </p>
55 *
56 * <a name="coordinateSystem"><h5>Coordinate System</h5></a>
57 * <p>
58 * <ul>
59 * <li>Abstract screen space has it's origin in the top-left corner, and may not be at 0/0.</li>
60 * <li>Window origin is in it's top-left corner, see {@link #getX()} and {@link #getY()}. </li>
61 * <li>Window client-area excludes {@link #getInsets() insets}, i.e. window decoration.</li>
62 * <li>Window origin is relative to it's parent window if exist, or the screen position (top-level).</li>
63 * </ul>
64 * </p>
65 * <p>
66 * A window toolkit such as the AWT may either implement this interface
67 * directly with one of its components, or provide and register an
68 * implementation of {@link NativeWindowFactory NativeWindowFactory}
69 * which can create NativeWindow objects for its components.
70 * </p>
71 */
73
74 /**
75 * {@inheritDoc}
76 * <p>
77 * Returns this instance, which <i>is-a</i> {@link NativeSurface}.
78 * </p>
79 */
80 @Override
82
83 /**
84 * Destroys this window incl. releasing all related resources.
85 */
86 public void destroy();
87
88 /**
89 * @return The parent NativeWindow, or null if this NativeWindow is top level.
90 */
92
93 /**
94 * Returns the window handle for this NativeWindow. <P>
95 *
96 * The window handle shall reflect the platform one
97 * for all window related operations, e.g. open, close, resize. <P>
98 *
99 * On X11 this returns an entity of type Window. <BR>
100 * On Microsoft Windows this returns an entity of type HWND.
101 */
102 public long getWindowHandle();
103
104 /**
105 * Returns the insets defined as the width and height of the window decoration
106 * on the left, right, top and bottom in window units.
107 * <p>
108 * Insets are zero if the window is undecorated, including child windows.
109 * </p>
110 *
111 * <p>
112 * Insets are available only after the native window has been created,
113 * ie. the native window has been made visible.<br>
114 *
115 * The top-level window area's top-left corner is located at
116 * <pre>
117 * {@link #getX()} - getInsets().{@link InsetsImmutable#getLeftWidth() getLeftWidth()}
118 * {@link #getY()} - getInsets().{@link InsetsImmutable#getTopHeight() getTopHeight()}
119 * </pre>
120 *
121 * The top-level window size is
122 * <pre>
123 * {@link #getWidth()} + getInsets().{@link InsetsImmutable#getTotalWidth() getTotalWidth()}
124 * {@link #getHeight()} + getInsets().{@link InsetsImmutable#getTotalHeight() getTotalHeight()}
125 * </pre>
126 *
127 * @return insets
128 */
130
131 /** Returns the current x position of this window, relative to it's parent. */
132
133 /**
134 * Returns the x position of the top-left corner
135 * of the client area relative to it's parent in window units.
136 * <p>
137 * If no parent exist (top-level window), this coordinate equals the screen coordinate.
138 * </p>
139 * <p>
140 * Since the position reflects the client area, it does not include the insets.
141 * </p>
142 * <p>
143 * See <a href="#coordinateSystem"> Coordinate System</a>.
144 * </p>
145 * @see #getInsets()
146 * @see #getLocationOnScreen(Point)
147 */
148 public int getX();
149
150 /**
151 * Returns the current y position of the top-left corner
152 * of the client area relative to it's parent in window units.
153 * <p>
154 * If no parent exist (top-level window), this coordinate equals the screen coordinate.
155 * </p>
156 * <p>
157 * Since the position reflects the client area, it does not include the insets.
158 * </p>
159 * <p>
160 * See <a href="#coordinateSystem"> Coordinate System</a>.
161 * </p>
162 * @see #getInsets()
163 * @see #getLocationOnScreen(Point)
164 */
165 public int getY();
166
167 /**
168 * Returns the width of the client area excluding insets (window decorations) in window units.
169 * @return width of the client area in window units
170 * @see NativeSurface#getSurfaceWidth()
171 */
172 public int getWidth();
173
174 /**
175 * Returns the height of the client area excluding insets (window decorations) in window units.
176 * @return height of the client area in window units
177 * @see NativeSurface#getSurfaceHeight()
178 */
179 public int getHeight();
180
181 /**
182 * Returns a newly created {@link Rectangle} containing window origin, {@link #getX()} & {@link #getY()},
183 * and size, {@link #getWidth()} & {@link #getHeight()}, in window units.
184 */
186
187 /**
188 * Returns a newly created {@link Rectangle} containing window's surface origin and size in pixel units.
189 */
191
192 /**
193 * Returns the window's top-left client-area position in the screen.
194 * <p>
195 * If {@link Point} is not <code>null</code>, it is translated about the resulting screen position
196 * and returned.
197 * </p>
198 * <p>
199 * See <a href="#coordinateSystem"> Coordinate System</a>.
200 * </p>
201 * <p>
202 * Since the position reflects the client area, it does not include the insets.
203 * </p>
204 * @param point Optional {@link Point} storage.
205 * If not null, <code>null</code>, it is translated about the resulting screen position
206 * and returned.
207 * @see #getX()
208 * @see #getY()
209 * @see #getInsets()
210 */
212
213 /** Returns true if this native window owns the focus, otherwise false. */
214 boolean hasFocus();
215
216}
Accessor interface for implementing classes with ownership of a NativeSurface via an is-a or has-a re...
Provides low-level information required for hardware-accelerated rendering using a surface in a platf...
Extend the NativeSurface interface with windowing information such as window-handle,...
NativeSurface getNativeSurface()
Returns the associated NativeSurface of this NativeSurfaceHolder.
void destroy()
Destroys this window incl.
int getHeight()
Returns the height of the client area excluding insets (window decorations) in window units.
Rectangle getSurfaceBounds()
Returns a newly created Rectangle containing window's surface origin and size in pixel units.
Point getLocationOnScreen(Point point)
Returns the window's top-left client-area position in the screen.
boolean hasFocus()
Returns true if this native window owns the focus, otherwise false.
int getY()
Returns the current y position of the top-left corner of the client area relative to it's parent in w...
Rectangle getBounds()
Returns a newly created Rectangle containing window origin, getX() & getY(), and size,...
InsetsImmutable getInsets()
Returns the insets defined as the width and height of the window decoration on the left,...
int getX()
Returns the current x position of this window, relative to it's parent.
int getWidth()
Returns the width of the client area excluding insets (window decorations) in window units.
long getWindowHandle()
Returns the window handle for this NativeWindow.
Immutable insets representing rectangular window decoration insets on all four edges in window units.