Package com.sun.jna.platform

## Class WindowUtils

- java.lang.Object
- - com.sun.jna.platform.WindowUtils

-     public class WindowUtils
      extends java.lang.Object

  Provides additional features on a Java `Window`.
  - Non-rectangular shape (bitmap mask, no antialiasing)
  - Transparency (constant alpha applied to window contents or transparent background)
  - Fully transparent window (the transparency of all painted pixels is applied to the window).
  NOTE: since there is no explicit way to force PopupFactory to use a heavyweight popup, and anything but a heavyweight popup will be clipped by a window mask, an additional subwindow is added to all masked windows to implicitly force PopupFactory to use a heavyweight window and avoid clipping.

  NOTE: Neither shaped windows nor transparency currently works with Java 1.4 under X11. This is at least partly due to 1.4 using multiple X11 windows for a single given Java window. It *might* be possible to remedy by applying the window region/transparency to all descendants, but I haven't tried it. In addition, windows must be both displayable and visible before the corresponding native Drawable may be obtained; in later Java versions, the window need only be displayable.

  NOTE: If you use `setWindowMask(Window,Shape)` and override `Window.paint(Graphics)` on OS X, you'll need to explicitly set the clip mask on the `Graphics` object with the window mask; only the content pane of the window and below have the window mask automatically applied.

  NOTE: On OSX, the property `apple.awt.draggableWindowBackground` is set automatically when a window's background color has an alpha component. That property must be set to its final value before the heavyweight peer for the Window is created. Once `Component.addNotify()` has been called on the component, causing creation of the heavyweight peer, changing this property has no effect.

  Author:
    Andreas "PAX" Lück, onkelpax-git[at]yahoo.de
  See Also:
    Apple Technote 2007

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `WindowUtils.NativeWindowUtils` | Window utilities with differing native implementations.
    `protected static class` | `WindowUtils.RepaintTrigger` | This can be installed over a `JLayeredPane` in order to listen for repaint requests.

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static java.awt.Shape` | `MASK_NONE` | Use this to clear a window mask.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `WindowUtils()` |

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static java.util.List<DesktopWindow>` | `getAllWindows​(boolean onlyVisibleWindows)` | Requests a list of all currently available Desktop windows.
    `static java.awt.GraphicsConfiguration` | `getAlphaCompatibleGraphicsConfiguration()` | Returns a `GraphicsConfiguration` comptible with alpha compositing.
    `static java.awt.Dimension` | `getIconSize​(WinDef.HICON hIcon)` | Detects the size of an icon.
    `static java.lang.String` | `getProcessFilePath​(WinDef.HWND hwnd)` | Detects the full file path of the process associated with the specified window handle.
    `static java.awt.image.BufferedImage` | `getWindowIcon​(WinDef.HWND hwnd)` | Obtains the set icon for the window associated with the specified window handle.
    `static java.awt.Rectangle` | `getWindowLocationAndSize​(WinDef.HWND hwnd)` | Requests the location and size of the window associated with the specified window handle.
    `static java.lang.String` | `getWindowTitle​(WinDef.HWND hwnd)` | Tries to obtain the Window's title which belongs to the specified window handle.
    `static boolean` | `isWindowAlphaSupported()` | Indicate a window can have a global alpha setting.
    `static void` | `setComponentMask​(java.awt.Component c, java.awt.Shape mask)` | Applies the given mask to the given heavyweight component.
    `static void` | `setWindowAlpha​(java.awt.Window w, float alpha)` | Set the overall window transparency.
    `static void` | `setWindowMask​(java.awt.Window w, java.awt.Shape mask)` | Applies the given mask to the given window.
    `static void` | `setWindowMask​(java.awt.Window w, javax.swing.Icon mask)` | Applies the given mask to the given window.
    `static void` | `setWindowTransparent​(java.awt.Window w, boolean transparent)` | Set the window to be transparent.

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

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

- - ### Field Detail

    - #### MASK_NONE

          public static final java.awt.Shape MASK_NONE

      Use this to clear a window mask.

  - ### Constructor Detail

    - #### WindowUtils

          public WindowUtils()

  - ### Method Detail

    - #### setWindowMask

          public static void setWindowMask​(java.awt.Window w,
                                           java.awt.Shape mask)

      Applies the given mask to the given window. Does nothing if the operation is not supported. The mask is treated as a bitmap and ignores transparency.

    - #### setComponentMask

          public static void setComponentMask​(java.awt.Component c,
                                              java.awt.Shape mask)

      Applies the given mask to the given heavyweight component. Does nothing if the operation is not supported. The mask is treated as a bitmap and ignores transparency.

    - #### setWindowMask

          public static void setWindowMask​(java.awt.Window w,
                                           javax.swing.Icon mask)

      Applies the given mask to the given window. Does nothing if the operation is not supported. The mask is treated as a bitmap and ignores transparency.

    - #### isWindowAlphaSupported

          public static boolean isWindowAlphaSupported()

      Indicate a window can have a global alpha setting.

    - #### getAlphaCompatibleGraphicsConfiguration

          public static java.awt.GraphicsConfiguration getAlphaCompatibleGraphicsConfiguration()

      Returns a `GraphicsConfiguration` comptible with alpha compositing.

    - #### setWindowAlpha

          public static void setWindowAlpha​(java.awt.Window w,
                                            float alpha)

      Set the overall window transparency. An alpha of 1.0 is fully opaque, 0.0 fully transparent. The alpha level is applied equally to all window pixels.

      NOTE: Windows requires that `sun.java2d.noddraw=true` in order for alpha to work.

      NOTE: On OSX, the property `apple.awt.draggableWindowBackground` must be set to its final value before the heavyweight peer for the Window is created. Once `Component.addNotify()` has been called on the component, causing creation of the heavyweight peer, changing this property has no effect.

      See Also:
        Apple Technote 2007

    - #### setWindowTransparent

          public static void setWindowTransparent​(java.awt.Window w,
                                                  boolean transparent)

      Set the window to be transparent. Only explicitly painted pixels will be non-transparent. All pixels will be composited with whatever is under the window using their alpha values. On OSX, the property `apple.awt.draggableWindowBackground` must be set to its final value before the heavyweight peer for the Window is created. Once `Component.addNotify()` has been called on the component, causing creation of the heavyweight peer, changing this property has no effect.
      See Also:
        Apple Technote 2007

    - #### getWindowIcon

          public static java.awt.image.BufferedImage getWindowIcon​(WinDef.HWND hwnd)

      Obtains the set icon for the window associated with the specified window handle.
      Parameters:
        `hwnd` - The concerning window handle.
      Returns:
        Either the window's icon or `null` if an error occurred.

    - #### getIconSize

          public static java.awt.Dimension getIconSize​(WinDef.HICON hIcon)

      Detects the size of an icon.
      Parameters:
        `hIcon` - The icon handle type.
      Returns:
        Either the requested icon's dimension or an `Dimension` instance of `(0, 0)`.

    - #### getAllWindows

          public static java.util.List<DesktopWindow> getAllWindows​(boolean onlyVisibleWindows)

      Requests a list of all currently available Desktop windows.
      Parameters:
        `onlyVisibleWindows` - Specifies whether only currently visible windows will be considered (`true`). That are windows which are not minimized. The `WS_VISIBLE` flag will be checked (see: User32.IsWindowVisible(HWND)).
      Returns:
        A list with all windows and some detailed information.

    - #### getWindowTitle

          public static java.lang.String getWindowTitle​(WinDef.HWND hwnd)

      Tries to obtain the Window's title which belongs to the specified window handle.
      Parameters:
        `hwnd` - The concerning window handle.
      Returns:
        Either the title or an empty string of no title was found or an error occurred.

    - #### getProcessFilePath

          public static java.lang.String getProcessFilePath​(WinDef.HWND hwnd)

      Detects the full file path of the process associated with the specified window handle.
      Parameters:
        `hwnd` - The concerning window handle for which the PE file path is required.
      Returns:
        The full file path of the PE file that is associated with the specified window handle.

    - #### getWindowLocationAndSize

          public static java.awt.Rectangle getWindowLocationAndSize​(WinDef.HWND hwnd)

      Requests the location and size of the window associated with the specified window handle.
      Parameters:
        `hwnd` - The concerning window handle.
      Returns:
        The location and size of the window.