com.dlsc.flexgantt.swing.util

## Class GraphicsUtilities

- java.lang.Object
- - com.dlsc.flexgantt.swing.util.GraphicsUtilities

-     public class GraphicsUtilities
      extends Object

  `GraphicsUtilities` contains a set of tools to perform common graphics operations easily. These operations are divided into several themes, listed below.

  ## Compatible Images

  Compatible images can, and should, be used to increase drawing performance. This class provides a number of methods to load compatible images directly from files or to convert existing images to compatibles images.

  ## Creating Thumbnails

  This class provides a number of methods to easily scale down images. Some of these methods offer a trade-off between speed and result quality and shouuld be used all the time. They also offer the advantage of producing compatible images, thus automatically resulting into better runtime performance.

  All these methodes are both faster than `Image.getScaledInstance(int, int, int)` and produce better-looking results than the various `drawImage()` methods in `Graphics`, which can be used for image scaling.

  ## Image Manipulation

  This class provides two methods to get and set pixels in a buffered image. These methods try to avoid unmanaging the image in order to keep good performance.

  Author:
    Romain Guy , rbair

- - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static BufferedImage` | `createColorModelCompatibleImage(BufferedImage image)` Returns a new `BufferedImage` using the same color model as the image passed as a parameter.
    `static BufferedImage` | `createCompatibleImage(BufferedImage image)` Returns a new compatible image with the same width, height and transparency as the image specified as a parameter.
    `static BufferedImage` | `createCompatibleImage(BufferedImage image, int width, int height)` Returns a new compatible image of the specified width and height, and the same transparency setting as the image specified as a parameter.
    `static BufferedImage` | `createCompatibleImage(int width, int height)` Returns a new opaque compatible image of the specified width and height.
    `static BufferedImage` | `createCompatibleTranslucentImage(int width, int height)` Returns a new translucent compatible image of the specified width and height.
    `static BufferedImage` | `createThumbnail(BufferedImage image, int newSize)` Returns a thumbnail of a source image.
    `static BufferedImage` | `createThumbnail(BufferedImage image, int newWidth, int newHeight)` Returns a thumbnail of a source image.
    `static BufferedImage` | `createThumbnailFast(BufferedImage image, int newSize)` Returns a thumbnail of a source image.
    `static BufferedImage` | `createThumbnailFast(BufferedImage image, int newWidth, int newHeight)` Returns a thumbnail of a source image.
    `static void` | `drawDropShadow(Component comp, Graphics2D g2d, int x, int y, int width)` Draws a drop shadow at the given location.
    `static void` | `drawDropShadow(Component comp, Graphics2D g2d, int x, int y, int width, int height)` Draws a drop shadow at the given location.
    `static int[]` | `getPixels(BufferedImage img, int x, int y, int w, int h, int[] pixels)` Returns an array of pixels, stored as integers, from a `BufferedImage`.
    `static BufferedImage` | `loadCompatibleImage(URL resource)` Returns a new compatible image from a URL.
    `static void` | `setPixels(BufferedImage img, int x, int y, int w, int h, int[] pixels)` Writes a rectangular area of pixels in the destination `BufferedImage`.
    `static BufferedImage` | `toCompatibleImage(BufferedImage image)` Return a new compatible image that contains a copy of the specified image.

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

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

- - ### Method Detail

    - #### createColorModelCompatibleImage

          public static BufferedImage createColorModelCompatibleImage(BufferedImage image)

      Returns a new `BufferedImage` using the same color model as the image passed as a parameter. The returned image is only compatible with the image passed as a parameter. This does not mean the returned image is compatible with the hardware.

      Parameters:
        `image` - the reference image from which the color model of the new image is obtained
      Returns:
        a new `BufferedImage`, compatible with the color model of `image`

    - #### createCompatibleImage

          public static BufferedImage createCompatibleImage(BufferedImage image)

      Returns a new compatible image with the same width, height and transparency as the image specified as a parameter. That is, the returned BufferedImage will be compatible with the graphics hardware. If this method is called in a headless environment, then the returned BufferedImage will be compatible with the source image.

      Parameters:
        `image` - the reference image from which the dimension and the transparency of the new image are obtained
      Returns:
        a new compatible `BufferedImage` with the same dimension and transparency as `image`
      See Also:
        `Transparency`, `createCompatibleImage(int, int)`, `createCompatibleImage(java.awt.image.BufferedImage, int, int)`, `createCompatibleTranslucentImage(int, int)`, `loadCompatibleImage(java.net.URL)`, `toCompatibleImage(java.awt.image.BufferedImage)`

    - #### createCompatibleImage

          public static BufferedImage createCompatibleImage(BufferedImage image,
                                                            int width,
                                                            int height)

      Returns a new compatible image of the specified width and height, and the same transparency setting as the image specified as a parameter. That is, the returned `BufferedImage` is compatible with the graphics hardware. If the method is called in a headless environment, then the returned BufferedImage will be compatible with the source image.

      Parameters:
        `width` - the width of the new image
        `height` - the height of the new image
        `image` - the reference image from which the transparency of the new image is obtained
      Returns:
        a new compatible `BufferedImage` with the same transparency as `image` and the specified dimension
      See Also:
        `Transparency`, `createCompatibleImage(java.awt.image.BufferedImage)`, `createCompatibleImage(int, int)`, `createCompatibleTranslucentImage(int, int)`, `loadCompatibleImage(java.net.URL)`, `toCompatibleImage(java.awt.image.BufferedImage)`

    - #### createCompatibleImage

          public static BufferedImage createCompatibleImage(int width,
                                                            int height)

      Returns a new opaque compatible image of the specified width and height. That is, the returned `BufferedImage` is compatible with the graphics hardware. If the method is called in a headless environment, then the returned BufferedImage will be compatible with the source image.

      Parameters:
        `width` - the width of the new image
        `height` - the height of the new image
      Returns:
        a new opaque compatible `BufferedImage` of the specified width and height
      See Also:
        `createCompatibleImage(java.awt.image.BufferedImage)`, `createCompatibleImage(java.awt.image.BufferedImage, int, int)`, `createCompatibleTranslucentImage(int, int)`, `loadCompatibleImage(java.net.URL)`, `toCompatibleImage(java.awt.image.BufferedImage)`

    - #### createCompatibleTranslucentImage

          public static BufferedImage createCompatibleTranslucentImage(int width,
                                                                       int height)

      Returns a new translucent compatible image of the specified width and height. That is, the returned `BufferedImage` is compatible with the graphics hardware. If the method is called in a headless environment, then the returned BufferedImage will be compatible with the source image.

      Parameters:
        `width` - the width of the new image
        `height` - the height of the new image
      Returns:
        a new translucent compatible `BufferedImage` of the specified width and height
      See Also:
        `createCompatibleImage(java.awt.image.BufferedImage)`, `createCompatibleImage(java.awt.image.BufferedImage, int, int)`, `createCompatibleImage(int, int)`, `loadCompatibleImage(java.net.URL)`, `toCompatibleImage(java.awt.image.BufferedImage)`

    - #### loadCompatibleImage

          public static BufferedImage loadCompatibleImage(URL resource)
                                                   throws IOException

      Returns a new compatible image from a URL. The image is loaded from the specified location and then turned, if necessary into a compatible image.

      Parameters:
        `resource` - the URL of the picture to load as a compatible image
      Returns:
        a new translucent compatible `BufferedImage` of the specified width and height
      Throws:
        `IOException` - if the image cannot be read or loaded
      See Also:
        `createCompatibleImage(java.awt.image.BufferedImage)`, `createCompatibleImage(java.awt.image.BufferedImage, int, int)`, `createCompatibleImage(int, int)`, `createCompatibleTranslucentImage(int, int)`, `toCompatibleImage(java.awt.image.BufferedImage)`

    - #### toCompatibleImage

          public static BufferedImage toCompatibleImage(BufferedImage image)

      Return a new compatible image that contains a copy of the specified image. This method ensures an image is compatible with the hardware, and therefore optimized for fast blitting operations.

      If the method is called in a headless environment, then the returned `BufferedImage` will be the source image.

      Parameters:
        `image` - the image to copy into a new compatible image
      Returns:
        a new compatible copy, with the same width and height and transparency and content, of `image`
      See Also:
        `createCompatibleImage(java.awt.image.BufferedImage)`, `createCompatibleImage(java.awt.image.BufferedImage, int, int)`, `createCompatibleImage(int, int)`, `createCompatibleTranslucentImage(int, int)`, `loadCompatibleImage(java.net.URL)`

    - #### createThumbnailFast

          public static BufferedImage createThumbnailFast(BufferedImage image,
                                                          int newSize)

      Returns a thumbnail of a source image. `newSize` defines the length of the longest dimension of the thumbnail. The other dimension is then computed according to the dimensions ratio of the original picture.

      This method favors speed over quality. When the new size is less than half the longest dimension of the source image, `createThumbnail(BufferedImage, int)` or `createThumbnail(BufferedImage, int, int)` should be used instead to ensure the quality of the result without sacrificing too much performance.

      Parameters:
        `image` - the source image
        `newSize` - the length of the largest dimension of the thumbnail
      Returns:
        a new compatible `BufferedImage` containing a thumbnail of `image`
      Throws:
        `IllegalArgumentException` - if `newSize` is larger than the largest dimension of `image` or <= 0
      See Also:
        `createThumbnailFast(java.awt.image.BufferedImage, int, int)`, `createThumbnail(java.awt.image.BufferedImage, int)`, `createThumbnail(java.awt.image.BufferedImage, int, int)`

    - #### createThumbnailFast

          public static BufferedImage createThumbnailFast(BufferedImage image,
                                                          int newWidth,
                                                          int newHeight)

      Returns a thumbnail of a source image.

      This method favors speed over quality. When the new size is less than half the longest dimension of the source image, `createThumbnail(BufferedImage, int)` or `createThumbnail(BufferedImage, int, int)` should be used instead to ensure the quality of the result without sacrificing too much performance.

      Parameters:
        `image` - the source image
        `newWidth` - the width of the thumbnail
        `newHeight` - the height of the thumbnail
      Returns:
        a new compatible `BufferedImage` containing a thumbnail of `image`
      Throws:
        `IllegalArgumentException` - if `newWidth` is larger than the width of `image` or if code>newHeight is larger than the height of `image` or if one of the dimensions is <= 0
      See Also:
        `createThumbnailFast(java.awt.image.BufferedImage, int)`, `createThumbnail(java.awt.image.BufferedImage, int)`, `createThumbnail(java.awt.image.BufferedImage, int, int)`

    - #### createThumbnail

          public static BufferedImage createThumbnail(BufferedImage image,
                                                      int newSize)

      Returns a thumbnail of a source image. `newSize` defines the length of the longest dimension of the thumbnail. The other dimension is then computed according to the dimensions ratio of the original picture.

      This method offers a good trade-off between speed and quality. The result looks better than `createThumbnailFast(java.awt.image.BufferedImage, int)` when the new size is less than half the longest dimension of the source image, yet the rendering speed is almost similar.

      Parameters:
        `image` - the source image
        `newSize` - the length of the largest dimension of the thumbnail
      Returns:
        a new compatible `BufferedImage` containing a thumbnail of `image`
      Throws:
        `IllegalArgumentException` - if `newSize` is larger than the largest dimension of `image` or <= 0
      See Also:
        `createThumbnailFast(java.awt.image.BufferedImage, int, int)`, `createThumbnailFast(java.awt.image.BufferedImage, int)`, `createThumbnail(java.awt.image.BufferedImage, int, int)`

    - #### createThumbnail

          public static BufferedImage createThumbnail(BufferedImage image,
                                                      int newWidth,
                                                      int newHeight)

      Returns a thumbnail of a source image.

      This method offers a good trade-off between speed and quality. The result looks better than `createThumbnailFast(java.awt.image.BufferedImage, int)` when the new size is less than half the longest dimension of the source image, yet the rendering speed is almost similar.

      Parameters:
        `image` - the source image
        `newWidth` - the width of the thumbnail
        `newHeight` - the height of the thumbnail
      Returns:
        a new compatible `BufferedImage` containing a thumbnail of `image`
      Throws:
        `IllegalArgumentException` - if `newWidth` is larger than the width of `image` or if code>newHeight is larger than the height of `image or if one the dimensions is not > 0`
      See Also:
        `createThumbnailFast(java.awt.image.BufferedImage, int)`, `createThumbnailFast(java.awt.image.BufferedImage, int, int)`, `createThumbnail(java.awt.image.BufferedImage, int)`

    - #### getPixels

          public static int[] getPixels(BufferedImage img,
                                        int x,
                                        int y,
                                        int w,
                                        int h,
                                        int[] pixels)

      Returns an array of pixels, stored as integers, from a `BufferedImage`. The pixels are grabbed from a rectangular area defined by a location and two dimensions. Calling this method on an image of type different from `BufferedImage.TYPE_INT_ARGB` and `BufferedImage.TYPE_INT_RGB` will unmanage the image.

      Parameters:
        `img` - the source image
        `x` - the x location at which to start grabbing pixels
        `y` - the y location at which to start grabbing pixels
        `w` - the width of the rectangle of pixels to grab
        `h` - the height of the rectangle of pixels to grab
        `pixels` - a pre-allocated array of pixels of size w*h; can be null
      Returns:
        `pixels` if non-null, a new array of integers otherwise
      Throws:
        `IllegalArgumentException` - is `pixels` is non-null and of length < w*h

    - #### setPixels

          public static void setPixels(BufferedImage img,
                                       int x,
                                       int y,
                                       int w,
                                       int h,
                                       int[] pixels)

      Writes a rectangular area of pixels in the destination `BufferedImage`. Calling this method on an image of type different from `BufferedImage.TYPE_INT_ARGB` and `BufferedImage.TYPE_INT_RGB` will unmanage the image.

      Parameters:
        `img` - the destination image
        `x` - the x location at which to start storing pixels
        `y` - the y location at which to start storing pixels
        `w` - the width of the rectangle of pixels to store
        `h` - the height of the rectangle of pixels to store
        `pixels` - an array of pixels, stored as integers
      Throws:
        `IllegalArgumentException` - is `pixels` is non-null and of length < w*h

    - #### drawDropShadow

          public static void drawDropShadow(Component comp,
                                            Graphics2D g2d,
                                            int x,
                                            int y,
                                            int width)

      Draws a drop shadow at the given location.
      Parameters:
        `comp` - the component where the shadow will be drawn
        `g2d` - the graphics context into which the shadow will be drawn
        `x` - the x location of the shadow
        `y` - the y location of the shadow
        `width` - the width of the shadow
      Since:
        2.0

    - #### drawDropShadow

          public static void drawDropShadow(Component comp,
                                            Graphics2D g2d,
                                            int x,
                                            int y,
                                            int width,
                                            int height)

      Draws a drop shadow at the given location.
      Parameters:
        `comp` - the component where the shadow will be drawn
        `g2d` - the graphics context into which the shadow will be drawn
        `x` - the x location of the shadow
        `y` - the y location of the shadow
        `width` - the width of the shadow
        `height` - the height of the shadow
      Since:
        2.0

Copyright © 2006–2020 Dirk Lemmermann Software & Consulting. All rights reserved.