1 /*
   2  * Copyright (c) 1999, 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.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 #ifndef _JAVASOFT_JAWT_H_
  27 #define _JAVASOFT_JAWT_H_
  28 
  29 #include "jni.h"
  30 
  31 #ifdef __cplusplus
  32 extern "C" {
  33 #endif
  34 
  35 /*
  36  * AWT native interface.
  37  *
  38  * The AWT native interface allows a native C or C++ application a means
  39  * by which to access native structures in AWT.  This is to facilitate moving
  40  * legacy C and C++ applications to Java and to target the needs of the
  41  * developers who need to do their own native rendering to canvases
  42  * for performance or other reasons.
  43  *
  44  * Conversely it also provides mechanisms for an application which already
  45  * has a native window to provide that to AWT for AWT rendering.
  46  * 
  47  * Since every platform may be different in its native data structures
  48  * and APIs for windowing systems the application must necessarily
  49  * provided per-platform source and compile and deliver per-platform
  50  * native code  to use this API.
  51  *
  52  * These interfaces are not part of the Java SE specification and
  53  * a VM is not required to implement this API. However it is strongly
  54  * recommended that all implementations which support headful AWT 
  55  * also support these interfaces.
  56  *
  57  */
  58 
  59 /*
  60  * AWT Native Drawing Surface (JAWT_DrawingSurface).
  61  *
  62  * For each platform, there is a native drawing surface structure.  This
  63  * platform-specific structure can be found in jawt_md.h.  It is recommended
  64  * that additional platforms follow the same model.  It is also recommended
  65  * that VMs on all platforms support the existing structures in jawt_md.h.
  66  *
  67  *******************
  68  * EXAMPLE OF USAGE:
  69  *******************
  70  *
  71  * In Win32, a programmer wishes to access the HWND of a canvas to perform
  72  * native rendering into it.  The programmer has declared the paint() method
  73  * for their canvas subclass to be native:
  74  *
  75  *
  76  * MyCanvas.java:
  77  *
  78  * import java.awt.*;
  79  *
  80  * public class MyCanvas extends Canvas {
  81  *
  82  *     static {
  83  *         System.loadLibrary("mylib");
  84  *     }
  85  *
  86  *     public native void paint(Graphics g);
  87  * }
  88  *
  89  *
  90  * myfile.c:
  91  *
  92  * #include "jawt_md.h"
  93  * #include <assert.h>
  94  *
  95  * JNIEXPORT void JNICALL
  96  * Java_MyCanvas_paint(JNIEnv* env, jobject canvas, jobject graphics)
  97  * {
  98  *     JAWT awt;
  99  *     JAWT_DrawingSurface* ds;
 100  *     JAWT_DrawingSurfaceInfo* dsi;
 101  *     JAWT_Win32DrawingSurfaceInfo* dsi_win;
 102  *     jboolean result;
 103  *     jint lock;
 104  *
 105  *     // Get the AWT. Request version 9 to access features in that release.
 106  *     awt.version = JAWT_VERSION_9;
 107  *     result = JAWT_GetAWT(env, &awt);
 108  *     assert(result != JNI_FALSE);
 109  *
 110  *     // Get the drawing surface
 111  *     ds = awt.GetDrawingSurface(env, canvas);
 112  *     assert(ds != NULL);
 113  *
 114  *     // Lock the drawing surface
 115  *     lock = ds->Lock(ds);
 116  *     assert((lock & JAWT_LOCK_ERROR) == 0);
 117  *
 118  *     // Get the drawing surface info
 119  *     dsi = ds->GetDrawingSurfaceInfo(ds);
 120  *
 121  *     // Get the platform-specific drawing info
 122  *     dsi_win = (JAWT_Win32DrawingSurfaceInfo*)dsi->platformInfo;
 123  *
 124  *     //////////////////////////////
 125  *     // !!! DO PAINTING HERE !!! //
 126  *     //////////////////////////////
 127  *
 128  *     // Free the drawing surface info
 129  *     ds->FreeDrawingSurfaceInfo(dsi);
 130  *
 131  *     // Unlock the drawing surface
 132  *     ds->Unlock(ds);
 133  *
 134  *     // Free the drawing surface
 135  *     awt.FreeDrawingSurface(ds);
 136  * }
 137  *
 138  */
 139 
 140 /*
 141  * JAWT_Rectangle
 142  * Structure for a native rectangle.
 143  */
 144 typedef struct jawt_Rectangle {
 145     jint x;
 146     jint y;
 147     jint width;
 148     jint height;
 149 } JAWT_Rectangle;
 150 
 151 struct jawt_DrawingSurface;
 152 
 153 /*
 154  * JAWT_DrawingSurfaceInfo
 155  * Structure for containing the underlying drawing information of a component.
 156  */
 157 typedef struct jawt_DrawingSurfaceInfo {
 158     /*
 159      * Pointer to the platform-specific information.  This can be safely
 160      * cast to a JAWT_Win32DrawingSurfaceInfo on Windows or a
 161      * JAWT_X11DrawingSurfaceInfo on Linux and Solaris. On Mac OS X this is a
 162      * pointer to a NSObject that conforms to the JAWT_SurfaceLayers
 163      * protocol. See jawt_md.h for details.
 164      */
 165     void* platformInfo;
 166     /* Cached pointer to the underlying drawing surface */
 167     struct jawt_DrawingSurface* ds;
 168     /* Bounding rectangle of the drawing surface */
 169     JAWT_Rectangle bounds;
 170     /* Number of rectangles in the clip */
 171     jint clipSize;
 172     /* Clip rectangle array */
 173     JAWT_Rectangle* clip;
 174 } JAWT_DrawingSurfaceInfo;
 175 
 176 #define JAWT_LOCK_ERROR                 0x00000001
 177 #define JAWT_LOCK_CLIP_CHANGED          0x00000002
 178 #define JAWT_LOCK_BOUNDS_CHANGED        0x00000004
 179 #define JAWT_LOCK_SURFACE_CHANGED       0x00000008
 180 
 181 /*
 182  * JAWT_DrawingSurface
 183  * Structure for containing the underlying drawing information of a component.
 184  * All operations on a JAWT_DrawingSurface MUST be performed from the same
 185  * thread as the call to GetDrawingSurface.
 186  */
 187 typedef struct jawt_DrawingSurface {
 188     /*
 189      * Cached reference to the Java environment of the calling thread.
 190      * If Lock(), Unlock(), GetDrawingSurfaceInfo() or
 191      * FreeDrawingSurfaceInfo() are called from a different thread,
 192      * this data member should be set before calling those functions.
 193      */
 194     JNIEnv* env;
 195     /* Cached reference to the target object */
 196     jobject target;
 197     /*
 198      * Lock the surface of the target component for native rendering.
 199      * When finished drawing, the surface must be unlocked with
 200      * Unlock().  This function returns a bitmask with one or more of the
 201      * following values:
 202      *
 203      * JAWT_LOCK_ERROR - When an error has occurred and the surface could not
 204      * be locked.
 205      *
 206      * JAWT_LOCK_CLIP_CHANGED - When the clip region has changed.
 207      *
 208      * JAWT_LOCK_BOUNDS_CHANGED - When the bounds of the surface have changed.
 209      *
 210      * JAWT_LOCK_SURFACE_CHANGED - When the surface itself has changed
 211      */
 212     jint (JNICALL *Lock)
 213         (struct jawt_DrawingSurface* ds);
 214     /*
 215      * Get the drawing surface info.
 216      * The value returned may be cached, but the values may change if
 217      * additional calls to Lock() or Unlock() are made.
 218      * Lock() must be called before this can return a valid value.
 219      * Returns NULL if an error has occurred.
 220      * When finished with the returned value, FreeDrawingSurfaceInfo must be
 221      * called.
 222      */
 223     JAWT_DrawingSurfaceInfo* (JNICALL *GetDrawingSurfaceInfo)
 224         (struct jawt_DrawingSurface* ds);
 225     /*
 226      * Free the drawing surface info.
 227      */
 228     void (JNICALL *FreeDrawingSurfaceInfo)
 229         (JAWT_DrawingSurfaceInfo* dsi);
 230     /*
 231      * Unlock the drawing surface of the target component for native rendering.
 232      */
 233     void (JNICALL *Unlock)
 234         (struct jawt_DrawingSurface* ds);
 235 } JAWT_DrawingSurface;
 236 
 237 /*
 238  * JAWT
 239  * Structure for containing native AWT functions.
 240  */
 241 typedef struct jawt {
 242     /*
 243      * Version of this structure.  This must always be set before
 244      * calling JAWT_GetAWT(). It affects the functions returned.
 245      * Must be one of the known pre-defined versions.
 246      */
 247     jint version;
 248     /*
 249      * Return a drawing surface from a target jobject.  This value
 250      * may be cached.
 251      * Returns NULL if an error has occurred.
 252      * Target must be a java.awt.Component (should be a Canvas
 253      * or Window for native rendering).
 254      * FreeDrawingSurface() must be called when finished with the
 255      * returned JAWT_DrawingSurface.
 256      */
 257     JAWT_DrawingSurface* (JNICALL *GetDrawingSurface)
 258         (JNIEnv* env, jobject target);
 259     /*
 260      * Free the drawing surface allocated in GetDrawingSurface.
 261      */
 262     void (JNICALL *FreeDrawingSurface)
 263         (JAWT_DrawingSurface* ds);
 264     /*
 265      * Since 1.4
 266      * Locks the entire AWT for synchronization purposes
 267      */
 268     void (JNICALL *Lock)(JNIEnv* env);
 269     /*
 270      * Since 1.4
 271      * Unlocks the entire AWT for synchronization purposes
 272      */
 273     void (JNICALL *Unlock)(JNIEnv* env);
 274     /*
 275      * Since 1.4
 276      * Returns a reference to a java.awt.Component from a native
 277      * platform handle.  On Windows, this corresponds to an HWND;
 278      * on Solaris and Linux, this is a Drawable.  For other platforms,
 279      * see the appropriate machine-dependent header file for a description.
 280      * The reference returned by this function is a local
 281      * reference that is only valid in this environment.
 282      * This function returns a NULL reference if no component could be
 283      * found with matching platform information.
 284      */
 285     jobject (JNICALL *GetComponent)(JNIEnv* env, void* platformInfo);
 286 
 287     /**
 288      * Since 9
 289      * Creates a java.awt.Frame placed in a native container. Container is
 290      * referenced by the native platform handle. For example on Windows this
 291      * corresponds to an HWND. For other platforms, see the appropriate
 292      * machine-dependent header file for a description. The reference returned
 293      * by this function is a local reference that is only valid in this
 294      * environment. This function returns a NULL reference if no frame could be
 295      * created with matching platform information.
 296      */
 297     jobject (JNICALL *CreateEmbeddedFrame) (JNIEnv *env, void* platformInfo);
 298 
 299     /**
 300      * Since 9
 301      * Moves and resizes the embedded frame. The new location of the top-left
 302      * corner is specified by x and y parameters relative to the native parent
 303      * component. The new size is specified by width and height.
 304      *
 305      * The embedded frame should be created by CreateEmbeddedFrame() method, or
 306      * this function will not have any effect.
 307      *
 308      * java.awt.Component.setLocation() and java.awt.Component.setBounds() for
 309      * EmbeddedFrame really don't move it within the native parent. These
 310      * methods always locate the embedded frame at (0, 0) for backward
 311      * compatibility. To allow moving embedded frames this method was
 312      * introduced, and it works just the same way as setLocation() and
 313      * setBounds() for usual, non-embedded components.
 314      *
 315      * Using usual get/setLocation() and get/setBounds() together with this new
 316      * method is not recommended.
 317      */
 318     void (JNICALL *SetBounds) (JNIEnv *env, jobject embeddedFrame,
 319             jint x, jint y, jint w, jint h);
 320     /**
 321      * Since 9
 322      * Synthesize a native message to activate or deactivate an EmbeddedFrame
 323      * window depending on the value of parameter doActivate, if "true"
 324      * activates the window; otherwise, deactivates the window.
 325      *
 326      * The embedded frame should be created by CreateEmbeddedFrame() method, or
 327      * this function will not have any effect.
 328      */
 329     void (JNICALL *SynthesizeWindowActivation) (JNIEnv *env,
 330             jobject embeddedFrame, jboolean doActivate);
 331 } JAWT;
 332 
 333 /*
 334  * Get the AWT native structure.  This function returns JNI_FALSE if
 335  * an error occurs.
 336  */
 337 _JNI_IMPORT_OR_EXPORT_
 338 jboolean JNICALL JAWT_GetAWT(JNIEnv* env, JAWT* awt);
 339 
 340 /*
 341  * Specify one of these constants as the JAWT.version
 342  * Specifying an earlier version will limit the available functions to
 343  * those provided in that earlier version of JAWT.
 344  * See the "Since" note on each API. Methods with no "Since"
 345  * may be presumed to be present in JAWT_VERSION_1_3.
 346  */
 347 #define JAWT_VERSION_1_3 0x00010003
 348 #define JAWT_VERSION_1_4 0x00010004
 349 #define JAWT_VERSION_1_7 0x00010007
 350 #define JAWT_VERSION_9 0x00090000
 351 
 352 #ifdef __cplusplus
 353 } /* extern "C" */
 354 #endif
 355 
 356 #endif /* !_JAVASOFT_JAWT_H_ */