Class IconUtilities


  • public class IconUtilities
    extends java.lang.Object
    Utilities for loading and manipulating images and icons.
    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static java.awt.Image alterSaturation​(java.awt.Image i, double amount)
      Adjust the saturation of an image.
      static Icons createGrayedOutIcons​(Icons icons, double saturationAdjustment, float alpha)
      Creates and caches a version of the icons with less (or more) saturation and/or a change in alpha.
      static java.lang.String createIconHtmlTag​(Icons icons, int size)
      Takes an icon and saves it to disk and then returns an html img tag referring to this image with an image resolution suitable for display on the highest resolution monitor on this system
      static java.net.URL createIconUrl​(javax.swing.Icon icon)
      Takes an icon and saves it to disk so then returns the path to the image file.
      static java.awt.Image createImageFromIcon​(javax.swing.Icon icon)
      Creates an image from the given icon.
      static Icons getAliasOverlayIconForIcon​(Icons originalIcons)
      When given the icon for a document, returns the same icon overlayed with an alias icon.
      static Icons getCategoryDefaultIcons​(GeneiousActionOptions.Category category)
      Get the default Icons for the specified action category.
      static java.awt.Image getColoredImage​(java.awt.Image image, java.awt.Color color)
      Moves the colors in this image towards the given color.
      static Icons getGrayedOutIconsOriginal​(Icons icons)
      Get the non-grayed out version of Icons, IF createGrayedOutIcons(com.biomatters.geneious.publicapi.plugin.Icons, double, float) was used to create the grayed out version.
      static Icons getIcons​(java.lang.String iconNameOrPath)
      Create an Icons from an image file on disk.
      static Icons getIcons​(java.lang.String... iconNamesOrPaths)
      Create an Icons from image files on disk: multiple sized renderings of the same image (typically 16x16 pixels, 32x32 (for document icons) and 24x24 (for toolbar icons), or double these sizes to support Hi-DPI displays).
      static Icons getIcons​(java.lang.String smallIconNameOrPath, java.lang.String largeIconNameOrPath)
      Create an Icons from two image files on disk: a small and a large version of the image (typically 16x16 pixels and 32x32 (for document icons) or 24x24 (for toolbar icons)).
      static Icons getIconsFromJar​(java.lang.Class aClass, java.lang.String iconNameOrPath)
      Create an Icons from an image file in a resource bundle (jar).
      static Icons getIconsFromJar​(java.lang.Class aClass, java.lang.String... iconPaths)
      Create an Icons from image files from a resource bundle (jar).
      static Icons getIconsFromJar​(java.lang.Class aClass, java.lang.String smallIconPath, java.lang.String largeIconPath)
      Create and Icons from two image files from a resource bundle (jar).
      static Icons getIconsFromPrefix​(java.lang.String prefix)
      Returns the 16, 24, 32, 48 and 64 sized icons for the given prefix.
      static java.lang.String getIconsName​(Icons icons)
      Get a string name of an icon for the purposes of lexicographic comparison.
      static java.awt.Image getImage​(java.lang.String imageName)
      Create an Image from an image file on disk.
      static java.awt.Image getImageFromJar​(java.lang.Class aClass, java.lang.String imageFilePath)
      Create and Image from an image file in a resource bundle (jar).
      static void waitForImageToLoad​(java.awt.Image image)
      Waits until an image has finished loading or returns immediately if it is already loaded.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Method Detail

      • alterSaturation

        public static java.awt.Image alterSaturation​(java.awt.Image i,
                                                     double amount)
        Adjust the saturation of an image.
        Parameters:
        i - The image to filter
        amount - 0 means 0 saturation (black and white), 1 gives no change, and > 1 increases saturation. Negative values are awesome.
        Returns:
        a copy of the image with altered saturation
      • waitForImageToLoad

        public static void waitForImageToLoad​(java.awt.Image image)
        Waits until an image has finished loading or returns immediately if it is already loaded.
        Parameters:
        image - the image to wait for
      • getIconsName

        public static java.lang.String getIconsName​(Icons icons)
        Get a string name of an icon for the purposes of lexicographic comparison. This is often the file name of the icon used to create the icons originally, but this is not guaranteed.
        Parameters:
        icons - Icons to get the name for
        Returns:
        a string name of an icon for the purposes of lexicographic comparison, not null.
      • getIcons

        public static Icons getIcons​(java.lang.String iconNameOrPath)
        Create an Icons from an image file on disk. If no directory path is specified to the image file then it assumed to be in the standard Geneious image directory (resources/images)

        Supported formats include png, jpeg and gif (plus any others supported by the standard java toolkit).

        Parameters:
        iconNameOrPath - path to the image file (if this parameter contains a file separator) or the name of an image file in the standard Geneious image directory (resources/images) otherwise.
        Returns:
        Icons or null if not found.
      • getIcons

        public static Icons getIcons​(java.lang.String... iconNamesOrPaths)
        Create an Icons from image files on disk: multiple sized renderings of the same image (typically 16x16 pixels, 32x32 (for document icons) and 24x24 (for toolbar icons), or double these sizes to support Hi-DPI displays). If no directory path is specified to the image file then it assumed to be in the standard Geneious image directory (resources/images)

        Supported formats include png, jpeg and gif (plus any others supported by the standard java toolkit).

        Parameters:
        iconNamesOrPaths - paths to the image file (if this parameter contains a file separator) or the names of image files in the standard Geneious image directory (resources/images) otherwise.
        Returns:
        Icons or null if one or more icons specified are not found.
        Since:
        API 4.201910 (Geneious 2019.1.0)
      • getIconsFromPrefix

        public static Icons getIconsFromPrefix​(java.lang.String prefix)
        Returns the 16, 24, 32, 48 and 64 sized icons for the given prefix. Or null if every single one of these icons could not be found.
        Parameters:
        prefix - The prefix which all the icons start with.
        Returns:
        Icons containing all the size icons available under this prefix. Null if no icons were found for this prefix.
        Since:
        API 4.202100 (Geneious 2021.0.0)
      • getIcons

        public static Icons getIcons​(java.lang.String smallIconNameOrPath,
                                     java.lang.String largeIconNameOrPath)
        Create an Icons from two image files on disk: a small and a large version of the image (typically 16x16 pixels and 32x32 (for document icons) or 24x24 (for toolbar icons)). If no directory path is specified to the image file then it assumed to be in the standard Geneious image directory (resources/images)

        Supported formats include png, jpeg and gif (plus any others supported by the standard java toolkit).

        Parameters:
        smallIconNameOrPath - path to the small image file (if this parameter contains a file separator) or the name of an image file in the standard Geneious image directory (resources/images) otherwise.
        largeIconNameOrPath - path to the large image file (if this parameter contains a file separator) or the name of an image file in the standard Geneious image directory (resources/images) otherwise.
        Returns:
        Icons or null if not found.
      • getIconsFromJar

        public static Icons getIconsFromJar​(java.lang.Class aClass,
                                            java.lang.String iconNameOrPath)
        Create an Icons from an image file in a resource bundle (jar). The path to the image file is obtained as a resource of the given class. If you wish to obtain an image packaged in the root of a jar file, the path must be preceded with a '/'.

        Supported formats include png, jpeg and gif (plus any others supported by the standard java toolkit).

        For example, if you have bundled an image file "smiley.png" in the root of your plugin jar file, you can create Icons like this:

         Icons smileyIcons = IconUtilities.getIconsFromJar(MyPlugin.class, "/smiley.png")
         
        Parameters:
        aClass - The class to get the image resource for (a class in the jar of interest)
        iconNameOrPath - Path to the image file, either absolute within the jar (if preceded by a '/') or relative to the specified class (if not preceded by a '/').
        Returns:
        Icons loaded from the specified file.
        See Also:
        Class.getResource(String)
      • getIconsFromJar

        public static Icons getIconsFromJar​(java.lang.Class aClass,
                                            java.lang.String... iconPaths)
        Create an Icons from image files from a resource bundle (jar). The paths to the image files are obtained as resources of the given class. If you wish to obtain an image packaged in the root of a jar file, the path must be preceded with a '/'.

        Supported formats include png, jpeg and gif (plus any others supported by the standard java toolkit).

        For example, if you have two bundled image files "smiley16.png" and "smiley32.png" in the root of your plugin jar file, you can create Icons like this:

         Icons smileyIcons = IconUtilities.getIconsFromJar(MyPlugin.class, "/smiley16.png", "/smiley32.png");
         
        Parameters:
        aClass - The class to get the image resource for (a class in the jar of interest)
        iconPaths - Paths to the image files, either absolute within the jar (if preceded by a '/') or relative to the specified class (if not preceded by a '/').
        Returns:
        Icons loaded from the specified files.
        Throws:
        java.lang.IllegalArgumentException - if one or more of the icons cannot be found.
        Since:
        API 4.201910 (Geneious 2019.1.0)
        See Also:
        Class.getResource(String)
      • getIconsFromJar

        public static Icons getIconsFromJar​(java.lang.Class aClass,
                                            java.lang.String smallIconPath,
                                            java.lang.String largeIconPath)
        Create and Icons from two image files from a resource bundle (jar). The paths to the image files are obtained as resources of the given class. If you wish to obtain an image packaged in the root of a jar file, the path must be preceded with a '/'.

        Supported formats include png, jpeg and gif (plus any others supported by the standard java toolkit).

        For example, if you have two bundled image files "smiley16.png" and "smiley32.png" in the root of your plugin jar file, you can create Icons like this:

         Icons smileyIcons = IconUtilities.getIconsFromJar(MyPlugin.class, "/smiley16.png", "/smiley32.png");
         
        Parameters:
        aClass - The class to get the image resource for (a class in the jar of interest)
        smallIconPath - Path to the small image file, either absolute within the jar (if preceded by a '/') or relative to the specified class (if not preceded by a '/').
        largeIconPath - Path to the large image file, either absolute within the jar (if preceded by a '/') or relative to the specified class (if not preceded by a '/').
        Returns:
        Icons loaded from the specified file.
        See Also:
        Class.getResource(String)
      • getImageFromJar

        public static java.awt.Image getImageFromJar​(java.lang.Class aClass,
                                                     java.lang.String imageFilePath)
        Create and Image from an image file in a resource bundle (jar). The path to the image is obtained as a resource of the given class. If you wish to obtain an image packaged in the root of a jar file, the path must be preceded with a '/'.

        Supported formats include png, jpeg and gif (plus any others supported by the standard java toolkit).

        For example, if you have bundled an image file "smiley.png" in the root of your plugin jar file, you can load it like this:

         Image smileyImage = IconUtilities.getImageFromJar(MyPlugin.class, "/smiley.png")
         
        Parameters:
        aClass - The class to get the image resource for (a class in the jar of interest)
        imageFilePath - Path to the image file, either absolute within the jar (if preceded by a '/') or relative to the specified class (if not preceded by a '/').
        Returns:
        Image loaded from the specified file.
        See Also:
        Class.getResource(String)
      • getImage

        public static java.awt.Image getImage​(java.lang.String imageName)
        Create an Image from an image file on disk. If no directory path is specified to the image file then it assumed to be in the standard Geneious image directory (resources/images)

        Supported formats include png, jpeg and gif (plus any others supported by the standard java toolkit).

        Parameters:
        imageName - actual image file name from images folder (including extension).
        Returns:
        image or null if not found.
      • createIconHtmlTag

        public static java.lang.String createIconHtmlTag​(Icons icons,
                                                         int size)
        Takes an icon and saves it to disk and then returns an html img tag referring to this image with an image resolution suitable for display on the highest resolution monitor on this system
        Parameters:
        icons - the icons to create an html tag for
        size - the size of the image in pixels on a standard resolution screen. On high resolution screens the image will appear the same size, but will be backed by a higher resolution image. Warning: Do not statically cache the return value from this method since it will become invalid if the user changes their data location.
        Returns:
        an html img tag of the form <img>...</img>
        Since:
        API 4.202101 (Geneious 2021.0.1)
      • createIconUrl

        public static java.net.URL createIconUrl​(javax.swing.Icon icon)
        Takes an icon and saves it to disk so then returns the path to the image file. This allows html to display an Icon objects from memory. This function caches so that if it is called within the same session with the same Icon object it will return the path to the previously saved Icon.

        Warning: Do not statically cache the return value from this method since it will become invalid if the user changes their data location.

        Parameters:
        icon - Icon to create a path for
        Returns:
        path (relative to working directory) to a saved copy of this Icon.
      • createGrayedOutIcons

        public static Icons createGrayedOutIcons​(Icons icons,
                                                 double saturationAdjustment,
                                                 float alpha)
        Creates and caches a version of the icons with less (or more) saturation and/or a change in alpha. Used for operations not matching the selection signature and summary documents.
        Parameters:
        icons - Icons to adjust
        saturationAdjustment - amount 0 means 0 saturation (black and white), 1 gives no change, and > 1 increases saturation. Negative values are awesome.
        alpha - 0 for transparent, 1 for no change (opaque), in between for translucent.
        Returns:
        the grayed out version of icons
      • getAliasOverlayIconForIcon

        public static Icons getAliasOverlayIconForIcon​(Icons originalIcons)
        When given the icon for a document, returns the same icon overlayed with an alias icon. This is the recommended way of getting an alias icon as it will return a specialized alias icon for all standard document icons.
        Parameters:
        originalIcons - The original icons. For consistency we recommend using icons generated via StandardIcon.getIcons() for this parameter.
        Returns:
        the originalIcons overlayed with a small alias icon which is usually a black arrow in the bottom left.
        Since:
        API 4.202200 (Geneious 2022.0.0)
      • createImageFromIcon

        public static java.awt.Image createImageFromIcon​(javax.swing.Icon icon)
        Creates an image from the given icon. The image will have the same dimensions as the icon.
        Parameters:
        icon - The icon from which to create the image
        Returns:
        The image
        Since:
        API 4.201910 (Geneious 2019.1.0)
      • getColoredImage

        public static java.awt.Image getColoredImage​(java.awt.Image image,
                                                     java.awt.Color color)
        Moves the colors in this image towards the given color. For example, this is how folder images are assigned the color the user chooses in the service tree.
        Parameters:
        image - the image to create a copy of for coloring
        color - the color to modify the image towards
        Returns:
        a new image colored towards the given color
        Since:
        4.810 (Geneious 8.1.0)