Package resources

Class ResourceKit


  • public class ResourceKit
    extends java.lang.Object
    The resource kit manages a virtual resource folder that combines resources from many sources (main application, installed plug-in bundles, project folder, etc.) into a single virtual file system. Resources in this file system are identified using a relative URL-like syntax with three parts (two of which are optional):

    [/] [folder/]* file.ext

    1. The first part is the least used and most technical:
      If the first character is a slash (/), then the identifier is absolute; otherwise the rest of the name is relative to /resources. (Resources are normally stored in the resources folder of the file system; however, sometimes it is useful to access a resource that is in the classpath of the application or a plug-in bundle. This can be done using an absolute identifier.)
    2. The second part consists of zero or more folder names separated by slashes.
    3. The third part, the only part which must be present, is the file identifier. Note that a path that ends in a folder name instead of a file name is not considered valid. The result of using such an identifier is undefined.
    In order to locate the actual resource file for a resource name, call composeResourceURL(java.lang.String) with the identifier. This will return a URL that can be used to access the resource, or null if the resource cannot be found.

    Alternatively, you can create a URL object for a resource using the special protocol res:, for example:
    URL u = new URL( "res://icons/application/app.png" );

    Note that the URLs produced with these two different methods are not the same. A res: URL is a URL for the virtual file system, while composeResourceURL returns a URL for the actual location of the file. In fact, when you try to access a res: URL's data using a method like openStream, the protocol handler will itself call composeResourceURL to find the file in question.

    Since:
    1.0
    Author:
    Chris Jennings
    • Method Summary

      All Methods Static Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      static java.net.URL composeResourceURL​(java.lang.String resource)
      Returns the URL of a resource from a path and file relative to a conceptual resources folder.
      static java.awt.image.BufferedImage createBleedBanner​(java.awt.Image source)
      Deprecated.
      static ThemedIcon createBleedBanner​(java.lang.String resource)
      Returns a bleed banner icon.
      static java.awt.Cursor createCustomCursor​(java.lang.String resourceName)
      Creates a custom cursor from a base resource name.
      static java.awt.Cursor createCustomCursor​(java.lang.String cursorImage, java.awt.Point hotspot, java.lang.String cursorName, java.awt.Cursor fallback)
      Creates a custom cursor using an image resource, which may be a multiresolution image resource.
      static javax.print.attribute.PrintRequestAttributeSet createPrintRequestAttributeSet​(java.awt.print.PrinterJob job)
      Creates a new, mutable print request attribute set based on the application preference settings.
      static AnimatedIcon createWaitIcon​(javax.swing.JComponent comp)
      Creates a new wait icon (an animated icon that indicates a lengthy delay).
      static java.awt.Font enableKerningAndLigatures​(java.awt.Font font)
      Returns a font instance that is equivalent to font but which will default to using kerning and ligatures (if available for the font and if supported by the particular rendering method).
      static double estimateDesktopScalingFactor()
      Returns an estimate of the desktop scaling factor of the primary display.
      static java.lang.String findAvailableFontFamily​(java.lang.String familyList, java.lang.String defaultFamily)
      Returns the first font family that is installed from a comma-separated list of font families.
      static java.net.URL findResourceInProject​(java.lang.String resource)
      Searches for a resource in the open project.
      static java.lang.String getBodyFamily()
      Returns the family name of the standard body font: this is the default Times-like serif font that is the default font for markup on game components.
      static java.awt.Font getBodyFont()
      Returns a Font instance for the standard body font: this is the default Times-like serif font that is the default font for markup on game components.
      static java.awt.Font getEditorFont()
      Returns the default font for editing markup in a text field.
      static java.awt.Font getFont​(java.lang.String resource, float pointSize)
      Creates a single font from a file in the application resources.
      static GameComponent getGameComponentFromFile​(java.io.File file)
      Reads a GameComponent from a file.
      static GameComponent getGameComponentFromFile​(java.io.File file, boolean reportError)
      Reads a GameComponent from a file.
      static GameComponent getGameComponentFromStream​(java.io.InputStream in, java.lang.String sourceDescription, boolean reportError)
      Reads a GameComponent from an input stream.
      static ThemedIcon getIcon​(java.lang.String iconResource)
      Returns an icon created from an image resource.
      static java.lang.String getIdentifier​(java.lang.Class<?> base, java.lang.String relativePathToResource)
      Returns a resource path for a resource that is relative to the specified class.
      static java.awt.image.BufferedImage getImage​(java.lang.String resource)
      Given the path to a resource file containing an image, returns the image.
      static java.awt.image.BufferedImage getImageQuietly​(java.lang.String resource)
      This method returns an image as if by getImage(java.lang.String), but without obvious feedback for the user.
      static java.awt.image.BufferedImage[] getImagesQuietly​(java.lang.String[] inputResources, java.awt.image.BufferedImage[] outputImages)
      Returns an array of image resources for the provided names.
      static java.io.InputStream getInputStream​(java.lang.String resource)
      Returns an input stream that can be used to read from the specified resource.
      static java.lang.String getMicroversionString()
      Deprecated.
      The complex microversion string has been replaced by a simple build number that is easier to compare when enabling version-dependent features.
      static java.awt.image.BufferedImage getMissingImage()
      Returns the stand-in image that is used when an image cannot be loaded.
      static VectorImage getMissingVectorImage()
      Returns the vector image used as a stand-in when a requested resource cannot be loaded.
      static CacheMetrics[] getRegisteredCacheMetrics()
      Returns an array of the currently registered cache metrics instances, sorted by name (that is, their toString() value).
      static java.awt.image.BufferedImage getThemedImage​(java.lang.String resource)
      Returns an image after allowing the installed theme an opportunity to modify it to match the interface theme.
      static java.awt.Font getTinyFont()
      Deprecated.
      This is no longer used within the application, and it is recommended not to use it in plug-ins or other projects as it may be removed in a future version.
      static VectorIcon getVectorIcon​(java.lang.String resource, int iconWidth, int iconHeight)
      Returns an icon that displays a vector image at the specified width and height.
      static VectorImage getVectorImage​(java.lang.String resource)
      Given the path to a resource file containing a vector image, returns the image.
      static void initializeFileDialogs()
      This method is called during startup to allow the resource kit to set up its shared file dialogs.
      static boolean isFamilyRegistered​(java.lang.String familyName)
      Returns true if one or more fonts with the specified family name have been registered through registerFont(java.lang.String).
      static boolean isResourceStatic​(java.net.URL composedResourceURL)
      Returns true if a resource file is not expected to change during the lifetime of the application.
      static java.lang.String makeStringFileSafe​(java.lang.String string)
      Strips illegal characters out of a potential file name.
      static java.lang.String makeStringHTMLSafe​(java.lang.String string)
      Makes a string safe for inclusion as literal HTML by escaping ampersands, less than symbols, and greater than symbols with their HTML entity expressions.
      static void missingKeyError​(java.lang.String key)  
      static java.lang.String normalizeFontFamilyName​(java.lang.String family)
      Normalizes a font family name provided by a user.
      static java.lang.String normalizeResourceIdentifier​(java.lang.String resource)
      Returns a normalized version of the identifier.
      static java.awt.image.BufferedImage prepareNewImage​(java.awt.Image image)
      Prepares a newly obtained image for use by ensuring that it is in the image format required by the application.
      static void registerCacheMetrics​(CacheMetrics cm)
      Registers a cache's metrics instance to make it available for lookup.
      static ResourceKit.FontRegistrationResult registerFont​(java.lang.String resourceFile)
      Attempts to register a single font.
      static ResourceKit.FontRegistrationResult[] registerFontFamily​(java.lang.String commaSeparatedList)
      Attempts to register a group of font resources as a single family.
      static java.io.File showBitmapImageFileDialog​(java.awt.Component parent)
      Displays a file dialog for opening a single image file that will accept only bitmap image formats (such as JPEG) and not vector image formats (such as SVG).
      static java.io.File showFolderDialog​(java.awt.Component parent, java.lang.String title, java.lang.String okText)  
      static java.io.File showGenericExportFileDialog​(java.awt.Component parent, java.lang.String basename, java.lang.String fileType, java.lang.String fileExtension)
      Displays a file dialog for exporting a file.
      static java.io.File showGenericOpenDialog​(java.awt.Component parent, java.io.File base, java.lang.String fileType, java.lang.String... fileExtensions)
      Displays a file dialog for opening a file.
      static java.io.File showGenericSaveDialog​(java.awt.Component parent, java.io.File base, java.lang.String fileTypeDescription, java.lang.String... fileNameExtensions)
      Displays a file dialog for saving a file.
      static java.io.File showImageFileDialog​(java.awt.Component parent)
      Displays a file dialog for opening a single image file.
      static java.io.File[] showMultiOpenDialog​(java.awt.Component parent)
      Displays a file dialog for opening multiple game components.
      static java.io.File showOpenDialog​(java.awt.Component parent)
      Displays a file dialog for opening a single game component.
      static java.io.File showPluginFileDialog​(java.awt.Component parent)
      Displays a file dialog for opening a plug-in bundle file.
      static boolean showPrintDialog​(java.awt.print.PrinterJob job)
      Shows a print dialog for a print job.
      static java.io.File showProjectFolderDialog​(java.awt.Component parent)
      Displays a file dialog for opening a project folder.
      static java.io.File showSaveDialog​(java.awt.Component parent, java.lang.String baseName)
      Displays a file dialog for saving a single game component.
      static java.io.File showScriptFileDialog​(java.awt.Component parent)
      Displays a file dialog for opening a script file.
      static java.io.File showZipFileDialog​(java.awt.Component parent, java.lang.String baseName)
      Displays a file dialog for exporting content to a ZIP archive.
      static void unregisterCacheMetrics​(CacheMetrics cm)
      Unregisters a cache's metrics instance.
      static void writeGameComponentToFile​(java.io.File f, GameComponent gc)
      Writes a GameComponent to a file.
      • Methods inherited from class java.lang.Object

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

      • getMicroversionString

        @Deprecated
        public static java.lang.String getMicroversionString()
        Deprecated.
        The complex microversion string has been replaced by a simple build number that is easier to compare when enabling version-dependent features. To obtain the build number, call StrangeEons.getBuildNumber().
        Returns a string that describes the specific build of this release of the application. This method is here only for backwards compatibility with old plug-ins.
        Returns:
        the microversion string for this build (the build number as a String)
      • estimateDesktopScalingFactor

        public static double estimateDesktopScalingFactor()
        Returns an estimate of the desktop scaling factor of the primary display.
        Returns:
        the scaling factor, or 1 if no scaling appears to be applied
      • composeResourceURL

        public static java.net.URL composeResourceURL​(java.lang.String resource)
        Returns the URL of a resource from a path and file relative to a conceptual resources folder. The conceptual resources folder typically represents many different virtual folders, including the resources folder of the main application and that of any installed plug-in bundles. If the requested file cannot be found, null will be returned.

        The contents of the virtual resources folder are determined by searching for the requested file in the following locations (in order until a file is found):

        1. If the resource path is actually an absolute URL then it is converted to a URL object and returned, except that if it is a res:// URL the procedure continues as if the res:// prefix was not present. Absolute URLs are indicated by the presence of a colon (:) in the identifier.
        2. The contents of the user resource folder, if any.
        3. The resources folders of the main application and all installed plug-in bundles, in the order of installation.
        4. The resources folder (if any) of all task folders in the open project. Note that this URL is typically only valid while the project is open. This is used when testing plug-in code in a project; resource paths in the code will locate the plug-in's resources as if it were installed.

        Folders: Resource identifiers can include relative paths, but the final part of the identifier must name a file, not a directory. The result of attempting to compose a resource URL that points to a directory, or of attempting to use such a URL should one be returned, if undefined.

        Case Sensitivity: Because the virtual file system actually reads its files from a mixture of sources, file names may or may not be case sensitive depending on where the actual file is located. Therefore, you should always assume that resource identifiers are case sensitive.

        Parameters:
        resource - a file path relative to the virtual resources folder
        Returns:
        a URL that can be used to access the named resource, or null
      • findResourceInProject

        public static java.net.URL findResourceInProject​(java.lang.String resource)
        Searches for a resource in the open project. This method can locate a resource within a project plug-in task folder by the same resource path that would be used to locate the resource if the plug-in were actually installed. This is essentially the final step in the algorithm used by composeResourceURL(java.lang.String) before it gives up and returns null.

        The process of finding a resource in a project consists of checking each plug-in task folder in turn, looking for a resources folder and then locating the resource relative to the folder.

        Parameters:
        resource - the resource path to search for
      • getIdentifier

        public static java.lang.String getIdentifier​(java.lang.Class<?> base,
                                                     java.lang.String relativePathToResource)
        Returns a resource path for a resource that is relative to the specified class.
        Parameters:
        base - the class that the resource is stored relative to
        relativePathToResource - the path to the resource relative to the class
        Returns:
        the resource path of the resource (whether or not it exists)
      • normalizeResourceIdentifier

        public static java.lang.String normalizeResourceIdentifier​(java.lang.String resource)
        Returns a normalized version of the identifier. Because composeResourceURL(java.lang.String) accepts both virtual resource paths and regular URLs, a given resource file can be accessed by multiple identifiers. This method reduces some (though not all) redundant names to their plain virtual resource path equivalent, if one exists. The intended purpose is to improve the efficiency of caching mechanisms or other cases where it could be useful to quickly detect that two different identifier strings actually refer to the same resource. Most plug-in developers will never have a reason to call this method.

        The precise effect of this method may change from version to version, but the following three conditions are guaranteed:

        1. If the identifier is null, it will be returned unchanged.
        2. If the identifier is a virtual resource path rather than an absolute URL, it will be returned unchanged and the method will return very quickly.
        3. If the identifier is an absolute URL identifier, then it may be changed to a virtual resource path that points to the same file.
        4. Any two identifiers that (a) are changed by this method and (b) refer to the same file will be changed to the same string.
        Parameters:
        resource - an identifier to normalize
        Returns:
        an equivalent (possibly identical) identifier
      • isResourceStatic

        public static boolean isResourceStatic​(java.net.URL composedResourceURL)
        Returns true if a resource file is not expected to change during the lifetime of the application. This can be used as a hint to caching mechanisms that the resource is safe to cache. For example, resources that come from an installed plug-in bundle can be cached because the bundle contents cannot change while the application is still running, while resources that come from a project must be handled more carefully because the user might modify them at any time.
        Parameters:
        composedResourceURL - the URL of the resource in question
        Returns:
        true if the resource cannot change while the application is running
        Since:
        3.0
      • getInputStream

        public static java.io.InputStream getInputStream​(java.lang.String resource)
                                                  throws java.io.IOException
        Returns an input stream that can be used to read from the specified resource.
        Parameters:
        resource - the relative location of a resource file
        Returns:
        an input stream that reads bytes from the resource
        Throws:
        java.io.FileNotFoundException - if the resource does not exist
        java.io.IOException - if an I/O error occurs while opening the stream
        java.lang.NullPointerException - if the specified resource is null
      • getIcon

        public static ThemedIcon getIcon​(java.lang.String iconResource)
        Returns an icon created from an image resource. By default, this method looks for the icon in the application's "icons" resource folder. Plug-ins that wish to load an icon from a different folder can override this by using a full "res://" resource descriptor or by starting the resource with a '/' and providing the full path to the resource. For example to load the icon from the resource "foo/icon.png", you could use either "res://foo/icon.png" or "/resources/foo/icon.png".

        The returned icon is a ThemedImageIcon instance. This means that the currently installed Theme will be given an opportunity to modify the resource location, modify the returned image before it is converted into an icon, or both.

        Parameters:
        iconResource - the resource identifier for the icon
        Returns:
        an icon consisting of the requested image or a theme-dependent substitute
        Throws:
        java.lang.NullPointerException - if iconResource is null
        See Also:
        Theme.applyThemeToImage(java.awt.image.BufferedImage)
      • getThemedImage

        public static java.awt.image.BufferedImage getThemedImage​(java.lang.String resource)
        Returns an image after allowing the installed theme an opportunity to modify it to match the interface theme. This should not be used on images that will be drawn on game components!
        Parameters:
        resource - the image resource to theme
        Returns:
        the themed version of the image
      • getImage

        public static java.awt.image.BufferedImage getImage​(java.lang.String resource)
        Given the path to a resource file containing an image, returns the image. If it exists and the file is valid, the returned image will use either the INT_RGB or INT_ARGB formats. (Or, if the setting premultiply-image-alpha is true, then a premultiplied equivalent.)

        The resource file must either be an image encoded in one of the supported file types (PNG, JPEG, or JPEG2000) or else a script file with the extension .js that contains a resource creation script. (See ScriptMonkey.runResourceCreationScript(java.lang.String).)

        If the file does not exist or is not a valid image file (or resource script), then a special "missing image" image is returned to indicate this visually to the user.

        Note that images may be cached, so if the resource is modified then the returned result may not reflect these changes.

        Parameters:
        resource - the relative file path of the image resource
        Returns:
        the image stored at the named resource, or a substitute missing image symbol
        Throws:
        java.lang.NullPointerException - if the resource identifier is null
        java.lang.IllegalArgumentException - if the resource identifier is empty
        See Also:
        isResourceStatic(java.net.URL)
      • getImageQuietly

        public static java.awt.image.BufferedImage getImageQuietly​(java.lang.String resource)
        This method returns an image as if by getImage(java.lang.String), but without obvious feedback for the user. The wait cursor is not set while loading the image, and an error dialog is not displayed if the attempt to load the image fails.
        Parameters:
        resource - the image resource path
        Returns:
        an image for the resource path
        Throws:
        java.lang.NullPointerException - if the resource identifier is null
        java.lang.IllegalArgumentException - if the resource identifier is empty
      • getImagesQuietly

        public static java.awt.image.BufferedImage[] getImagesQuietly​(java.lang.String[] inputResources,
                                                                      java.awt.image.BufferedImage[] outputImages)
        Returns an array of image resources for the provided names. Each name will be looked up and the matching image found as if by calling getImageQuietly(java.lang.String) for each name in turn, and placing the result at the matching index in the output array. The benefit of getting images with this method is that they can be loaded concurrently if the system has multiple processors (CPUs or cores).

        The supplied output array may be null, in which case a new array will be created. If a non-null output array is given, it must be at least as long as the number of names provided.

        Parameters:
        inputResources - image resources to load
        outputImages - an array to be filled in with the resulting images
        Returns:
        the output array that holds the images
        Throws:
        java.lang.NullPointerException - if any resource identifier is null
        java.lang.IllegalArgumentException - if any resource identifier is empty
      • getMissingImage

        public static java.awt.image.BufferedImage getMissingImage()
        Returns the stand-in image that is used when an image cannot be loaded.
        Returns:
        an image that provides a visual cue that the intended image is not available
      • prepareNewImage

        public static java.awt.image.BufferedImage prepareNewImage​(java.awt.Image image)
        Prepares a newly obtained image for use by ensuring that it is in the image format required by the application. For example, when an image is read from a file it may be returned as whatever type of image was the most convenient for the file format. This method will check the format of an image, convert it to the optimal format if necessary, and then return it. If no conversion is required, the original image is returned. Note that images that you obtain via the resource kit or other parts of the Strange Eons API will already be in the correct format.
        Parameters:
        image - the image to prepare
        Returns:
        an image in the correct format; either the original or a converted one, or null if image was null
      • getVectorImage

        public static VectorImage getVectorImage​(java.lang.String resource)
        Given the path to a resource file containing a vector image, returns the image. The resource file must be in the SVG format. Note that there are some limitations on the supported SVG features: SVG files with scripts are not supported at all, and filter effects are not completely supported.

        If the specified file does not exist or is not valid, a special "missing image" image is returned.

        Parameters:
        resource - the vector image resource to load
        Returns:
        a vector image created from the content of the resource, or the "missing image" vector image
        Since:
        3.0
      • getMissingVectorImage

        public static VectorImage getMissingVectorImage()
        Returns the vector image used as a stand-in when a requested resource cannot be loaded.
        Returns:
        the "missing image" vector image
      • getVectorIcon

        public static VectorIcon getVectorIcon​(java.lang.String resource,
                                               int iconWidth,
                                               int iconHeight)
        Returns an icon that displays a vector image at the specified width and height. The icon size can be changed later using methods in the returned VectorIcon.
        Parameters:
        resource - the image resource to create an icon of
        iconWidth - the initial width of the icon, in pixels
        iconHeight - the initial height of the icon, in pixels
        Returns:
        an new icon that paints the specified image
        See Also:
        getVectorImage(java.lang.String)
      • getBodyFont

        public static java.awt.Font getBodyFont()
        Returns a Font instance for the standard body font: this is the default Times-like serif font that is the default font for markup on game components. It is normally accessed by its family name via getBodyFamily() rather than by Font. Please see the documentation for that method for further details.
        Returns:
        an instance of the standard body font
        See Also:
        getBodyFamily()
      • getBodyFamily

        public static java.lang.String getBodyFamily()
        Returns the family name of the standard body font: this is the default Times-like serif font that is the default font for markup on game components. If the core typefaces library is installed, then this will return the core body font from that library. Otherwise, it will return a serif font that depends on the platform and available system fonts. (It is strongly recommended that the core typefaces library be installed so that game components will appear consistent across platforms.)
        Returns:
        the family name of the standard body font
      • getEditorFont

        public static java.awt.Font getEditorFont()
        Returns the default font for editing markup in a text field.
        Returns:
        the font to use for text editing
      • getTinyFont

        @Deprecated
        public static java.awt.Font getTinyFont()
        Deprecated.
        This is no longer used within the application, and it is recommended not to use it in plug-ins or other projects as it may be removed in a future version.
        Returns a font that is optimized for displaying characters at very small size. This is useful for dynamically creating small icons or other UI elements. The returned font is only guaranteed to support the basic ASCII character set, and might not include distinct lower case letters.
        Returns:
        a font optimized for small size
      • getFont

        public static java.awt.Font getFont​(java.lang.String resource,
                                            float pointSize)
                                     throws java.io.IOException
        Creates a single font from a file in the application resources. The font is not registered, meaning that it is not visible to the rest of the application if looked up by its family name.
        Parameters:
        resource - the font resource file
        Returns:
        an instance of the font at the requested point size
        Throws:
        java.lang.NullPointerException - if the resource is null
        InvalidFileFormatException - if the resource is not a supported font file format or the font is corrupt
        java.io.FileNotFoundException - if the resource file does not exist
        java.io.IOException - if an I/O error occurs while creating the font
        See Also:
        registerFont(java.lang.String), registerFontFamily(java.lang.String)
      • registerFont

        public static ResourceKit.FontRegistrationResult registerFont​(java.lang.String resourceFile)
                                                               throws java.io.IOException
        Attempts to register a single font. The font is first loaded from the resource file as if by using getFont(java.lang.String, float). If this is successful, then an attempt is made to register the font. A registered font can be created by its family name just as if it were installed in the user's operating system. For example, it can be used in markup boxes with the &lt;family&gt; tag or the font family text attribute. (If registration fails, it is usually because a font with the same name—possibly the same font—is installed on the user's system.)
        Parameters:
        resourceFile - the font resource file to register
        Returns:
        an object that provides access to the font, its family name, and the result of registration
        Throws:
        java.lang.NullPointerException - if the resource is null
        InvalidFileFormatException - if the resource is not a supported font file format or the font is corrupt
        java.io.FileNotFoundException - if the resource file does not exist
        java.io.IOException - if an I/O error occurs while creating the font
        See Also:
        getFont(java.lang.String, float), registerFontFamily(java.lang.String)
      • registerFontFamily

        public static ResourceKit.FontRegistrationResult[] registerFontFamily​(java.lang.String commaSeparatedList)
                                                                       throws java.io.IOException
        Attempts to register a group of font resources as a single family. (For example, the regular, bold, italic, and bold italic versions of the font.) The method takes a string containing a comma-separated list of resource files; each resource file is one of the fonts to register. The first entry in the list should be the regular variant of the file; the order of the remaining resources does not matter. Each resource in the list will be loaded and registered as if by registerFont(java.lang.String), and an array of registration results is returned. Typically, the caller will want to get the name of the font to use for TextStyles by calling ResourceKit.registerFontList( families )[0].getFamily().

        After the first entry in the list, subsequent entries will be assumed to be located in the same resource folder as the first entry if they do not include a '/' character. For example, the following list would load a family of two fonts located in the foo/fonts resource folder: foot/fonts/bar_regular.ttf, bar_italic.ttf.

        Parameters:
        commaSeparatedList - the list of resource files to register
        Returns:
        an array of results, one for each registered resource in the same order as listed by the caller
        Throws:
        java.lang.NullPointerException - if the list is null
        InvalidFileFormatException - if any resource is not a supported font file format or the font is corrupt
        java.io.FileNotFoundException - if any resource file does not exist
        java.io.IOException - if an I/O error occurs while creating a font
        See Also:
        registerFont(java.lang.String)
      • isFamilyRegistered

        public static boolean isFamilyRegistered​(java.lang.String familyName)
        Returns true if one or more fonts with the specified family name have been registered through registerFont(java.lang.String).
        Parameters:
        familyName - the family name of the font to check
        Returns:
        true if at least one font with that family name has been registered successfully
        Throws:
        java.lang.NullPointerException - if the family name is null
      • enableKerningAndLigatures

        public static java.awt.Font enableKerningAndLigatures​(java.awt.Font font)
        Returns a font instance that is equivalent to font but which will default to using kerning and ligatures (if available for the font and if supported by the particular rendering method). Note that this method is not needed for markup text drawn on components, as the markup system already provides its own support for kerning and ligatures, and it looks up fonts by family name rather than Font instance.
        Parameters:
        font - the font to modify
        Returns:
        a font instance that is equivalent to font but will use kerning and ligatures when possible
        Throws:
        java.lang.NullPointerException - if the font is null
      • registerCacheMetrics

        public static void registerCacheMetrics​(CacheMetrics cm)
        Registers a cache's metrics instance to make it available for lookup.
        Parameters:
        cm - the metrics instance to register
        Throws:
        java.lang.NullPointerException - if the metrics instance is null
      • unregisterCacheMetrics

        public static void unregisterCacheMetrics​(CacheMetrics cm)
        Unregisters a cache's metrics instance. Most caches exist for the lifetime of the application and are never unregistered.
        Parameters:
        cm - the metrics instance to unregister
      • getRegisteredCacheMetrics

        public static CacheMetrics[] getRegisteredCacheMetrics()
        Returns an array of the currently registered cache metrics instances, sorted by name (that is, their toString() value).
        Returns:
        an array of registered cache metrics instances
      • missingKeyError

        public static void missingKeyError​(java.lang.String key)
      • initializeFileDialogs

        public static void initializeFileDialogs()
        This method is called during startup to allow the resource kit to set up its shared file dialogs. This method is public only to cross a package boundary. There is no need for user code to call this method.
      • showOpenDialog

        public static java.io.File showOpenDialog​(java.awt.Component parent)
        Displays a file dialog for opening a single game component.
        Parameters:
        parent - a parent component for the dialog; may be null in which case the main application window is used
        Returns:
        the selected file, or null if no file was selected
      • showMultiOpenDialog

        public static java.io.File[] showMultiOpenDialog​(java.awt.Component parent)
        Displays a file dialog for opening multiple game components.
        Parameters:
        parent - a parent component for the dialog; may be null in which case the main application window is used
        Returns:
        the selected files (empty if no file was selected)
      • showSaveDialog

        public static java.io.File showSaveDialog​(java.awt.Component parent,
                                                  java.lang.String baseName)
        Displays a file dialog for saving a single game component. If the selected file exists, the user must confirm whether they wish to replace the existing file.
        Parameters:
        parent - a parent component for the dialog; may be null in which case the main application window is used
        baseName - an optional suggested file name
        Returns:
        the selected file, or null if no file was selected
      • showImageFileDialog

        public static java.io.File showImageFileDialog​(java.awt.Component parent)
        Displays a file dialog for opening a single image file.
        Parameters:
        parent - a parent component for the dialog; may be null in which case the main application window is used
        Returns:
        the selected file, or null if no file was selected
        Since:
        1.5
      • showBitmapImageFileDialog

        public static java.io.File showBitmapImageFileDialog​(java.awt.Component parent)
        Displays a file dialog for opening a single image file that will accept only bitmap image formats (such as JPEG) and not vector image formats (such as SVG).
        Parameters:
        parent - a parent component for the dialog; may be null in which case the main application window is used
        Returns:
        the selected file, or null if no file was selected
        Since:
        3.0
      • showZipFileDialog

        public static java.io.File showZipFileDialog​(java.awt.Component parent,
                                                     java.lang.String baseName)
        Displays a file dialog for exporting content to a ZIP archive. If the selected file exists, the user must confirm whether they wish to replace the existing file.
        Parameters:
        parent - a parent component for the dialog; may be null in which case the main application window is used
        baseName - an optional suggested file name
        Returns:
        the selected file, or null if no file was selected
      • showGenericSaveDialog

        public static java.io.File showGenericSaveDialog​(java.awt.Component parent,
                                                         java.io.File base,
                                                         java.lang.String fileTypeDescription,
                                                         java.lang.String... fileNameExtensions)
        Displays a file dialog for saving a file. If the selected file exists, the user must confirm whether they wish to replace the existing file.
        Parameters:
        parent - a parent component for the dialog; may be null in which case the main application window is used
        base - the base location or file
        fileTypeDescription - a description of the file type
        fileNameExtensions - typical file extensions for this file type
        Returns:
        the selected file, or null if no file was selected
      • showGenericOpenDialog

        public static java.io.File showGenericOpenDialog​(java.awt.Component parent,
                                                         java.io.File base,
                                                         java.lang.String fileType,
                                                         java.lang.String... fileExtensions)
        Displays a file dialog for opening a file.
        Parameters:
        parent - a parent component for the dialog; may be null in which case the main application window is used
        base - the base location or file
        fileType - a description of the file type
        fileExtensions - typical file extensions for this file type
        Returns:
        the selected file, or null if no file was selected
      • showGenericExportFileDialog

        public static java.io.File showGenericExportFileDialog​(java.awt.Component parent,
                                                               java.lang.String basename,
                                                               java.lang.String fileType,
                                                               java.lang.String fileExtension)
        Displays a file dialog for exporting a file. If the selected file exists, the user must confirm whether they wish to replace the existing file.
        Parameters:
        parent - a parent component for the dialog; may be null in which case the main application window is used
        basename - the base location or file
        fileType - a description of the file type
        fileExtension - typical file extension for this file type
        Returns:
        the selected file, or null if no file was selected
      • showScriptFileDialog

        public static java.io.File showScriptFileDialog​(java.awt.Component parent)
        Displays a file dialog for opening a script file.
        Parameters:
        parent - a parent component for the dialog; may be null in which case the main application window is used
        Returns:
        the selected file, or null if no file was selected
      • showPluginFileDialog

        public static java.io.File showPluginFileDialog​(java.awt.Component parent)
        Displays a file dialog for opening a plug-in bundle file.
        Parameters:
        parent - a parent component for the dialog; may be null in which case the main application window is used
        Returns:
        the selected file, or null if no file was selected
      • showProjectFolderDialog

        public static java.io.File showProjectFolderDialog​(java.awt.Component parent)
        Displays a file dialog for opening a project folder.
        Parameters:
        parent - a parent component for the dialog; may be null in which case the main application window is used
        Returns:
        the selected file, or null if no file was selected
      • showFolderDialog

        public static java.io.File showFolderDialog​(java.awt.Component parent,
                                                    java.lang.String title,
                                                    java.lang.String okText)
      • showPrintDialog

        public static boolean showPrintDialog​(java.awt.print.PrinterJob job)
        Shows a print dialog for a print job. This method may display either the native dialog (that allows selection from native print services) or a custom dialog (that allows selection from non-native print services) depending on application preference settings.
        Parameters:
        job - the printer job to be used for printing
        Returns:
        true if the user confirms that printing should proceed
      • createPrintRequestAttributeSet

        public static javax.print.attribute.PrintRequestAttributeSet createPrintRequestAttributeSet​(java.awt.print.PrinterJob job)
        Creates a new, mutable print request attribute set based on the application preference settings.
        Parameters:
        job - the printer job to create an attribute set for; may be null
        Returns:
        a print attribute set that reflects user preferences
        Since:
        3.0
      • makeStringFileSafe

        public static java.lang.String makeStringFileSafe​(java.lang.String string)
        Strips illegal characters out of a potential file name. If no characters are stripped, name is returned unchanged.
        Parameters:
        string - the potential file name
        Returns:
        a copy of name with any illegal characters stripped out
      • makeStringHTMLSafe

        public static java.lang.String makeStringHTMLSafe​(java.lang.String string)
        Makes a string safe for inclusion as literal HTML by escaping ampersands, less than symbols, and greater than symbols with their HTML entity expressions. If the string contains none of these characters, the original string is returned (including if it is null).
        Parameters:
        string - the string to make safe for HTML display (may be null)
        Returns:
        an HTML-safe version with escaped characters where needed, or the original string
      • findAvailableFontFamily

        public static java.lang.String findAvailableFontFamily​(java.lang.String familyList,
                                                               java.lang.String defaultFamily)
        Returns the first font family that is installed from a comma-separated list of font families.
        Parameters:
        familyList - a comma-separated list of family names
        defaultFamily - the value to return if none of the listed families is available
        Returns:
        the first available font family, or defaultFamily
      • normalizeFontFamilyName

        public static java.lang.String normalizeFontFamilyName​(java.lang.String family)
        Normalizes a font family name provided by a user. This removes any leading or trailing whitespace from the family name. If the family name starts with the prefix "cloud:", then the remainder of the name is treated as a cloud font family name. The requested cloud font family is downloaded and registered, if required, and its family name is returned without the prefix, ready to use as a text attribute value.
        Parameters:
        family - the family name to normalize
        Returns:
        the normalized name; returns an empty string on failure or if null is passed as the family name
        Since:
        3.4
      • getGameComponentFromFile

        public static GameComponent getGameComponentFromFile​(java.io.File file)
        Reads a GameComponent from a file. If an error occurs while reading or creating the component, an error message will be displayed to the user as if the component was opened using the File|Open command, and null will be returned.
        Parameters:
        file - the file to load the component from
        Returns:
        the game component stored in the file, or null
        See Also:
        getGameComponentFromFile(java.io.File, boolean)
      • getGameComponentFromFile

        public static GameComponent getGameComponentFromFile​(java.io.File file,
                                                             boolean reportError)
        Reads a GameComponent from a file. If an error occurs while reading or creating the component, and reportError is true, then an error message will be displayed to the user as if the component was opened using the File|Open command. In any case, if the component cannot be created then null will be returned.
        Parameters:
        file - the file to load the component from
        reportError - if false, errors will be logged but not displayed
        Returns:
        the game component stored in the file, or null
        See Also:
        getGameComponentFromFile(java.io.File, boolean)
      • getGameComponentFromStream

        public static GameComponent getGameComponentFromStream​(java.io.InputStream in,
                                                               java.lang.String sourceDescription,
                                                               boolean reportError)
        Reads a GameComponent from an input stream. If an error occurs while reading or creating the component, and reportError is true, then an error message will be displayed to the user as if the component was opened using the File|Open command. In any case, if the component cannot be created then null will be returned.
        Parameters:
        in - the input stream to read from
        sourceDescription - a description of the source of the input stream (such as a file or URL); this is displayed as part of an error message, if any
        reportError - if true, any errors will be reported to the user with suitable error messages; otherwise, errors will simply be logged
        Returns:
        a game component deserialized from the input stream, or null
        See Also:
        SEObjectInputStream
      • writeGameComponentToFile

        public static void writeGameComponentToFile​(java.io.File f,
                                                    GameComponent gc)
                                             throws java.io.IOException
        Writes a GameComponent to a file.
        Parameters:
        f - the file to write to
        gc - the game component to serialize to the file
        Throws:
        java.io.IOException - if an I/O error occurs while writing the file
        See Also:
        getGameComponentFromFile(java.io.File)
      • createCustomCursor

        public static java.awt.Cursor createCustomCursor​(java.lang.String resourceName)
        Creates a custom cursor from a base resource name. If the resource does not include a slash, then the path icons/cursors/ will be used. The suffix .png will be appended to locate a set of multiresolution images, and the suffix .cursor will be appended to locate a simple UTF-8 text file containing the following metadata, one item per line: the accessible cursor name; the constant name of one a built-in cursor to use as a fallback; the x; and the y coordinates of the hotspot in the base cursor image. If the accessible cursor name starts with @, then the remainder of the line is treated as an interface string key. If the cursor cannot be created, and the specified fallback cannot be decoded, the default cursor is returned.
        Parameters:
        resourceName - the base name of a collection of files that together define the cursor
        Returns:
        the custom cursor, or a fallback
        Since:
        3.4
      • createCustomCursor

        public static java.awt.Cursor createCustomCursor​(java.lang.String cursorImage,
                                                         java.awt.Point hotspot,
                                                         java.lang.String cursorName,
                                                         java.awt.Cursor fallback)
        Creates a custom cursor using an image resource, which may be a multiresolution image resource.
        Parameters:
        cursorImage - the base image resource to use for the cursor
        hotspot - the location of the hotspot on the base image
        cursorName - the cursor name, for accessibility
        fallback - the cursor to return if your cursor cannot be supported
        Returns:
        the custom cursor, or the fallback
      • createBleedBanner

        @Deprecated
        public static java.awt.image.BufferedImage createBleedBanner​(java.awt.Image source)
        Deprecated.
      • createBleedBanner

        public static ThemedIcon createBleedBanner​(java.lang.String resource)
        Returns a bleed banner icon. This is an icon based on a variation of a standard image, icons/banner/banner.jpg, with a specific alpha gradient effect applied to the bottom edge. (An example use is the new game component dialog.)
        Parameters:
        source - the source banner image; if does not specify a directory, the default is icons/banner.
        Returns:
        an image with a transparent lower edge
        Throws:
        java.lang.NullPointerException - if the source image is null
      • createWaitIcon

        public static AnimatedIcon createWaitIcon​(javax.swing.JComponent comp)
        Creates a new wait icon (an animated icon that indicates a lengthy delay). These icons are tied to a specific component, so a new one must be created whenever one is required.
        Parameters:
        comp - the component that the icon will be set on
        Returns:
        an animated wait icon for the component