Package resources

Class ResourceKit

java.lang.Object

resources.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

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	ResourceKit.FontRegistrationResult	Returned by registerFont(java.lang.String) to describe the result of registration.

Method Summary

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 <family> 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