From 821e71f0ccf176ca398f2fee1df840a3da33393b Mon Sep 17 00:00:00 2001 From: Phil Race Date: Thu, 27 Apr 2017 14:07:38 -0700 Subject: [PATCH] 8179365: JAWT (AWT Native Interface) specification needs to be updated for JDK 9 Reviewed-by: serb, ssadetsky --- .../macosx/native/include/jawt_md.h | 2 +- .../share/classes/java/awt/package-info.java | 2 + .../java.desktop/share/native/include/jawt.h | 42 +- .../share/specs/AWT_Native_Interface.html | 776 ++++++++++++++++++ 4 files changed, 806 insertions(+), 16 deletions(-) create mode 100644 jdk/src/java.desktop/share/specs/AWT_Native_Interface.html diff --git a/jdk/src/java.desktop/macosx/native/include/jawt_md.h b/jdk/src/java.desktop/macosx/native/include/jawt_md.h index c6859fdbf90..94a13c9ab40 100644 --- a/jdk/src/java.desktop/macosx/native/include/jawt_md.h +++ b/jdk/src/java.desktop/macosx/native/include/jawt_md.h @@ -37,7 +37,7 @@ extern "C" { #endif /* - * Mac OS X specific declarations for AWT native interface. + * MacOS specific declarations for AWT native interface. * See notes in jawt.h for an example of use. */ diff --git a/jdk/src/java.desktop/share/classes/java/awt/package-info.java b/jdk/src/java.desktop/share/classes/java/awt/package-info.java index 76ecdae7ec0..682a371dd83 100644 --- a/jdk/src/java.desktop/share/classes/java/awt/package-info.java +++ b/jdk/src/java.desktop/share/classes/java/awt/package-info.java @@ -54,6 +54,8 @@ * * * @since 1.0 diff --git a/jdk/src/java.desktop/share/native/include/jawt.h b/jdk/src/java.desktop/share/native/include/jawt.h index 8cb2cb8564d..2079b0bc1b3 100644 --- a/jdk/src/java.desktop/share/native/include/jawt.h +++ b/jdk/src/java.desktop/share/native/include/jawt.h @@ -1,5 +1,5 @@ /* - * Copyright (c) 1999, 2016, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1999, 2017, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -38,18 +38,22 @@ extern "C" { * The AWT native interface allows a native C or C++ application a means * by which to access native structures in AWT. This is to facilitate moving * legacy C and C++ applications to Java and to target the needs of the - * community who, at present, wish to do their own native rendering to canvases - * for performance reasons. Standard extensions such as Java3D also require a - * means to access the underlying native data structures of AWT. + * developers who need to do their own native rendering to canvases + * for performance or other reasons. * - * There may be future extensions to this API depending on demand. + * Conversely it also provides mechanisms for an application which already + * has a native window to provide that to AWT for AWT rendering. * - * A VM does not have to implement this API in order to pass the JCK. - * It is recommended, however, that this API is implemented on VMs that support - * standard extensions, such as Java3D. + * Since every platform may be different in its native data structures + * and APIs for windowing systems the application must necessarily + * provided per-platform source and compile and deliver per-platform + * native code to use this API. + * + * These interfaces are not part of the Java SE specification and + * a VM is not required to implement this API. However it is strongly + * recommended that all implementations which support headful AWT + * also support these interfaces. * - * Since this is a native API, any program which uses it cannot be considered - * 100% pure java. */ /* @@ -58,7 +62,7 @@ extern "C" { * For each platform, there is a native drawing surface structure. This * platform-specific structure can be found in jawt_md.h. It is recommended * that additional platforms follow the same model. It is also recommended - * that VMs on Win32 and Solaris support the existing structures in jawt_md.h. + * that VMs on all platforms support the existing structures in jawt_md.h. * ******************* * EXAMPLE OF USAGE: @@ -98,8 +102,8 @@ extern "C" { * jboolean result; * jint lock; * - * // Get the AWT - * awt.version = JAWT_VERSION_1_3; + * // Get the AWT. Request version 9 to access features in that release. + * awt.version = JAWT_VERSION_9; * result = JAWT_GetAWT(env, &awt); * assert(result != JNI_FALSE); * @@ -154,7 +158,7 @@ typedef struct jawt_DrawingSurfaceInfo { /* * Pointer to the platform-specific information. This can be safely * cast to a JAWT_Win32DrawingSurfaceInfo on Windows or a - * JAWT_X11DrawingSurfaceInfo on Solaris. On Mac OS X this is a + * JAWT_X11DrawingSurfaceInfo on Linux and Solaris. On Mac OS X this is a * pointer to a NSObject that conforms to the JAWT_SurfaceLayers * protocol. See jawt_md.h for details. */ @@ -237,7 +241,8 @@ typedef struct jawt_DrawingSurface { typedef struct jawt { /* * Version of this structure. This must always be set before - * calling JAWT_GetAWT() + * calling JAWT_GetAWT(). It affects the functions returned. + * Must be one of the known pre-defined versions. */ jint version; /* @@ -332,6 +337,13 @@ typedef struct jawt { _JNI_IMPORT_OR_EXPORT_ jboolean JNICALL JAWT_GetAWT(JNIEnv* env, JAWT* awt); +/* + * Specify one of these constants as the JAWT.version + * Specifying an earlier version will limit the available functions to + * those provided in that earlier version of JAWT. + * See the "Since" note on each API. Methods with no "Since" + * may be presumed to be present in JAWT_VERSION_1_3. + */ #define JAWT_VERSION_1_3 0x00010003 #define JAWT_VERSION_1_4 0x00010004 #define JAWT_VERSION_1_7 0x00010007 diff --git a/jdk/src/java.desktop/share/specs/AWT_Native_Interface.html b/jdk/src/java.desktop/share/specs/AWT_Native_Interface.html new file mode 100644 index 00000000000..782376099a8 --- /dev/null +++ b/jdk/src/java.desktop/share/specs/AWT_Native_Interface.html @@ -0,0 +1,776 @@ + + + + + +Java AWT Native Interface Specification and Guide + + +

The Java AWT Native Interface Specification and Guide

+

Introduction

+

The Java AWT Native Interface (JAWT) comprises a small set of native +(eg C language-based) APIs that provide a standard supported way +for interaction between Java API windows and surfaces, and +platform native API windows and surfaces. +Non-Java libraries may then render to a Java owned window. +

+Note: in this document the terms "Java AWT Native Interface", +"AWT Native Interface" and "JAWT" are interchangeable and +refer to this same specification. +

+The fundamental obstacle to native rendering without JAWT is that +is that the rendering code cannot identify where to draw. +The native code needs access to information about a Java +drawing surface (such as a handle to the underlying native ID of a +Canvas), but cannot get it.

+Without that information (ie without JAWT) an application could +use native rendering only by creating its own top-level window +not shared at all with Java. This is unacceptable for most uses. +Except for usage via JAWT, this is considered to be entirely +internal to the Java platform implementation: private, unsupported +and undocumented. +

+JAWT should be supported in all headful implementations +where technically possible although this is not enforced by the JCK. +There is a platform-specific and a platform +independent portion to the API, to account for the differing +data structures and requirements of each platform. +This document specifies the platform independent portions and +also documents the platform dependent portions for the Oracle JDK +supported desktop operating environments. +For AWT the term platform is less tied to the underlying operating +system than it is to the desktop windowing environment. +

+Reasons for using the AWT Native Interface include +

+

+Drawbacks include +

+The header file "jawt.h" +in the Appendix fully specifies the APIs provided by JAWT. +

+An example illustrating how easy it is to use the AWT Native Interface +is presented and discussed later in this document.

+ +

JAWT usage depends on JNI

+

The definition of Java Standard Edition includes JNI, the Java +Native Interface. Many Java developers will never need to use it, +but the interface is the only standard supported way for a Java +language program to interact directly with +application code that has been compiled to the native machine +instructions for the host processor architecture. +JNI is used where ever there is a need for mixed languages. +These are by no means limited to cases like AWT. For example, you +could use JNI to integrate with native code that communicates with +a peripheral device, such as a scanner, connected to a system via a +USB port.

+

So JNI is general enough to be used to access almost any +sort of native library. +The rest of this document assumes a familiarity with how +to use JNI. + +

How to use JAWT

+

In this section we describe the most common usage of the AWT +Native Interface — overriding the paint method to +direct drawing operations to a native rendering library which then +queries the Java VM to determine the information it needs in order +to render. Note, however, that any native code may use the AWT +Native Interface to learn about a target drawing surface, not just +code in a paint method.

+

The first step in hooking up a native rendering library to a +Java Canvas is to define a new class that extends +Canvas and overrides the paint method. The Java +system routes all drawing operations for a Canvas object +through the paint method, as it does for all other GUI +objects. Canvas is a good candidate for the rendering surface as +it does not have any content as a Button would.

+

The new paint method, to be implemented in the native +rendering library, must be declared as public native void +, and the native library itself is loaded at runtime by including a +call to System.loadLibrary( "myRenderingLib")in +the static block of the class. The myRenderingLib +name is used for the native shared library; for Linux or the Solaris +operating environment, the actual name for the library file on disk +is libmyRenderingLib.so .

+

Here is a simple example of such a class:

+
+import java.awt.*;
+import java.awt.event.*;
+
+public class MyCanvas extends Canvas {
+    static {
+        System.loadLibrary("myRenderingLib");
+    }
+    public native void paint(Graphics g);
+
+    public static void main(String[] args) {
+        Frame f = new Frame();
+        f.setBounds(0, 0, 500, 110);
+        f.add(new MyCanvas());
+        f.addWindowListener( new WindowAdapter() {
+            public void windowClosing(WindowEvent ev) {
+                System.exit(0);
+            }
+        } );
+        f.show();
+    }
+}
+

+
+

Note that this class has a main method that can be used +to run this code as an application for testing purposes.

+

The next step is to run the javah tool on the +MyCanvas class file above to generate a C/C++ header file +that describes the interface to the native paint method +that Java expects to be used. javah is a standard tool +included with the JDK. NB: javac -h outputdir may also be used.

+ +

The final step ­ and the most interesting one ­ is to +write the native rendering method, with an interface that conforms +to the header file that javah generated, and build it as a +standard shared library (called myRenderingLib in the +above example) by linking it, against the appropriate JDK provided +$JDK_HOME/lib/$JAWT_LIB library for the target platform. +Where JAWT_LIB has the base name "jawt" and follows platform +shared object naming rules. i.e.: +

+ +This code will call back to the Java virtual machine to +get the drawing surface information it needs to access the +MyCanvas peer. Once this information is available, the +code can draw directly to MyCanvas using standard drawing +routines supplied by the underlying operating system.

+

Here is sample source code for a native paint method +designed for use in a X11-based drawing environment (Linux +or Solaris) and a Java VM where the AWT Native Interface is present:

+
+#include "MyCanvas.h"
+#include "jawt_md.h"
+
+/*
+ * Class:     MyCanvas
+ * Method:    paint
+ * Signature: (Ljava/awt/Graphics;)V
+ */
+JNIEXPORT void JNICALL Java_MyCanvas_paint
+(JNIEnv* env, jobject canvas, jobject graphics)
+{
+    JAWT awt;
+    JAWT_DrawingSurface* ds;
+    JAWT_DrawingSurfaceInfo* dsi;
+    JAWT_X11DrawingSurfaceInfo* dsi_x11;
+    jboolean result;
+    jint lock;
+    GC gc;
+
+    short       i;
+    char        *testString = "^^^ rendered from native code ^^^";
+
+    /* Get the AWT */
+    awt.version = JAWT_VERSION_9;
+    if (JAWT_GetAWT(env, &awt) == JNI_FALSE) {
+        printf("AWT Not found\n");
+        return;
+    }
+
+    /* Get the drawing surface */
+    ds = awt.GetDrawingSurface(env, canvas);
+    if (ds == NULL) {
+        printf("NULL drawing surface\n");
+        return;
+    }
+
+    /* Lock the drawing surface */
+    lock = ds->Lock(ds);
+    if((lock & JAWT_LOCK_ERROR) != 0) {
+        printf("Error locking surface\n");
+        awt.FreeDrawingSurface(ds);
+        return;
+    }
+
+    /* Get the drawing surface info */
+    dsi = ds->GetDrawingSurfaceInfo(ds);
+    if (dsi == NULL) {
+        printf("Error getting surface info\n");
+        ds->Unlock(ds);
+        awt.FreeDrawingSurface(ds);
+        return;
+    }
+
+    /* Get the platform-specific drawing info */
+    dsi_x11 = (JAWT_X11DrawingSurfaceInfo*)dsi->platformInfo;
+
+
+    /* Now paint */
+    gc = XCreateGC(dsi_x11->display, dsi_x11->drawable, 0, 0);
+    XSetBackground(dsi_x11->display, gc, 0);
+    for (i=0; i<36;i++)
+    {
+        XSetForeground(dsi_x11->display, gc, 10*i);
+        XFillRectangle(dsi_x11->display, dsi_x11->drawable, gc,
+                        10*i, 5, 90, 90);
+    }
+    XSetForeground(dsi_x11->display, gc, 155);
+    XDrawImageString(dsi_x11->display, dsi_x11->drawable, gc,
+                        100, 110, testString, strlen(testString));
+    XFreeGC(dsi_x11->display, gc);
+
+
+    /* Free the drawing surface info */
+    ds->FreeDrawingSurfaceInfo(dsi);
+
+    /* Unlock the drawing surface */
+    ds->Unlock(ds);
+
+    /* Free the drawing surface */
+    awt.FreeDrawingSurface(ds);
+}
+
+

The key data structure here is JAWT , which is defined +in jawt.h (included by jawt_md.h) ; it provides +access to all the information the native code needs to get the job +done. The first part of the native method is boilerplate: it +populates the JAWT structure, gets a +JAWT_DrawingSurface structure, locks the surface (only one +drawing engine at a time, please!), then gets a +JAWT_DrawingSurfaceInfo structure that contains a pointer +(in the platformInfo field) to the necessary +platform-specific drawing information. It also includes the +bounding rectangle of the drawing surface and the current clipping +region.

+

The structure of the information pointed to by +platformInfo is defined in a machine-dependent header file +called jawt_md.h. For X11 drawing, it includes +information about the X11 display and X11 drawable associated with +MyCanvas. After the drawing operations are completed, +there is more boilerplate code as JAWT_DrawingSurfaceInfo +is freed and JAWT_DrawingSurface is unlocked and +freed.

+

The corresponding code for the GDI API on the Microsoft Windows platform would +be structured similarly, but would include the version of +jawt_md.h for Microsoft Windows and the structure located +in the platformInfo field of drawing surface info would be +cast as a JAWT_Win32DrawingSurfaceInfo* . And, of course, +the actual drawing operations would need to be changed to those +appropriate for the Microsoft Windows platform. +The same also for MacOS. +

+

Summary

+

The ability to draw directly into a Java Canvas from a +native code library is extremely useful for developers planning to +migrate a legacy software system to Java, especially one that +includes a high-performance rendering engine. It makes it much +easier to migrate in stages, leaving performance-sensitive +rendering code alone, while other less-sensitive portions of code +are converted to Java. The result can be a modern Java-centric +application, providing the benefit of portability and development +efficiency, but one that does not sacrifice an investment in +performance of a key piece of native code.

+

References

+

The definitive reference to the Java Native Interface is The +Java Native Interface: Programmer's Guide and Specification by +Sheng Liang. This book was published in June +1999 by Addison-Wesley. The ISBN is 0-201-32577-2.

+

Appendix

+

Header Files for jawt.h and jawt_md.h

+ +

jawt.h

+
+#ifndef _JAVASOFT_JAWT_H_
+#define _JAVASOFT_JAWT_H_
+
+#include "jni.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/*
+ * AWT native interface.
+ *
+ * The AWT native interface allows a native C or C++ application a means
+ * by which to access native structures in AWT.  This is to facilitate moving
+ * legacy C and C++ applications to Java and to target the needs of the
+ * developers who need to do their own native rendering to canvases
+ * for performance or other reasons.
+ *
+ * Conversely it also provides mechanisms for an application which already
+ * has a native window to provide that to AWT for AWT rendering.
+ *
+ * Since every platform may be different in its native data structures
+ * and APIs for windowing systems the application must necessarily
+ * provided per-platform source and compile and deliver per-platform
+ * native code  to use this API.
+ *
+ * These interfaces are not part of the Java SE specification and
+ * a VM is not required to implement this API. However it is strongly
+ * recommended that all implementations which support headful AWT
+ * also support these interfaces.
+ *
+ */
+
+/*
+ * AWT Native Drawing Surface (JAWT_DrawingSurface).
+ *
+ * For each platform, there is a native drawing surface structure.  This
+ * platform-specific structure can be found in jawt_md.h.  It is recommended
+ * that additional platforms follow the same model.  It is also recommended
+ * that VMs on all platforms support the existing structures in jawt_md.h.
+ *
+ *******************
+ * EXAMPLE OF USAGE:
+ *******************
+ *
+ * On Microsoft Windows, a programmer wishes to access the HWND of a canvas
+ * to perform native rendering into it.  The programmer has declared the
+ * paint() method for their canvas subclass to be native:
+ *
+ *
+ * MyCanvas.java:
+ *
+ * import java.awt.*;
+ *
+ * public class MyCanvas extends Canvas {
+ *
+ *     static {
+ *         System.loadLibrary("mylib");
+ *     }
+ *
+ *     public native void paint(Graphics g);
+ * }
+ *
+ *
+ * myfile.c:
+ *
+ * #include "jawt_md.h"
+ * #include <assert.h>
+ *
+ * JNIEXPORT void JNICALL
+ * Java_MyCanvas_paint(JNIEnv* env, jobject canvas, jobject graphics)
+ * {
+ *     JAWT awt;
+ *     JAWT_DrawingSurface* ds;
+ *     JAWT_DrawingSurfaceInfo* dsi;
+ *     JAWT_Win32DrawingSurfaceInfo* dsi_win;
+ *     jboolean result;
+ *     jint lock;
+ *
+ *     // Get the AWT. Request version 9 to access features in that release.
+ *     awt.version = JAWT_VERSION_9;
+ *     result = JAWT_GetAWT(env, &awt);
+ *     assert(result != JNI_FALSE);
+ *
+ *     // Get the drawing surface
+ *     ds = awt.GetDrawingSurface(env, canvas);
+ *     assert(ds != NULL);
+ *
+ *     // Lock the drawing surface
+ *     lock = ds->Lock(ds);
+ *     assert((lock & JAWT_LOCK_ERROR) == 0);
+ *
+ *     // Get the drawing surface info
+ *     dsi = ds->GetDrawingSurfaceInfo(ds);
+ *
+ *     // Get the platform-specific drawing info
+ *     dsi_win = (JAWT_Win32DrawingSurfaceInfo*)dsi->platformInfo;
+ *
+ *     //////////////////////////////
+ *     // !!! DO PAINTING HERE !!! //
+ *     //////////////////////////////
+ *
+ *     // Free the drawing surface info
+ *     ds->FreeDrawingSurfaceInfo(dsi);
+ *
+ *     // Unlock the drawing surface
+ *     ds->Unlock(ds);
+ *
+ *     // Free the drawing surface
+ *     awt.FreeDrawingSurface(ds);
+ * }
+ *
+ */
+
+/*
+ * JAWT_Rectangle
+ * Structure for a native rectangle.
+ */
+typedef struct jawt_Rectangle {
+    jint x;
+    jint y;
+    jint width;
+    jint height;
+} JAWT_Rectangle;
+
+struct jawt_DrawingSurface;
+
+/*
+ * JAWT_DrawingSurfaceInfo
+ * Structure for containing the underlying drawing information of a component.
+ */
+typedef struct jawt_DrawingSurfaceInfo {
+    /*
+     * Pointer to the platform-specific information.  This can be safely
+     * cast to a JAWT_Win32DrawingSurfaceInfo on Microsoft Windows or a
+     * JAWT_X11DrawingSurfaceInfo on Linux and Solaris. On MacOS this is a
+     * pointer to a NSObject that conforms to the JAWT_SurfaceLayers protocol.
+     * See jawt_md.h for details.
+     */
+    void* platformInfo;
+    /* Cached pointer to the underlying drawing surface */
+    struct jawt_DrawingSurface* ds;
+    /* Bounding rectangle of the drawing surface */
+    JAWT_Rectangle bounds;
+    /* Number of rectangles in the clip */
+    jint clipSize;
+    /* Clip rectangle array */
+    JAWT_Rectangle* clip;
+} JAWT_DrawingSurfaceInfo;
+
+#define JAWT_LOCK_ERROR                 0x00000001
+#define JAWT_LOCK_CLIP_CHANGED          0x00000002
+#define JAWT_LOCK_BOUNDS_CHANGED        0x00000004
+#define JAWT_LOCK_SURFACE_CHANGED       0x00000008
+
+/*
+ * JAWT_DrawingSurface
+ * Structure for containing the underlying drawing information of a component.
+ * All operations on a JAWT_DrawingSurface MUST be performed from the same
+ * thread as the call to GetDrawingSurface.
+ */
+typedef struct jawt_DrawingSurface {
+    /* Cached reference to the Java environment of the calling thread.
+     * If Lock(), Unlock(), GetDrawingSurfaceInfo() or
+     * FreeDrawingSurfaceInfo() are called from a different thread,
+     * this data member should be set before calling those functions.
+     */
+    JNIEnv* env;
+    /* Cached reference to the target object */
+    jobject target;
+    /*
+     * Lock the surface of the target component for native rendering.
+     * When finished drawing, the surface must be unlocked with
+     * Unlock().  This function returns a bitmask with one or more of the
+     * following values:
+     *
+     * JAWT_LOCK_ERROR - When an error has occurred and the surface could not
+     * be locked.
+     *
+     * JAWT_LOCK_CLIP_CHANGED - When the clip region has changed.
+     *
+     * JAWT_LOCK_BOUNDS_CHANGED - When the bounds of the surface have changed.
+     *
+     * JAWT_LOCK_SURFACE_CHANGED - When the surface itself has changed
+     */
+    jint (JNICALL *Lock)
+        (struct jawt_DrawingSurface* ds);
+    /*
+     * Get the drawing surface info.
+     * The value returned may be cached, but the values may change if
+     * additional calls to Lock() or Unlock() are made.
+     * Lock() must be called before this can return a valid value.
+     * Returns NULL if an error has occurred.
+     * When finished with the returned value, FreeDrawingSurfaceInfo must be
+     * called.
+     */
+    JAWT_DrawingSurfaceInfo* (JNICALL *GetDrawingSurfaceInfo)
+        (struct jawt_DrawingSurface* ds);
+    /*
+     * Free the drawing surface info.
+     */
+    void (JNICALL *FreeDrawingSurfaceInfo)
+        (JAWT_DrawingSurfaceInfo* dsi);
+    /*
+     * Unlock the drawing surface of the target component for native rendering.
+     */
+    void (JNICALL *Unlock)
+        (struct jawt_DrawingSurface* ds);
+} JAWT_DrawingSurface;
+
+/*
+ * JAWT
+ * Structure for containing native AWT functions.
+ */
+typedef struct jawt {
+    /*
+     * Version of this structure.  This must always be set before
+     * calling JAWT_GetAWT(). It affects the functions returned.
+     * Must be one of the known pre-defined versions.
+     */
+    jint version;
+    /*
+     * Return a drawing surface from a target jobject.  This value
+     * may be cached.
+     * Returns NULL if an error has occurred.
+     * Target must be a java.awt.Component (should be a Canvas
+     * or Window for native rendering).
+     * FreeDrawingSurface() must be called when finished with the
+     * returned JAWT_DrawingSurface.
+     */
+    JAWT_DrawingSurface* (JNICALL *GetDrawingSurface)
+        (JNIEnv* env, jobject target);
+    /*
+     * Free the drawing surface allocated in GetDrawingSurface.
+     */
+    void (JNICALL *FreeDrawingSurface)
+        (JAWT_DrawingSurface* ds);
+    /*
+     * Since 1.4
+     * Locks the entire AWT for synchronization purposes
+     */
+    void (JNICALL *Lock)(JNIEnv* env);
+    /*
+     * Since 1.4
+     * Unlocks the entire AWT for synchronization purposes
+     */
+    void (JNICALL *Unlock)(JNIEnv* env);
+    /*
+     * Since 1.4
+     * Returns a reference to a java.awt.Component from a native
+     * platform handle.  On Windows, this corresponds to an HWND;
+     * on Solaris and Linux, this is a Drawable.  For other platforms,
+     * see the appropriate machine-dependent header file for a description.
+     * The reference returned by this function is a local
+     * reference that is only valid in this environment.
+     * This function returns a NULL reference if no component could be
+     * found with matching platform information.
+     */
+    jobject (JNICALL *GetComponent)(JNIEnv* env, void* platformInfo);
+
+    /**
+     * Since 9
+     * Creates a java.awt.Frame placed in a native container. Container is
+     * referenced by the native platform handle. For example on Windows this
+     * corresponds to an HWND. For other platforms, see the appropriate
+     * machine-dependent header file for a description. The reference returned
+     * by this function is a local reference that is only valid in this
+     * environment. This function returns a NULL reference if no frame could be
+     * created with matching platform information.
+     */
+    jobject (JNICALL *CreateEmbeddedFrame) (JNIEnv *env, void* platformInfo);
+
+    /**
+     * Since 9
+     * Moves and resizes the embedded frame. The new location of the top-left
+     * corner is specified by x and y parameters relative to the native parent
+     * component. The new size is specified by width and height.
+     *
+     * The embedded frame should be created by CreateEmbeddedFrame() method, or
+     * this function will not have any effect.
+     *
+     * java.awt.Component.setLocation() and java.awt.Component.setBounds() for
+     * EmbeddedFrame really don't move it within the native parent. These
+     * methods always locate the embedded frame at (0, 0) for backward
+     * compatibility. To allow moving embedded frames this method was
+     * introduced, and it works just the same way as setLocation() and
+     * setBounds() for usual, non-embedded components.
+     *
+     * Using usual get/setLocation() and get/setBounds() together with this new
+     * method is not recommended.
+     */
+    void (JNICALL *SetBounds) (JNIEnv *env, jobject embeddedFrame,
+            jint x, jint y, jint w, jint h);
+    /**
+     * Since 9
+     * Synthesize a native message to activate or deactivate an EmbeddedFrame
+     * window depending on the value of parameter doActivate, if "true"
+     * activates the window; otherwise, deactivates the window.
+     *
+     * The embedded frame should be created by CreateEmbeddedFrame() method, or
+     * this function will not have any effect.
+     */
+    void (JNICALL *SynthesizeWindowActivation) (JNIEnv *env,
+            jobject embeddedFrame, jboolean doActivate);
+} JAWT;
+
+/*
+ * Get the AWT native structure.  This function returns JNI_FALSE if
+ * an error occurs.
+ */
+_JNI_IMPORT_OR_EXPORT_
+jboolean JNICALL JAWT_GetAWT(JNIEnv* env, JAWT* awt);
+
+/*
+ * Specify one of these constants as the JAWT.version
+ * Specifying an earlier version will limit the available functions to
+ * those provided in that earlier version of JAWT.
+ * See the "Since" note on each API. Methods with no "Since"
+ * may be presumed to be present in JAWT_VERSION_1_3.
+ */
+#define JAWT_VERSION_1_3 0x00010003
+#define JAWT_VERSION_1_4 0x00010004
+#define JAWT_VERSION_1_7 0x00010007
+#define JAWT_VERSION_9 0x00090000
+
+
+#ifdef __cplusplus
+} /* extern "C" */
+#endif
+
+#endif /* !_JAVASOFT_JAWT_H_ */
+
+
+

jawt_md.h (Linux/Solaris/X11 operating environment version)

+
+#ifndef _JAVASOFT_JAWT_MD_H_
+#define _JAVASOFT_JAWT_MD_H_
+
+#include <X11/Xlib.h>
+#include <X11/Xutil.h>
+#include <X11/Intrinsic.h>
+#include "jawt.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/*
+ * X11-specific declarations for AWT native interface.
+ * See notes in jawt.h for an example of use.
+ */
+typedef struct jawt_X11DrawingSurfaceInfo {
+    Drawable drawable;
+    Display* display;
+    VisualID visualID;
+    Colormap colormapID;
+    int depth;
+} JAWT_X11DrawingSurfaceInfo;
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* !_JAVASOFT_JAWT_MD_H_ */
+
+

jawt_md.h (Microsoft Windows version)

+
+#ifndef _JAVASOFT_JAWT_MD_H_
+#define _JAVASOFT_JAWT_MD_H_
+
+#include <windows.h>
+#include "jawt.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/*
+ * Microsoft Windows specific declarations for AWT native interface.
+ * See notes in jawt.h for an example of use.
+ */
+typedef struct jawt_Win32DrawingSurfaceInfo {
+    /* Native window, DDB, or DIB handle */
+    union {
+        HWND hwnd;
+        HBITMAP hbitmap;
+        void* pbits;
+    };
+    /*
+     * This HDC should always be used instead of the HDC returned from
+     * BeginPaint() or any calls to GetDC().
+     */
+    HDC hdc;
+    HPALETTE hpalette;
+} JAWT_Win32DrawingSurfaceInfo;
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* !_JAVASOFT_JAWT_MD_H_ */
+
+

jawt_md.h (MacOS version)

+
+#ifndef _JAVASOFT_JAWT_MD_H_
+#define _JAVASOFT_JAWT_MD_H_
+
+#include "jawt.h"
+
+#ifdef __OBJC__
+#import 
+#endif
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/*
+ * MacOS specific declarations for AWT native interface.
+ * See notes in jawt.h for an example of use.
+ */
+
+/*
+ * When calling JAWT_GetAWT with a JAWT version less than 1.7, you must pass this
+ * flag or you will not be able to get a valid drawing surface and JAWT_GetAWT will
+ * return false. This is to maintain compatibility with applications that used the
+ * interface with Java 6 which had multiple rendering models. This flag is not necessary
+ * when JAWT version 1.7 or greater is used as this is the only supported rendering mode.
+ *
+ * Example:
+ *   JAWT awt;
+ *   awt.version = JAWT_VERSION_1_4 | JAWT_MACOSX_USE_CALAYER;
+ *   jboolean success = JAWT_GetAWT(env, &awt);
+ */
+#define JAWT_MACOSX_USE_CALAYER 0x80000000
+
+/*
+ * When the native Cocoa toolkit is in use, the pointer stored in
+ * JAWT_DrawingSurfaceInfo->platformInfo points to a NSObject that conforms to the
+ * JAWT_SurfaceLayers protocol. Setting the layer property of this object will cause the
+ * specified layer to be overlaid on the Components rectangle. If the window the
+ * Component belongs to has a CALayer attached to it, this layer will be accessible via
+ * the windowLayer property.
+ */
+#ifdef __OBJC__
+@protocol JAWT_SurfaceLayers
+@property (readwrite, retain) CALayer *layer;
+@property (readonly) CALayer *windowLayer;
+@end
+#endif
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* !_JAVASOFT_JAWT_MD_H_ */
+
+ + +