org.mases.jcobridge

Class JCControl

java.lang.Object

java.awt.Component

org.mases.jcobridge.JCControl

All Implemented Interfaces:

ComponentListener, ImageObserver, MenuContainer, Serializable, EventListener

public final class JCControl
extends Component
implements ComponentListener

AWT wrapper that embeds a CLR graphical object (WinForms or WPF control) inside an AWT component hierarchy.

This is the AWT counterpart of JCJControl: it extends Component directly rather than JComponent, making it suitable for use in pure AWT containers. The behaviour is otherwise identical — the CLR control is allocated via the native bridge (allocateRemote(long, java.lang.String)), and ComponentListener events on both this component and its top-level ancestor window drive executePaint(long, long, boolean, java.awt.Component, double, double, int, int) calls that keep the embedded CLR control positioned correctly.

Member access (Invoke(java.lang.String, java.lang.Object...), Get(java.lang.String), Set(java.lang.String, java.lang.Object)) operates on the CLR control directly. Dispatcher-aware variants (DispatcherInvoke(org.mases.jcobridge.JCObject, java.lang.String, java.lang.Object...), DispatcherGet(org.mases.jcobridge.JCObject, java.lang.String), DispatcherSet(org.mases.jcobridge.JCObject, java.lang.String, java.lang.Object)) are available for WPF controls that require UI thread marshalling.

Instances are created by JCOBridge.GetControl(String) and should not be constructed directly.

Since:

1.0.0.0

Author:

MASES S.R.L.

See Also:

Serialized Form

Nested Class Summary

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

Component.BaselineResizeBehavior

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

Method Summary

Modifier and Type	Method and Description
void	addNotify()
void	componentHidden(ComponentEvent e)
void	componentMoved(ComponentEvent e)
void	componentResized(ComponentEvent e)
void	componentShown(ComponentEvent e)
static Object	DispatcherGet(JCObject target, String field) Retrieves an instance property or field value from a CLR object using the WPF Dispatcher thread.
static Object	DispatcherGet(JCType target, String field) Retrieves a static property or field value from a CLR type using the WPF Dispatcher thread.
static Object	DispatcherInvoke(JCObject target, String method, Object... params) Invokes an instance method on a CLR object using the WPF Dispatcher thread.
static Object	DispatcherInvoke(JCType target, String method, Object... params) Invokes a static method on a CLR type using the WPF Dispatcher thread.
static JCObject	DispatcherSet(JCObject target, String field, Object value) Sets an instance property or field on a CLR object using the WPF Dispatcher thread.
static JCObject	DispatcherSet(JCType target, String field, Object value) Sets a static property or field on a CLR type using the WPF Dispatcher thread.
Object	Get(String field) Retrieves an instance property or field value from the underlying CLR control.
JCObject	getControl() Returns the JCObject wrapper for the underlying CLR control, enabling direct member access via JCObject.Invoke(java.lang.String, java.lang.Object...), JCObject.Get(java.lang.String), etc.
boolean	getIsWPF() Returns true if the underlying CLR control is a WPF element.
int	hashCode() Returns the hash code of the underlying CLR control by delegating to JCObject.hashCode().
Object	Invoke(String method, Object... params) Invokes an instance method on the underlying CLR control with optional arguments.
void	RegisterEventListener(String eventName, IJCEventEmit eventHandler) Registers a value-returning CLR event handler on the underlying CLR control.
void	RegisterEventListener(String eventName, IJCVoidEventEmit eventHandler) Registers a void-return CLR event handler on the underlying CLR control.
void	removeNotify()
void	requestFocus()
JCObject	Set(String field, Object value) Sets an instance property or field on the underlying CLR control.
String	toString() Returns the string representation of the underlying CLR control by delegating to JCObject.toString().
void	UnregisterEventListener(String eventName, IJCEventEmit eventHandler) Unregisters a value-returning CLR event handler from the underlying CLR control.
void	UnregisterEventListener(String eventName, IJCVoidEventEmit eventHandler) Unregisters a void-return CLR event handler from the underlying CLR control.

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, contains, contains, createImage, createImage, createVolatileImage, createVolatileImage, deliverEvent, disable, dispatchEvent, doLayout, enable, enable, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getAccessibleContext, getAlignmentX, getAlignmentY, getBackground, getBaseline, getBaselineResizeBehavior, 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, getMaximumSize, getMinimumSize, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPreferredSize, 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, paint, paintAll, postEvent, preferredSize, prepareImage, prepareImage, print, printAll, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, repaint, requestFocusInWindow, reshape, resize, resize, revalidate, 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, transferFocus, transferFocusBackward, transferFocusUpCycle, update, validate

Methods inherited from class java.lang.Object

equals, getClass, notify, notifyAll, wait, wait, wait

Method Detail

hashCode

public int hashCode()

Returns the hash code of the underlying CLR control by delegating to JCObject.hashCode().

Overrides:

hashCode in class Object

Returns:

the CLR hash code.

toString

public String toString()

Returns the string representation of the underlying CLR control by delegating to JCObject.toString().

Overrides:

toString in class Component

Returns:

the CLR string representation.

getControl

public JCObject getControl()

Returns the JCObject wrapper for the underlying CLR control, enabling direct member access via JCObject.Invoke(java.lang.String, java.lang.Object...), JCObject.Get(java.lang.String), etc.

Returns:

the JCObject representing the CLR control.

getIsWPF

public boolean getIsWPF()
                 throws JCNativeException

Returns true if the underlying CLR control is a WPF element. WPF controls require Dispatcher-aware member access — use DispatcherInvoke(org.mases.jcobridge.JCObject, java.lang.String, java.lang.Object...), DispatcherGet(org.mases.jcobridge.JCObject, java.lang.String), and DispatcherSet(org.mases.jcobridge.JCObject, java.lang.String, java.lang.Object) instead of the direct variants.

Returns:

true if the CLR control is a WPF object.

Throws:

JCNativeException - if the query fails within the CLR context.

Invoke

public Object Invoke(String method,
                     Object... params)
              throws JCNativeException

Invokes an instance method on the underlying CLR control with optional arguments. For WPF controls, use DispatcherInvoke(JCObject, String, Object...) instead.

Parameters:

method - the name of the CLR method to invoke.

params - optional arguments to pass to the method.

Returns:

the method return value, as a Java primitive or JCObject.

Throws:

JCNativeException - if the method cannot be found, the invocation fails, or a CLR exception is thrown.

DispatcherInvoke

public static Object DispatcherInvoke(JCObject target,
                                      String method,
                                      Object... params)
                               throws JCNativeException

Invokes an instance method on a CLR object using the WPF Dispatcher thread. Use this variant when the target is a WPF element that requires UI thread marshalling.

Parameters:

target - the JCObject on which to invoke the method.

method - the name of the CLR method to invoke.

params - optional arguments to pass to the method.

Returns:

the method return value, as a Java primitive or JCObject.

Throws:

JCNativeException - if the Dispatcher invocation fails.

DispatcherInvoke

public static Object DispatcherInvoke(JCType target,
                                      String method,
                                      Object... params)
                               throws JCNativeException

Invokes a static method on a CLR type using the WPF Dispatcher thread.

Parameters:

target - the JCType on which to invoke the static method.

method - the name of the CLR static method to invoke.

params - optional arguments to pass to the method.

Returns:

the method return value, as a Java primitive or JCObject.

Throws:

JCNativeException - if the Dispatcher invocation fails.

Get

public Object Get(String field)
           throws JCNativeException

Retrieves an instance property or field value from the underlying CLR control. For WPF controls, use DispatcherGet(JCObject, String) instead.

Parameters:

field - the name of the CLR property or field to read.

Returns:

the value, as a Java primitive or JCObject.

Throws:

JCNativeException - if the property or field cannot be found or the read fails.

DispatcherGet

public static Object DispatcherGet(JCObject target,
                                   String field)
                            throws JCNativeException

Retrieves an instance property or field value from a CLR object using the WPF Dispatcher thread.

Parameters:

target - the JCObject from which to read.

field - the name of the CLR property or field to read.

Returns:

the value, as a Java primitive or JCObject.

Throws:

JCNativeException - if the Dispatcher get fails.

DispatcherGet

public static Object DispatcherGet(JCType target,
                                   String field)
                            throws JCNativeException

Retrieves a static property or field value from a CLR type using the WPF Dispatcher thread.

Parameters:

target - the JCType from which to read.

field - the name of the CLR static property or field to read.

Returns:

the value, as a Java primitive or JCObject.

Throws:

JCNativeException - if the Dispatcher get fails.

Set

public JCObject Set(String field,
                    Object value)
             throws JCNativeException

Sets an instance property or field on the underlying CLR control. For WPF controls, use DispatcherSet(JCObject, String, Object) instead.

Parameters:

field - the name of the CLR property or field to write.

value - the value to assign.

Returns:

a JCObject representing the updated CLR control, for chaining.

Throws:

JCNativeException - if the property or field cannot be found or the write fails.

DispatcherSet

public static JCObject DispatcherSet(JCObject target,
                                     String field,
                                     Object value)
                              throws JCNativeException

Sets an instance property or field on a CLR object using the WPF Dispatcher thread.

Parameters:

target - the JCObject on which to write.

field - the name of the CLR property or field to write.

value - the value to assign.

Returns:

a JCObject representing the result, for chaining.

Throws:

JCNativeException - if the Dispatcher set fails.

DispatcherSet

public static JCObject DispatcherSet(JCType target,
                                     String field,
                                     Object value)
                              throws JCNativeException

Sets a static property or field on a CLR type using the WPF Dispatcher thread.

Parameters:

target - the JCType on which to write.

field - the name of the CLR static property or field to write.

value - the value to assign.

Returns:

a JCObject representing the result, for chaining.

Throws:

JCNativeException - if the Dispatcher set fails.

RegisterEventListener

public void RegisterEventListener(String eventName,
                                  IJCVoidEventEmit eventHandler)
                           throws JCNativeException,
                                  JCException

Registers a void-return CLR event handler on the underlying CLR control. Delegates to JCObject.RegisterEventListener(String, IJCVoidEventEmit).

Parameters:

eventName - the CLR event name to subscribe to.

eventHandler - the IJCVoidEventEmit handler to invoke when the event fires.

Throws:

JCNativeException - if the native registration fails.

JCException - if a handler for eventName is already registered.

RegisterEventListener

public void RegisterEventListener(String eventName,
                                  IJCEventEmit eventHandler)
                           throws JCNativeException,
                                  JCException

Registers a value-returning CLR event handler on the underlying CLR control. Delegates to JCObject.RegisterEventListener(String, IJCEventEmit).

Parameters:

eventName - the CLR event name to subscribe to.

eventHandler - the IJCEventEmit handler to invoke when the event fires.

Throws:

JCNativeException - if the native registration fails.

JCException - if a handler for eventName is already registered.

UnregisterEventListener

public void UnregisterEventListener(String eventName,
                                    IJCVoidEventEmit eventHandler)
                             throws JCNativeException,
                                    JCException

Unregisters a void-return CLR event handler from the underlying CLR control. Delegates to JCObject.UnregisterEventListener(String, IJCVoidEventEmit).

Parameters:

eventName - the CLR event name to unsubscribe from.

eventHandler - the IJCVoidEventEmit handler to remove.

Throws:

JCNativeException - if the native unregistration fails.

JCException - if no handler for eventName is registered.

UnregisterEventListener

public void UnregisterEventListener(String eventName,
                                    IJCEventEmit eventHandler)
                             throws JCNativeException,
                                    JCException

Unregisters a value-returning CLR event handler from the underlying CLR control. Delegates to JCObject.UnregisterEventListener(String, IJCEventEmit).

Parameters:

eventName - the CLR event name to unsubscribe from.

eventHandler - the IJCEventEmit handler to remove.

Throws:

JCNativeException - if the native unregistration fails.

JCException - if no handler for eventName is registered.

componentResized

public void componentResized(ComponentEvent e)

Notifies the CLR side of the new screen position and size so the embedded CLR control can be repositioned. Do not call directly.

Specified by:

componentResized in interface ComponentListener

componentMoved

public void componentMoved(ComponentEvent e)

Notifies the CLR side of the new screen position and size so the embedded CLR control can be repositioned. Do not call directly.

Specified by:

componentMoved in interface ComponentListener

componentShown

public void componentShown(ComponentEvent e)

Notifies the CLR side that this component is now visible and provides its current screen position and size. Do not call directly.

Specified by:

componentShown in interface ComponentListener

componentHidden

public void componentHidden(ComponentEvent e)

Notifies the CLR side that this component is hidden by passing zero bounds, allowing the CLR control to hide itself accordingly. Do not call directly.

Specified by:

componentHidden in interface ComponentListener

addNotify

public void addNotify()

Called when this component is connected to a native screen resource. Resolves the top-level ancestor and notifies the CLR side of the initial screen position and size. Do not call directly.

Overrides:

addNotify in class Component

removeNotify

public void removeNotify()

Called when this component is disconnected from its native screen resource. Unsubscribes the component listener from the top-level ancestor and notifies the CLR side with zero bounds so the CLR control hides itself. Do not call directly.

Overrides:

removeNotify in class Component

requestFocus

public void requestFocus()

Delegates the AWT focus request to the CLR side by invoking the CLR Focus() method on the hosted control. CLR exceptions during focus transfer are silently swallowed.

Overrides:

requestFocus in class Component