1 <!-- |
|
2 Copyright (c) 2005, 2017, Oracle and/or its affiliates. All rights reserved. |
|
3 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
|
4 |
|
5 This code is free software; you can redistribute it and/or modify it |
|
6 under the terms of the GNU General Public License version 2 only, as |
|
7 published by the Free Software Foundation. |
|
8 |
|
9 This code is distributed in the hope that it will be useful, but WITHOUT |
|
10 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
|
11 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
|
12 version 2 for more details (a copy is included in the LICENSE file that |
|
13 accompanied this code). |
|
14 |
|
15 You should have received a copy of the GNU General Public License version |
|
16 2 along with this work; if not, write to the Free Software Foundation, |
|
17 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
|
18 |
|
19 Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
|
20 or visit www.oracle.com if you need additional information or have any |
|
21 questions. |
|
22 --> |
|
23 <?xml version="1.0" encoding="utf-8"?> |
|
24 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" |
|
25 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
|
26 <html lang="en-US" xmlns="http://www.w3.org/1999/xhtml" xml:lang= |
|
27 "en-US"> |
|
28 <head> |
|
29 <title>Java AWT Native Interface Specification and Guide</title> |
|
30 </head> |
|
31 <body> |
|
32 <h2>The Java AWT Native Interface Specification and Guide</h2> |
|
33 <h3>Introduction</h3> |
|
34 <p>The Java AWT Native Interface (JAWT) comprises a small set of native |
|
35 (eg C language-based) APIs that provide a standard supported way |
|
36 for interaction between Java API windows and surfaces, and |
|
37 platform native API windows and surfaces. |
|
38 Non-Java libraries may then render to a Java owned window. |
|
39 <p> |
|
40 Note: in this document the terms "Java AWT Native Interface", |
|
41 "AWT Native Interface" and "JAWT" are interchangeable and |
|
42 refer to this same specification. |
|
43 <p> |
|
44 The fundamental obstacle to native rendering without JAWT is that |
|
45 is that the rendering code cannot identify where to draw. |
|
46 The native code needs access to information about a Java |
|
47 drawing surface (such as a handle to the underlying native ID of a |
|
48 <tt>Canvas</tt>), but cannot get it.</p> |
|
49 Without that information (ie without JAWT) an application could |
|
50 use native rendering only by creating its own top-level window |
|
51 not shared at all with Java. This is unacceptable for most uses. |
|
52 Except for usage via JAWT, this is considered to be entirely |
|
53 internal to the Java platform implementation: private, unsupported |
|
54 and undocumented. |
|
55 <p> |
|
56 JAWT should be supported in all headful implementations |
|
57 where technically possible although this is not enforced by the JCK. |
|
58 There is a platform-specific and a platform |
|
59 independent portion to the API, to account for the differing |
|
60 data structures and requirements of each platform. |
|
61 This document specifies the platform independent portions and |
|
62 also documents the platform dependent portions for the Oracle JDK |
|
63 supported desktop operating environments. |
|
64 For AWT the term platform is less tied to the underlying operating |
|
65 system than it is to the desktop windowing environment. |
|
66 <p> |
|
67 Reasons for using the AWT Native Interface include |
|
68 <ul> |
|
69 <li>Use of a 3rd party native library not available in Java |
|
70 <li>A temporary porting aid before converting legacy code to Java |
|
71 <li>Rendering performance available only to native hardware accelerated APIs |
|
72 <li>Interoperation with another toolkit |
|
73 </ul> |
|
74 <p> |
|
75 Drawbacks include |
|
76 <ul> |
|
77 <li>A more complex application implementation, eg for painting |
|
78 <li>Potential for application instability if the native library does |
|
79 not interoperate properly with AWT. |
|
80 <li>Increased application delivery complexity - per platform binaries |
|
81 </ul> |
|
82 The header file <a href="#jawt.h"> "jawt.h"</a> |
|
83 in the Appendix fully specifies the APIs provided by JAWT. |
|
84 <p> |
|
85 An example illustrating how easy it is to use the AWT Native Interface |
|
86 is presented and discussed later in this document.</p> |
|
87 |
|
88 <p><b>JAWT usage depends on JNI</b></p> |
|
89 <p>The definition of Java Standard Edition includes JNI, the Java |
|
90 Native Interface. Many Java developers will never need to use it, |
|
91 but the interface is the only standard supported way for a Java |
|
92 language program to interact directly with |
|
93 application code that has been compiled to the native machine |
|
94 instructions for the host processor architecture. |
|
95 JNI is used where ever there is a need for mixed languages. |
|
96 These are by no means limited to cases like AWT. For example, you |
|
97 could use JNI to integrate with native code that communicates with |
|
98 a peripheral device, such as a scanner, connected to a system via a |
|
99 USB port.</p> |
|
100 <p>So JNI is general enough to be used to access almost any |
|
101 sort of native library. |
|
102 The rest of this document assumes a familiarity with how |
|
103 to use JNI. |
|
104 |
|
105 <p><b>How to use JAWT </b></p> |
|
106 <p>In this section we describe the most common usage of the AWT |
|
107 Native Interface — overriding the <tt>paint</tt> method to |
|
108 direct drawing operations to a native rendering library which then |
|
109 queries the Java VM to determine the information it needs in order |
|
110 to render. Note, however, that any native code may use the AWT |
|
111 Native Interface to learn about a target drawing surface, not just |
|
112 code in a <tt>paint</tt> method.</p> |
|
113 <p>The first step in hooking up a native rendering library to a |
|
114 Java <tt>Canvas</tt> is to define a new class that extends |
|
115 <tt>Canvas</tt> and overrides the <tt>paint</tt> method. The Java |
|
116 system routes all drawing operations for a <tt>Canvas</tt> object |
|
117 through the <tt>paint</tt> method, as it does for all other GUI |
|
118 objects. Canvas is a good candidate for the rendering surface as |
|
119 it does not have any content as a Button would.</p> |
|
120 <p>The new <tt>paint</tt> method, to be implemented in the native |
|
121 rendering library, must be declared as <tt>public native void</tt> |
|
122 , and the native library itself is loaded at runtime by including a |
|
123 call to <tt>System.loadLibrary( "myRenderingLib")</tt>in |
|
124 the <tt>static</tt> block of the class. The <tt>myRenderingLib</tt> |
|
125 name is used for the native shared library; for Linux or the Solaris |
|
126 operating environment, the actual name for the library file on disk |
|
127 is <tt>libmyRenderingLib.so</tt> .</p> |
|
128 <p>Here is a simple example of such a class:</p> |
|
129 <pre> |
|
130 import java.awt.*; |
|
131 import java.awt.event.*; |
|
132 |
|
133 public class MyCanvas extends Canvas { |
|
134 static { |
|
135 System.loadLibrary("myRenderingLib"); |
|
136 } |
|
137 public native void paint(Graphics g); |
|
138 |
|
139 public static void main(String[] args) { |
|
140 Frame f = new Frame(); |
|
141 f.setBounds(0, 0, 500, 110); |
|
142 f.add(new MyCanvas()); |
|
143 f.addWindowListener( new WindowAdapter() { |
|
144 public void windowClosing(WindowEvent ev) { |
|
145 System.exit(0); |
|
146 } |
|
147 } ); |
|
148 f.show(); |
|
149 } |
|
150 } |
|
151 <br /> |
|
152 </pre> |
|
153 <p>Note that this class has a <tt>main</tt> method that can be used |
|
154 to run this code as an application for testing purposes.</p> |
|
155 <p>The next step is to run the <tt>javah</tt> tool on the |
|
156 <tt>MyCanvas</tt> class file above to generate a C/C++ header file |
|
157 that describes the interface to the native <tt>paint</tt> method |
|
158 that Java expects to be used. <tt>javah</tt> is a standard tool |
|
159 included with the JDK. NB: <tt>javac -h outputdir</tt> may also be used.</p> |
|
160 |
|
161 <p>The final step ­ and the most interesting one ­ is to |
|
162 write the native rendering method, with an interface that conforms |
|
163 to the header file that <tt>javah</tt> generated, and build it as a |
|
164 standard shared library (called <tt>myRenderingLib</tt> in the |
|
165 above example) by linking it, against the appropriate JDK provided |
|
166 $JDK_HOME/lib/$JAWT_LIB library for the target platform. |
|
167 Where JAWT_LIB has the base name "jawt" and follows platform |
|
168 shared object naming rules. i.e.: |
|
169 <ul> |
|
170 <li>Windows: jawt.dll |
|
171 <li>MacOS: libjawt.dylib |
|
172 <li>Linux: libjawt.so |
|
173 <li>Solaris: libjawt.so |
|
174 </ul> |
|
175 |
|
176 This code will call back to the Java virtual machine to |
|
177 get the drawing surface information it needs to access the |
|
178 <tt>MyCanvas</tt> peer. Once this information is available, the |
|
179 code can draw directly to <tt>MyCanvas</tt> using standard drawing |
|
180 routines supplied by the underlying operating system.</p> |
|
181 <p>Here is sample source code for a native <tt>paint</tt> method |
|
182 designed for use in a X11-based drawing environment (Linux |
|
183 or Solaris) and a Java VM where the AWT Native Interface is present:</p> |
|
184 <pre> |
|
185 #include "MyCanvas.h" |
|
186 #include "jawt_md.h" |
|
187 |
|
188 /* |
|
189 * Class: MyCanvas |
|
190 * Method: paint |
|
191 * Signature: (Ljava/awt/Graphics;)V |
|
192 */ |
|
193 JNIEXPORT void JNICALL Java_MyCanvas_paint |
|
194 (JNIEnv* env, jobject canvas, jobject graphics) |
|
195 { |
|
196 JAWT awt; |
|
197 JAWT_DrawingSurface* ds; |
|
198 JAWT_DrawingSurfaceInfo* dsi; |
|
199 JAWT_X11DrawingSurfaceInfo* dsi_x11; |
|
200 jboolean result; |
|
201 jint lock; |
|
202 GC gc; |
|
203 |
|
204 short i; |
|
205 char *testString = "^^^ rendered from native code ^^^"; |
|
206 |
|
207 /* Get the AWT */ |
|
208 awt.version = JAWT_VERSION_9; |
|
209 if (JAWT_GetAWT(env, &awt) == JNI_FALSE) { |
|
210 printf("AWT Not found\n"); |
|
211 return; |
|
212 } |
|
213 |
|
214 /* Get the drawing surface */ |
|
215 ds = awt.GetDrawingSurface(env, canvas); |
|
216 if (ds == NULL) { |
|
217 printf("NULL drawing surface\n"); |
|
218 return; |
|
219 } |
|
220 |
|
221 /* Lock the drawing surface */ |
|
222 lock = ds->Lock(ds); |
|
223 if((lock & JAWT_LOCK_ERROR) != 0) { |
|
224 printf("Error locking surface\n"); |
|
225 awt.FreeDrawingSurface(ds); |
|
226 return; |
|
227 } |
|
228 |
|
229 /* Get the drawing surface info */ |
|
230 dsi = ds->GetDrawingSurfaceInfo(ds); |
|
231 if (dsi == NULL) { |
|
232 printf("Error getting surface info\n"); |
|
233 ds->Unlock(ds); |
|
234 awt.FreeDrawingSurface(ds); |
|
235 return; |
|
236 } |
|
237 |
|
238 /* Get the platform-specific drawing info */ |
|
239 dsi_x11 = (JAWT_X11DrawingSurfaceInfo*)dsi->platformInfo; |
|
240 |
|
241 |
|
242 /* Now paint */ |
|
243 gc = XCreateGC(dsi_x11->display, dsi_x11->drawable, 0, 0); |
|
244 XSetBackground(dsi_x11->display, gc, 0); |
|
245 for (i=0; i<36;i++) |
|
246 { |
|
247 XSetForeground(dsi_x11->display, gc, 10*i); |
|
248 XFillRectangle(dsi_x11->display, dsi_x11->drawable, gc, |
|
249 10*i, 5, 90, 90); |
|
250 } |
|
251 XSetForeground(dsi_x11->display, gc, 155); |
|
252 XDrawImageString(dsi_x11->display, dsi_x11->drawable, gc, |
|
253 100, 110, testString, strlen(testString)); |
|
254 XFreeGC(dsi_x11->display, gc); |
|
255 |
|
256 |
|
257 /* Free the drawing surface info */ |
|
258 ds->FreeDrawingSurfaceInfo(dsi); |
|
259 |
|
260 /* Unlock the drawing surface */ |
|
261 ds->Unlock(ds); |
|
262 |
|
263 /* Free the drawing surface */ |
|
264 awt.FreeDrawingSurface(ds); |
|
265 } |
|
266 </pre> |
|
267 <p>The key data structure here is <tt>JAWT</tt> , which is defined |
|
268 in <tt>jawt.h</tt> (included by <tt>jawt_md.h)</tt> ; it provides |
|
269 access to all the information the native code needs to get the job |
|
270 done. The first part of the native method is boilerplate: it |
|
271 populates the <tt>JAWT</tt> structure, gets a |
|
272 <tt>JAWT_DrawingSurface</tt> structure, locks the surface (only one |
|
273 drawing engine at a time, please!), then gets a |
|
274 <tt>JAWT_DrawingSurfaceInfo</tt> structure that contains a pointer |
|
275 (in the <tt>platformInfo</tt> field) to the necessary |
|
276 platform-specific drawing information. It also includes the |
|
277 bounding rectangle of the drawing surface and the current clipping |
|
278 region.</p> |
|
279 <p>The structure of the information pointed to by |
|
280 <tt>platformInfo</tt> is defined in a machine-dependent header file |
|
281 called <tt>jawt_md.h</tt>. For X11 drawing, it includes |
|
282 information about the X11 display and X11 drawable associated with |
|
283 <tt>MyCanvas</tt>. After the drawing operations are completed, |
|
284 there is more boilerplate code as <tt>JAWT_DrawingSurfaceInfo</tt> |
|
285 is freed and <tt>JAWT_DrawingSurface</tt> is unlocked and |
|
286 freed.</p> |
|
287 <p>The corresponding code for the GDI API on the Microsoft Windows platform would |
|
288 be structured similarly, but would include the version of |
|
289 <tt>jawt_md.h</tt> for Microsoft Windows and the structure located |
|
290 in the <tt>platformInfo</tt> field of drawing surface info would be |
|
291 cast as a <tt>JAWT_Win32DrawingSurfaceInfo*</tt> . And, of course, |
|
292 the actual drawing operations would need to be changed to those |
|
293 appropriate for the Microsoft Windows platform. |
|
294 The same also for MacOS. |
|
295 </p> |
|
296 <p><b>Summary</b></p> |
|
297 <p>The ability to draw directly into a Java <tt>Canvas</tt> from a |
|
298 native code library is extremely useful for developers planning to |
|
299 migrate a legacy software system to Java, especially one that |
|
300 includes a high-performance rendering engine. It makes it much |
|
301 easier to migrate in stages, leaving performance-sensitive |
|
302 rendering code alone, while other less-sensitive portions of code |
|
303 are converted to Java. The result can be a modern Java-centric |
|
304 application, providing the benefit of portability and development |
|
305 efficiency, but one that does not sacrifice an investment in |
|
306 performance of a key piece of native code.</p> |
|
307 <p><b>References</b></p> |
|
308 <p>The definitive reference to the Java Native Interface is <i>The |
|
309 Java Native Interface: Programmer's Guide and Specification</i> by |
|
310 Sheng Liang. This book was published in June |
|
311 1999 by Addison-Wesley. The ISBN is 0-201-32577-2.</p> |
|
312 <p><b>Appendix</b></p> |
|
313 <p><b>Header Files for jawt.h and jawt_md.h</b></p> |
|
314 <a name="jawt.h"></a> |
|
315 <p>jawt.h</p> |
|
316 <pre> |
|
317 #ifndef _JAVASOFT_JAWT_H_ |
|
318 #define _JAVASOFT_JAWT_H_ |
|
319 |
|
320 #include "jni.h" |
|
321 |
|
322 #ifdef __cplusplus |
|
323 extern "C" { |
|
324 #endif |
|
325 |
|
326 /* |
|
327 * AWT native interface. |
|
328 * |
|
329 * The AWT native interface allows a native C or C++ application a means |
|
330 * by which to access native structures in AWT. This is to facilitate moving |
|
331 * legacy C and C++ applications to Java and to target the needs of the |
|
332 * developers who need to do their own native rendering to canvases |
|
333 * for performance or other reasons. |
|
334 * |
|
335 * Conversely it also provides mechanisms for an application which already |
|
336 * has a native window to provide that to AWT for AWT rendering. |
|
337 * |
|
338 * Since every platform may be different in its native data structures |
|
339 * and APIs for windowing systems the application must necessarily |
|
340 * provided per-platform source and compile and deliver per-platform |
|
341 * native code to use this API. |
|
342 * |
|
343 * These interfaces are not part of the Java SE specification and |
|
344 * a VM is not required to implement this API. However it is strongly |
|
345 * recommended that all implementations which support headful AWT |
|
346 * also support these interfaces. |
|
347 * |
|
348 */ |
|
349 |
|
350 /* |
|
351 * AWT Native Drawing Surface (JAWT_DrawingSurface). |
|
352 * |
|
353 * For each platform, there is a native drawing surface structure. This |
|
354 * platform-specific structure can be found in jawt_md.h. It is recommended |
|
355 * that additional platforms follow the same model. It is also recommended |
|
356 * that VMs on all platforms support the existing structures in jawt_md.h. |
|
357 * |
|
358 ******************* |
|
359 * EXAMPLE OF USAGE: |
|
360 ******************* |
|
361 * |
|
362 * On Microsoft Windows, a programmer wishes to access the HWND of a canvas |
|
363 * to perform native rendering into it. The programmer has declared the |
|
364 * paint() method for their canvas subclass to be native: |
|
365 * |
|
366 * |
|
367 * MyCanvas.java: |
|
368 * |
|
369 * import java.awt.*; |
|
370 * |
|
371 * public class MyCanvas extends Canvas { |
|
372 * |
|
373 * static { |
|
374 * System.loadLibrary("mylib"); |
|
375 * } |
|
376 * |
|
377 * public native void paint(Graphics g); |
|
378 * } |
|
379 * |
|
380 * |
|
381 * myfile.c: |
|
382 * |
|
383 * #include "jawt_md.h" |
|
384 * #include <assert.h> |
|
385 * |
|
386 * JNIEXPORT void JNICALL |
|
387 * Java_MyCanvas_paint(JNIEnv* env, jobject canvas, jobject graphics) |
|
388 * { |
|
389 * JAWT awt; |
|
390 * JAWT_DrawingSurface* ds; |
|
391 * JAWT_DrawingSurfaceInfo* dsi; |
|
392 * JAWT_Win32DrawingSurfaceInfo* dsi_win; |
|
393 * jboolean result; |
|
394 * jint lock; |
|
395 * |
|
396 * // Get the AWT. Request version 9 to access features in that release. |
|
397 * awt.version = JAWT_VERSION_9; |
|
398 * result = JAWT_GetAWT(env, &awt); |
|
399 * assert(result != JNI_FALSE); |
|
400 * |
|
401 * // Get the drawing surface |
|
402 * ds = awt.GetDrawingSurface(env, canvas); |
|
403 * assert(ds != NULL); |
|
404 * |
|
405 * // Lock the drawing surface |
|
406 * lock = ds->Lock(ds); |
|
407 * assert((lock & JAWT_LOCK_ERROR) == 0); |
|
408 * |
|
409 * // Get the drawing surface info |
|
410 * dsi = ds->GetDrawingSurfaceInfo(ds); |
|
411 * |
|
412 * // Get the platform-specific drawing info |
|
413 * dsi_win = (JAWT_Win32DrawingSurfaceInfo*)dsi->platformInfo; |
|
414 * |
|
415 * ////////////////////////////// |
|
416 * // !!! DO PAINTING HERE !!! // |
|
417 * ////////////////////////////// |
|
418 * |
|
419 * // Free the drawing surface info |
|
420 * ds->FreeDrawingSurfaceInfo(dsi); |
|
421 * |
|
422 * // Unlock the drawing surface |
|
423 * ds->Unlock(ds); |
|
424 * |
|
425 * // Free the drawing surface |
|
426 * awt.FreeDrawingSurface(ds); |
|
427 * } |
|
428 * |
|
429 */ |
|
430 |
|
431 /* |
|
432 * JAWT_Rectangle |
|
433 * Structure for a native rectangle. |
|
434 */ |
|
435 typedef struct jawt_Rectangle { |
|
436 jint x; |
|
437 jint y; |
|
438 jint width; |
|
439 jint height; |
|
440 } JAWT_Rectangle; |
|
441 |
|
442 struct jawt_DrawingSurface; |
|
443 |
|
444 /* |
|
445 * JAWT_DrawingSurfaceInfo |
|
446 * Structure for containing the underlying drawing information of a component. |
|
447 */ |
|
448 typedef struct jawt_DrawingSurfaceInfo { |
|
449 /* |
|
450 * Pointer to the platform-specific information. This can be safely |
|
451 * cast to a JAWT_Win32DrawingSurfaceInfo on Microsoft Windows or a |
|
452 * JAWT_X11DrawingSurfaceInfo on Linux and Solaris. On MacOS this is a |
|
453 * pointer to a NSObject that conforms to the JAWT_SurfaceLayers protocol. |
|
454 * See jawt_md.h for details. |
|
455 */ |
|
456 void* platformInfo; |
|
457 /* Cached pointer to the underlying drawing surface */ |
|
458 struct jawt_DrawingSurface* ds; |
|
459 /* Bounding rectangle of the drawing surface */ |
|
460 JAWT_Rectangle bounds; |
|
461 /* Number of rectangles in the clip */ |
|
462 jint clipSize; |
|
463 /* Clip rectangle array */ |
|
464 JAWT_Rectangle* clip; |
|
465 } JAWT_DrawingSurfaceInfo; |
|
466 |
|
467 #define JAWT_LOCK_ERROR 0x00000001 |
|
468 #define JAWT_LOCK_CLIP_CHANGED 0x00000002 |
|
469 #define JAWT_LOCK_BOUNDS_CHANGED 0x00000004 |
|
470 #define JAWT_LOCK_SURFACE_CHANGED 0x00000008 |
|
471 |
|
472 /* |
|
473 * JAWT_DrawingSurface |
|
474 * Structure for containing the underlying drawing information of a component. |
|
475 * All operations on a JAWT_DrawingSurface MUST be performed from the same |
|
476 * thread as the call to GetDrawingSurface. |
|
477 */ |
|
478 typedef struct jawt_DrawingSurface { |
|
479 /* Cached reference to the Java environment of the calling thread. |
|
480 * If Lock(), Unlock(), GetDrawingSurfaceInfo() or |
|
481 * FreeDrawingSurfaceInfo() are called from a different thread, |
|
482 * this data member should be set before calling those functions. |
|
483 */ |
|
484 JNIEnv* env; |
|
485 /* Cached reference to the target object */ |
|
486 jobject target; |
|
487 /* |
|
488 * Lock the surface of the target component for native rendering. |
|
489 * When finished drawing, the surface must be unlocked with |
|
490 * Unlock(). This function returns a bitmask with one or more of the |
|
491 * following values: |
|
492 * |
|
493 * JAWT_LOCK_ERROR - When an error has occurred and the surface could not |
|
494 * be locked. |
|
495 * |
|
496 * JAWT_LOCK_CLIP_CHANGED - When the clip region has changed. |
|
497 * |
|
498 * JAWT_LOCK_BOUNDS_CHANGED - When the bounds of the surface have changed. |
|
499 * |
|
500 * JAWT_LOCK_SURFACE_CHANGED - When the surface itself has changed |
|
501 */ |
|
502 jint (JNICALL *Lock) |
|
503 (struct jawt_DrawingSurface* ds); |
|
504 /* |
|
505 * Get the drawing surface info. |
|
506 * The value returned may be cached, but the values may change if |
|
507 * additional calls to Lock() or Unlock() are made. |
|
508 * Lock() must be called before this can return a valid value. |
|
509 * Returns NULL if an error has occurred. |
|
510 * When finished with the returned value, FreeDrawingSurfaceInfo must be |
|
511 * called. |
|
512 */ |
|
513 JAWT_DrawingSurfaceInfo* (JNICALL *GetDrawingSurfaceInfo) |
|
514 (struct jawt_DrawingSurface* ds); |
|
515 /* |
|
516 * Free the drawing surface info. |
|
517 */ |
|
518 void (JNICALL *FreeDrawingSurfaceInfo) |
|
519 (JAWT_DrawingSurfaceInfo* dsi); |
|
520 /* |
|
521 * Unlock the drawing surface of the target component for native rendering. |
|
522 */ |
|
523 void (JNICALL *Unlock) |
|
524 (struct jawt_DrawingSurface* ds); |
|
525 } JAWT_DrawingSurface; |
|
526 |
|
527 /* |
|
528 * JAWT |
|
529 * Structure for containing native AWT functions. |
|
530 */ |
|
531 typedef struct jawt { |
|
532 /* |
|
533 * Version of this structure. This must always be set before |
|
534 * calling JAWT_GetAWT(). It affects the functions returned. |
|
535 * Must be one of the known pre-defined versions. |
|
536 */ |
|
537 jint version; |
|
538 /* |
|
539 * Return a drawing surface from a target jobject. This value |
|
540 * may be cached. |
|
541 * Returns NULL if an error has occurred. |
|
542 * Target must be a java.awt.Component (should be a Canvas |
|
543 * or Window for native rendering). |
|
544 * FreeDrawingSurface() must be called when finished with the |
|
545 * returned JAWT_DrawingSurface. |
|
546 */ |
|
547 JAWT_DrawingSurface* (JNICALL *GetDrawingSurface) |
|
548 (JNIEnv* env, jobject target); |
|
549 /* |
|
550 * Free the drawing surface allocated in GetDrawingSurface. |
|
551 */ |
|
552 void (JNICALL *FreeDrawingSurface) |
|
553 (JAWT_DrawingSurface* ds); |
|
554 /* |
|
555 * Since 1.4 |
|
556 * Locks the entire AWT for synchronization purposes |
|
557 */ |
|
558 void (JNICALL *Lock)(JNIEnv* env); |
|
559 /* |
|
560 * Since 1.4 |
|
561 * Unlocks the entire AWT for synchronization purposes |
|
562 */ |
|
563 void (JNICALL *Unlock)(JNIEnv* env); |
|
564 /* |
|
565 * Since 1.4 |
|
566 * Returns a reference to a java.awt.Component from a native |
|
567 * platform handle. On Windows, this corresponds to an HWND; |
|
568 * on Solaris and Linux, this is a Drawable. For other platforms, |
|
569 * see the appropriate machine-dependent header file for a description. |
|
570 * The reference returned by this function is a local |
|
571 * reference that is only valid in this environment. |
|
572 * This function returns a NULL reference if no component could be |
|
573 * found with matching platform information. |
|
574 */ |
|
575 jobject (JNICALL *GetComponent)(JNIEnv* env, void* platformInfo); |
|
576 |
|
577 /** |
|
578 * Since 9 |
|
579 * Creates a java.awt.Frame placed in a native container. Container is |
|
580 * referenced by the native platform handle. For example on Windows this |
|
581 * corresponds to an HWND. For other platforms, see the appropriate |
|
582 * machine-dependent header file for a description. The reference returned |
|
583 * by this function is a local reference that is only valid in this |
|
584 * environment. This function returns a NULL reference if no frame could be |
|
585 * created with matching platform information. |
|
586 */ |
|
587 jobject (JNICALL *CreateEmbeddedFrame) (JNIEnv *env, void* platformInfo); |
|
588 |
|
589 /** |
|
590 * Since 9 |
|
591 * Moves and resizes the embedded frame. The new location of the top-left |
|
592 * corner is specified by x and y parameters relative to the native parent |
|
593 * component. The new size is specified by width and height. |
|
594 * |
|
595 * The embedded frame should be created by CreateEmbeddedFrame() method, or |
|
596 * this function will not have any effect. |
|
597 * |
|
598 * java.awt.Component.setLocation() and java.awt.Component.setBounds() for |
|
599 * EmbeddedFrame really don't move it within the native parent. These |
|
600 * methods always locate the embedded frame at (0, 0) for backward |
|
601 * compatibility. To allow moving embedded frames this method was |
|
602 * introduced, and it works just the same way as setLocation() and |
|
603 * setBounds() for usual, non-embedded components. |
|
604 * |
|
605 * Using usual get/setLocation() and get/setBounds() together with this new |
|
606 * method is not recommended. |
|
607 */ |
|
608 void (JNICALL *SetBounds) (JNIEnv *env, jobject embeddedFrame, |
|
609 jint x, jint y, jint w, jint h); |
|
610 /** |
|
611 * Since 9 |
|
612 * Synthesize a native message to activate or deactivate an EmbeddedFrame |
|
613 * window depending on the value of parameter doActivate, if "true" |
|
614 * activates the window; otherwise, deactivates the window. |
|
615 * |
|
616 * The embedded frame should be created by CreateEmbeddedFrame() method, or |
|
617 * this function will not have any effect. |
|
618 */ |
|
619 void (JNICALL *SynthesizeWindowActivation) (JNIEnv *env, |
|
620 jobject embeddedFrame, jboolean doActivate); |
|
621 } JAWT; |
|
622 |
|
623 /* |
|
624 * Get the AWT native structure. This function returns JNI_FALSE if |
|
625 * an error occurs. |
|
626 */ |
|
627 _JNI_IMPORT_OR_EXPORT_ |
|
628 jboolean JNICALL JAWT_GetAWT(JNIEnv* env, JAWT* awt); |
|
629 |
|
630 /* |
|
631 * Specify one of these constants as the JAWT.version |
|
632 * Specifying an earlier version will limit the available functions to |
|
633 * those provided in that earlier version of JAWT. |
|
634 * See the "Since" note on each API. Methods with no "Since" |
|
635 * may be presumed to be present in JAWT_VERSION_1_3. |
|
636 */ |
|
637 #define JAWT_VERSION_1_3 0x00010003 |
|
638 #define JAWT_VERSION_1_4 0x00010004 |
|
639 #define JAWT_VERSION_1_7 0x00010007 |
|
640 #define JAWT_VERSION_9 0x00090000 |
|
641 |
|
642 |
|
643 #ifdef __cplusplus |
|
644 } /* extern "C" */ |
|
645 #endif |
|
646 |
|
647 #endif /* !_JAVASOFT_JAWT_H_ */ |
|
648 |
|
649 </pre> |
|
650 <p>jawt_md.h (Linux/Solaris/X11 operating environment version)</p> |
|
651 <pre> |
|
652 #ifndef _JAVASOFT_JAWT_MD_H_ |
|
653 #define _JAVASOFT_JAWT_MD_H_ |
|
654 |
|
655 #include <X11/Xlib.h> |
|
656 #include <X11/Xutil.h> |
|
657 #include <X11/Intrinsic.h> |
|
658 #include "jawt.h" |
|
659 |
|
660 #ifdef __cplusplus |
|
661 extern "C" { |
|
662 #endif |
|
663 |
|
664 /* |
|
665 * X11-specific declarations for AWT native interface. |
|
666 * See notes in jawt.h for an example of use. |
|
667 */ |
|
668 typedef struct jawt_X11DrawingSurfaceInfo { |
|
669 Drawable drawable; |
|
670 Display* display; |
|
671 VisualID visualID; |
|
672 Colormap colormapID; |
|
673 int depth; |
|
674 } JAWT_X11DrawingSurfaceInfo; |
|
675 |
|
676 #ifdef __cplusplus |
|
677 } |
|
678 #endif |
|
679 |
|
680 #endif /* !_JAVASOFT_JAWT_MD_H_ */ |
|
681 </pre> |
|
682 <p>jawt_md.h (Microsoft Windows version)</p> |
|
683 <pre> |
|
684 #ifndef _JAVASOFT_JAWT_MD_H_ |
|
685 #define _JAVASOFT_JAWT_MD_H_ |
|
686 |
|
687 #include <windows.h> |
|
688 #include "jawt.h" |
|
689 |
|
690 #ifdef __cplusplus |
|
691 extern "C" { |
|
692 #endif |
|
693 |
|
694 /* |
|
695 * Microsoft Windows specific declarations for AWT native interface. |
|
696 * See notes in jawt.h for an example of use. |
|
697 */ |
|
698 typedef struct jawt_Win32DrawingSurfaceInfo { |
|
699 /* Native window, DDB, or DIB handle */ |
|
700 union { |
|
701 HWND hwnd; |
|
702 HBITMAP hbitmap; |
|
703 void* pbits; |
|
704 }; |
|
705 /* |
|
706 * This HDC should always be used instead of the HDC returned from |
|
707 * BeginPaint() or any calls to GetDC(). |
|
708 */ |
|
709 HDC hdc; |
|
710 HPALETTE hpalette; |
|
711 } JAWT_Win32DrawingSurfaceInfo; |
|
712 |
|
713 #ifdef __cplusplus |
|
714 } |
|
715 #endif |
|
716 |
|
717 #endif /* !_JAVASOFT_JAWT_MD_H_ */ |
|
718 </pre> |
|
719 <p>jawt_md.h (MacOS version)</p> |
|
720 <pre> |
|
721 #ifndef _JAVASOFT_JAWT_MD_H_ |
|
722 #define _JAVASOFT_JAWT_MD_H_ |
|
723 |
|
724 #include "jawt.h" |
|
725 |
|
726 #ifdef __OBJC__ |
|
727 #import <QuartzCore/CALayer.h> |
|
728 #endif |
|
729 |
|
730 #ifdef __cplusplus |
|
731 extern "C" { |
|
732 #endif |
|
733 |
|
734 /* |
|
735 * MacOS specific declarations for AWT native interface. |
|
736 * See notes in jawt.h for an example of use. |
|
737 */ |
|
738 |
|
739 /* |
|
740 * When calling JAWT_GetAWT with a JAWT version less than 1.7, you must pass this |
|
741 * flag or you will not be able to get a valid drawing surface and JAWT_GetAWT will |
|
742 * return false. This is to maintain compatibility with applications that used the |
|
743 * interface with Java 6 which had multiple rendering models. This flag is not necessary |
|
744 * when JAWT version 1.7 or greater is used as this is the only supported rendering mode. |
|
745 * |
|
746 * Example: |
|
747 * JAWT awt; |
|
748 * awt.version = JAWT_VERSION_1_4 | JAWT_MACOSX_USE_CALAYER; |
|
749 * jboolean success = JAWT_GetAWT(env, &awt); |
|
750 */ |
|
751 #define JAWT_MACOSX_USE_CALAYER 0x80000000 |
|
752 |
|
753 /* |
|
754 * When the native Cocoa toolkit is in use, the pointer stored in |
|
755 * JAWT_DrawingSurfaceInfo->platformInfo points to a NSObject that conforms to the |
|
756 * JAWT_SurfaceLayers protocol. Setting the layer property of this object will cause the |
|
757 * specified layer to be overlaid on the Components rectangle. If the window the |
|
758 * Component belongs to has a CALayer attached to it, this layer will be accessible via |
|
759 * the windowLayer property. |
|
760 */ |
|
761 #ifdef __OBJC__ |
|
762 @protocol JAWT_SurfaceLayers |
|
763 @property (readwrite, retain) CALayer *layer; |
|
764 @property (readonly) CALayer *windowLayer; |
|
765 @end |
|
766 #endif |
|
767 |
|
768 #ifdef __cplusplus |
|
769 } |
|
770 #endif |
|
771 |
|
772 #endif /* !_JAVASOFT_JAWT_MD_H_ */ |
|
773 </pre> |
|
774 <!-- Body text ends here --> |
|
775 </body> |
|
776 </html> |
|