com.jogamp.newt.awt

## Class NewtCanvasAWT

- java.lang.Object
- - java.awt.Component
  - - java.awt.Canvas
    - - com.jogamp.newt.awt.NewtCanvasAWT

- All Implemented Interfaces:
    AWTPrintLifecycle, ImageObserver, MenuContainer, Serializable, Accessible, OffscreenLayerOption, WindowClosingProtocol

      public class NewtCanvasAWT
      extends Canvas
      implements WindowClosingProtocol, OffscreenLayerOption, AWTPrintLifecycle

  AWT `Canvas` containing a NEWT `Window` using native parenting.

  ##### Offscreen Layer Remarks

  `setShallUseOffscreenLayer(true)` maybe called to use an offscreen drawable (FBO or PBuffer) allowing the underlying JAWT mechanism to composite the image, if supported.
  See Also:
    Serialized Form

- - ### Nested Class Summary

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

      `Component.BaselineResizeBehavior`

    - ### Nested classes/interfaces inherited from interface javax.media.nativewindow.WindowClosingProtocol

      `WindowClosingProtocol.WindowClosingMode`

    - ### Nested classes/interfaces inherited from interface com.jogamp.nativewindow.awt.AWTPrintLifecycle

      `AWTPrintLifecycle.Context`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static boolean` | `DEBUG`

    - ### Fields inherited from class java.awt.Component

      `BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT`

    - ### Fields inherited from interface com.jogamp.nativewindow.awt.AWTPrintLifecycle

      `DEFAULT_PRINT_TILE_SIZE`

    - ### Fields inherited from interface java.awt.image.ImageObserver

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

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `NewtCanvasAWT()` Instantiates a NewtCanvas without a NEWT child.
    `NewtCanvasAWT(GraphicsConfiguration gc)` Instantiates a NewtCanvas without a NEWT child.
    `NewtCanvasAWT(GraphicsConfiguration gc, Window child)` Instantiates a NewtCanvas with a NEWT child.
    `NewtCanvasAWT(Window child)` Instantiates a NewtCanvas with a NEWT child.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addNotify()`
    `void` | `destroy()` Destroys this resource: Make the NEWT Child invisible Disconnects the NEWT Child from this Canvas NativeWindow, reparent to NULL Issues `destroy()` on the NEWT Child Remove reference to the NEWT Child
    `WindowClosingProtocol.WindowClosingMode` | `getDefaultCloseOperation()`
    `NativeWindow` | `getNativeWindow()`
    `Window` | `getNEWTChild()`
    `boolean` | `getShallUseOffscreenLayer()` Returns the property set by `OffscreenLayerOption.setShallUseOffscreenLayer(boolean)`.
    `boolean` | `getSkipJAWTDestroy()` See `setSkipJAWTDestroy(boolean)`.
    `boolean` | `isApplet()` Returns true if the AWT component is parented to an `Applet`, otherwise false.
    `boolean` | `isAWTEventPassThrough()` Returns `true` if Key and Mouse input events will be passed through AWT, otherwise only the `NEWT child` will receive them.
    `boolean` | `isOffscreenLayerSurfaceEnabled()` Returns true if this instance uses an offscreen layer, otherwise false.
    `void` | `paint(Graphics g)`
    `void` | `print(Graphics graphics)`
    `void` | `releasePrint()` Shall be called after `PrinterJob.print()`.
    `void` | `removeNotify()`
    `void` | `reshape(int x, int y, int width, int height)`
    `WindowClosingProtocol.WindowClosingMode` | `setDefaultCloseOperation(WindowClosingProtocol.WindowClosingMode op)`
    `Window` | `setNEWTChild(Window newChild)` Sets a new NEWT child, provoking reparenting.
    `void` | `setShallUseOffscreenLayer(boolean v)` Request an offscreen layer, if supported.
    `void` | `setSkipJAWTDestroy(boolean v)` Mitigates Bug 910 (IcedTea-Web), i.e.
    `void` | `setupPrint(double scaleMatX, double scaleMatY, int numSamples, int tileWidth, int tileHeight)` Shall be called before `PrinterJob.print()`.
    `void` | `update(Graphics g)`

    - ### Methods inherited from class java.awt.Canvas

      `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, contains, contains, createImage, createImage, createVolatileImage, createVolatileImage, deliverEvent, disable, dispatchEvent, doLayout, enable, enable, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, 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, paintAll, postEvent, preferredSize, prepareImage, prepareImage, printAll, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, repaint, requestFocus, requestFocusInWindow, 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, toString, transferFocus, transferFocusBackward, transferFocusUpCycle, validate`

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### DEBUG

          public static final boolean DEBUG

  - ### Constructor Detail

    - #### NewtCanvasAWT

          public NewtCanvasAWT()

      Instantiates a NewtCanvas without a NEWT child.

    - #### NewtCanvasAWT

          public NewtCanvasAWT(GraphicsConfiguration gc)

      Instantiates a NewtCanvas without a NEWT child.

    - #### NewtCanvasAWT

          public NewtCanvasAWT(Window child)

      Instantiates a NewtCanvas with a NEWT child.

    - #### NewtCanvasAWT

          public NewtCanvasAWT(GraphicsConfiguration gc,
                       Window child)

      Instantiates a NewtCanvas with a NEWT child.

  - ### Method Detail

    - #### setShallUseOffscreenLayer

          public void setShallUseOffscreenLayer(boolean v)

      Description copied from interface: `OffscreenLayerOption`
      Request an offscreen layer, if supported.

      Shall be called before the first `NativeSurface.lockSurface()`, and hence before realization.

      Specified by:
        `setShallUseOffscreenLayer` in interface `OffscreenLayerOption`
      See Also:
        `OffscreenLayerOption.getShallUseOffscreenLayer()`, `OffscreenLayerOption.isOffscreenLayerSurfaceEnabled()`

    - #### getShallUseOffscreenLayer

          public final boolean getShallUseOffscreenLayer()

      Description copied from interface: `OffscreenLayerOption`
      Returns the property set by `OffscreenLayerOption.setShallUseOffscreenLayer(boolean)`.
      Specified by:
        `getShallUseOffscreenLayer` in interface `OffscreenLayerOption`

    - #### isOffscreenLayerSurfaceEnabled

          public final boolean isOffscreenLayerSurfaceEnabled()

      Description copied from interface: `OffscreenLayerOption`
      Returns true if this instance uses an offscreen layer, otherwise false.

      This instance is an offscreen layer, if `setShallUseOffscreenLayer(true)` has been called before it's realization and first lock and the underlying implementation supports it.

      The return value is undefined before issuing the first `NativeSurface.lockSurface()`.
      Specified by:
        `isOffscreenLayerSurfaceEnabled` in interface `OffscreenLayerOption`
      See Also:
        `OffscreenLayerOption.setShallUseOffscreenLayer(boolean)`

    - #### isApplet

          public final boolean isApplet()

      Returns true if the AWT component is parented to an `Applet`, otherwise false. This information is valid only after `addNotify()` is issued.

    - #### setNEWTChild

          public Window setNEWTChild(Window newChild)

      Sets a new NEWT child, provoking reparenting.

      A previously detached `newChild` will be released to top-level status and made invisible.

      Note: When switching NEWT child's, detaching the previous first via `setNEWTChild(null)` produced much cleaner visual results.

      Returns:
        the previous attached newt child.

    - #### getNEWTChild

          public Window getNEWTChild()

      Returns:
        the current NEWT child

    - #### getNativeWindow

          public NativeWindow getNativeWindow()

      Returns:
        this AWT Canvas NativeWindow representation, may be null in case `removeNotify()` has been called, or `addNotify()` hasn't been called yet.

    - #### getDefaultCloseOperation

          public WindowClosingProtocol.WindowClosingMode getDefaultCloseOperation()

      Specified by:
        `getDefaultCloseOperation` in interface `WindowClosingProtocol`
      Returns:
        the current close operation value
      See Also:
        `WindowClosingProtocol.WindowClosingMode.DISPOSE_ON_CLOSE`, `WindowClosingProtocol.WindowClosingMode.DO_NOTHING_ON_CLOSE`

    - #### setDefaultCloseOperation

          public WindowClosingProtocol.WindowClosingMode setDefaultCloseOperation(WindowClosingProtocol.WindowClosingMode op)

      Specified by:
        `setDefaultCloseOperation` in interface `WindowClosingProtocol`
      Parameters:
        `op` - the new close operation value
      Returns:
        the previous close operation value
      See Also:
        `WindowClosingProtocol.WindowClosingMode.DISPOSE_ON_CLOSE`, `WindowClosingProtocol.WindowClosingMode.DO_NOTHING_ON_CLOSE`

    - #### setSkipJAWTDestroy

          public final void setSkipJAWTDestroy(boolean v)

      Mitigates Bug 910 (IcedTea-Web), i.e. crash via removeNotify() invoked before Applet.destroy().

      `skipJAWTDestroy` defaults to `false`. Due to above IcedTea-Web issue the `Applet` code needs to avoid JAWT destruction before `Applet.destroy()` is reached by setting `skipJAWTDestroy` to `true`. Afterwards the value should be reset to `false` and `destroy()` needs to be called, which finally will perform the pending JAWT destruction.

    - #### getSkipJAWTDestroy

          public final boolean getSkipJAWTDestroy()

      See `setSkipJAWTDestroy(boolean)`.

    - #### addNotify

          public void addNotify()

      Overrides:
        `addNotify` in class `Canvas`

    - #### removeNotify

          public void removeNotify()

      Overrides:
        `removeNotify` in class `Component`

    - #### destroy

          public final void destroy()

      Destroys this resource:
      - Make the NEWT Child invisible
      - Disconnects the NEWT Child from this Canvas NativeWindow, reparent to NULL
      - Issues `destroy()` on the NEWT Child
      - Remove reference to the NEWT Child
      See Also:
        `Window.destroy()`

    - #### paint

          public void paint(Graphics g)

      Overrides:
        `paint` in class `Canvas`

    - #### update

          public void update(Graphics g)

      Overrides:
        `update` in class `Canvas`

    - #### reshape

          public void reshape(int x,
                     int y,
                     int width,
                     int height)

      Overrides:
        `reshape` in class `Component`

    - #### setupPrint

          public void setupPrint(double scaleMatX,
                        double scaleMatY,
                        int numSamples,
                        int tileWidth,
                        int tileHeight)

      Description copied from interface: `AWTPrintLifecycle`
      Shall be called before `PrinterJob.print()`.

      See Usage.

      Specified by:
        `setupPrint` in interface `AWTPrintLifecycle`
      Parameters:
        `scaleMatX` - `Graphics2D` `scaling factor`, i.e. rendering 1/scaleMatX * width pixels
        `scaleMatY` - `Graphics2D` `scaling factor`, i.e. rendering 1/scaleMatY * height pixels
        `numSamples` - multisampling value: < 0 turns off, == 0 leaves as-is, > 0 enables using given num samples
        `tileWidth` - custom tile width for `tile renderer`, pass -1 for default.
        `tileHeight` - custom tile height for `tile renderer`, pass -1 for default.

    - #### releasePrint

          public void releasePrint()

      Description copied from interface: `AWTPrintLifecycle`
      Shall be called after `PrinterJob.print()`.

      See Usage.

      Specified by:
        `releasePrint` in interface `AWTPrintLifecycle`

    - #### print

          public void print(Graphics graphics)

      Overrides:
        `print` in class `Component`

    - #### isAWTEventPassThrough

          public final boolean isAWTEventPassThrough()

      Returns `true` if Key and Mouse input events will be passed through AWT, otherwise only the `NEWT child` will receive them.

      Normally only the `NEWT child` will receive Key and Mouse input events. In offscreen mode, e.g. OSX/CALayer, the AWT events will be received and translated into NEWT events and delivered to the NEWT child window.
      Note: AWT key events will `consumed` in pass-through mode.

Copyright 2010 JogAmp Community.