com.apple.eawt
Class CocoaComponent

java.lang.Object
  java.awt.Component
      java.awt.Canvas
          com.apple.eawt.CocoaComponent

All Implemented Interfaces:

java.awt.image.ImageObserver, java.awt.MenuContainer, java.io.Serializable, javax.accessibility.Accessible

public abstract class CocoaComponent
extends java.awt.Canvas

Allows custom widgets based on Cocoa's NSView class to be hosted in the AWT component hierarchy. Using this class, in conjunction with JNI libraries, you can embed Cocoa components inside of native Java applications. Use CocoaComponent to pass AWT events and messages through to the embedded Cocoa component.

When using CocoaComponent, it is important to understand that there are two threading models involved. Whenever a graphical Java application is run, it is hosted inside of a Cocoa NSApplication. Normally any interactions between the native environment and the Java environment are handled for you and you need not be concerned with their threading or event models. When implementing this class though, you must take a few precautions to ensure harmony between the two environments:

• Do not block the AWT event dispatch thread against the AppKit thread. Doing so likely results in a deadlock.
• Do not block the AppKit thread against the AWT event thread. Doing so likely results in a deadlock. Note that grabbing a Java-accessible lock (such as the AWT TreeLock) from the AppKit thread is considered unsafe for this reason. Avoid calling AWT or Swing methods from the AppKit thread.
• Once the NSView you are using has been added to the Cocoa view hierarchy on the AppKit thread, all calls on the implementation's NSView must be made on the AppKit thread.

The embedded Cocoa component, included all of its methods, is fully available from Java. It can can be told to draw onto the canvas, receive events, change its bounds, or perform any other behavior provided by the native API. It does not understand Java-specific things not defined in its own API. For example, you are not able to set the font, background color, mouse cursor, or related characteristics of the NSView from Java, since AWT does not know how to pass these messages to the underlying NSView.

If the underlying NSView consumes NSEvents it may not be possible for AWT to generate AWT events for the CocoaComponent.

WARNING: Given the nature of the interrelationship between the AppKit and AWT, it is important to adhere to the guidelines presented here. Failure to do so may result in your Java application deadlocking or crashing, possibly also resulting in data loss.

NOTE: In Mac OS X v10.4, the threading model of the AWT native implementation has been revised. To provide compatibility between the improved threading model and older implementations of CocoaComponent, a special mode has been introduced. This compatibility mode activates the first time a CocoaComponent is used in an application and defaults to true. A developer can turn this mode off by setting a System Property:

com.apple.eawt.CocoaComponent.CompatibilityMode=false

While the compatibility mode is active, the AWT will not deadlock longer than 0.5 seconds. However, this also means that any AWT peer request that takes longer 0.5 seconds will return asynchronously (with possibly incorrect results for a "get"). The intent is for older applications to work better on Mac OS X v10.4. However, it's strongly suggested that newer applications fix their threading model and disable this compatibility mode. By default, applets always have the compatibility mode enabled, though not active. The first applet to use CocoaComponent will activate the compatibility mode. Once all applets have been closed, the compatibility mode is disabled. At this time there is no supported way to exclude specific applets from the compatibility mode.

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class java.awt.Canvas

java.awt.Canvas.AccessibleAWTCanvas

Nested classes/interfaces inherited from class java.awt.Component

java.awt.Component.AccessibleAWTComponent, java.awt.Component.BltBufferStrategy, java.awt.Component.FlipBufferStrategy

Field Summary

Fields inherited from class java.awt.Component

BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT

Fields inherited from interface java.awt.image.ImageObserver

ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH

Constructor Summary

CocoaComponent()

Method Summary

abstract int	createNSView() Deprecated. As of Mac OS X 10.4 (Tiger), programs should pass native pointers to java as a long; replaced by long createNSViewLong().
long	createNSViewLong() This is the same as createNSView.
abstract java.awt.Dimension	getMaximumSize() Used by AWT layout managers to get the maximum allowable size for the embedded component.
abstract java.awt.Dimension	getMinimumSize() Used by AWT layout managers to get the minimum allowable size for the embedded component.
abstract java.awt.Dimension	getPreferredSize() Used by AWT layout managers to get the preferred size for the embedded component.
void	paint(java.awt.Graphics g)
void	sendMessage(int messageID, java.lang.Object message) Sends a message to the embedded NSView.
void	update(java.awt.Graphics g)

Methods inherited from class java.awt.Canvas

addNotify, createBufferStrategy, createBufferStrategy, getAccessibleContext, getBufferStrategy

Methods inherited from class java.awt.Component

action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, bounds, checkImage, checkImage, coalesceEvents, contains, contains, createImage, createImage, createVolatileImage, createVolatileImage, deliverEvent, disable, disableEvents, dispatchEvent, doLayout, enable, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getAlignmentX, getAlignmentY, getBackground, getBounds, getBounds, getColorModel, getComponentAt, getComponentAt, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeys, getFocusTraversalKeysEnabled, getFont, getFontMetrics, getForeground, getGraphics, getGraphicsConfiguration, getHeight, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getListeners, getLocale, getLocation, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getSize, getToolkit, getTreeLock, getWidth, getX, getY, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, invalidate, isBackgroundSet, isCursorSet, isDisplayable, isDoubleBuffered, isEnabled, isFocusable, isFocusCycleRoot, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isOpaque, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, layout, list, list, list, list, list, locate, location, lostFocus, minimumSize, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, paramString, postEvent, preferredSize, prepareImage, prepareImage, print, printAll, processComponentEvent, processEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removeNotify, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, repaint, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, reshape, resize, resize, setBackground, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setEnabled, setFocusable, setFocusTraversalKeys, setFocusTraversalKeysEnabled, setFont, setForeground, setIgnoreRepaint, setLocale, setLocation, setLocation, setMaximumSize, setMinimumSize, setName, setPreferredSize, setSize, setSize, setVisible, show, show, size, toString, transferFocus, transferFocusBackward, transferFocusUpCycle, validate

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

CocoaComponent

public CocoaComponent()

Method Detail

createNSView

public abstract int createNSView()

Deprecated. As of Mac OS X 10.4 (Tiger), programs should pass native pointers to java as a long; replaced by long createNSViewLong().

Creates and retains the underlying NSView. Normally you call this from the AWT event dispatch thread. Note that calling this method will not immediately result in an active NSView, you must first make the component visible. When you the component is made visible, CToolkit's createCanvas returns the NSView to AppKit's main thread. It is then added to the main superview of the containing NSApplication. The embedded NSView will not be usable until it receives the viewDidMoveToSuperview message.

update

public void update(java.awt.Graphics g)

Overrides:

update in class java.awt.Canvas

paint

public void paint(java.awt.Graphics g)

Overrides:

paint in class java.awt.Canvas

createNSViewLong

public long createNSViewLong()

This is the same as createNSView. However it returns the native pointer as a long. This is how Sun's Java code stores native pointers in Java, so this method is preferred.

sendMessage

public final void sendMessage(int messageID,
                              java.lang.Object message)

Sends a message to the embedded NSView. The message is sent to the NSView on AppKit's main thread created by createNSView. That NSView must have a selector of type -(void)awtMessage:(jint)messageID message:(jobject)message env:(JNIEnv *)env (or implement the AWTCocoaComponent protocol found in JavaVM/AWTCocoaComponent.h) to receive the message. The method is sent asynchronously, so the method does not wait for the message to return.

Note that this method is provided as a convenience API.

getMaximumSize

public abstract java.awt.Dimension getMaximumSize()

Used by AWT layout managers to get the maximum allowable size for the embedded component. Because Cocoa and AWT do not use the same mechanism to determine layout components, classes that implement CocoaComponent must implement this method. To specify an unlimited maximum size, simply return new Dimension(Short.MAX_VALUE, Short.MAX_VALUE).

Overrides:

getMaximumSize in class java.awt.Component

Returns:

a dimension object indicating the embedded Cocoa component's maximum size

getMinimumSize

public abstract java.awt.Dimension getMinimumSize()

Used by AWT layout managers to get the minimum allowable size for the embedded component. Because Cocoa and AWT do not use the same mechanism to determine how to lay out components, classes that implement CocoaComponent must implement this method explicitly. For example, if you return new Dimension(0,0), Cocoa may not actually add the component to its superview as expected. If you do not have a default minimum size and would normally return a Dimension with 0 as both the height and the width, instead return new Dimension(2,2).

Overrides:

getMinimumSize in class java.awt.Component

Returns:

a dimension object indicating the embedded Cocoa component's minimum size

getPreferredSize

public abstract java.awt.Dimension getPreferredSize()

Used by AWT layout managers to get the preferred size for the embedded component. Because Cocoa and AWT do not use the same mechanism to determine how to lay out components, classes that implement CocoaComponent must implement this method explicitly. If you do not have a preferred size, return the result from getMinimumSize. Do not just return Dimension(0,0), because Cocoa may not add the component to its superview as expected.

Overrides:

getPreferredSize in class java.awt.Component

Returns:

a dimension object indicating the embedded Cocoa component's preferred size