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
- 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 theresources
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.) - The second part consists of zero or more folder names separated by slashes.
- 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.
composeResourceURL(java.lang.String)
with the identifier. This will return a URL that can be used to access the resource, ornull
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, whilecomposeResourceURL
returns a URL for the actual location of the file. In fact, when you try to access ares:
URL's data using a method likeopenStream
, the protocol handler will itself callcomposeResourceURL
to find the file in question.- Since:
- 1.0
- Author:
- Chris Jennings
- The first part is the least used and most technical:
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
ResourceKit.FontRegistrationResult
Returned byregisterFont(java.lang.String)
to describe the result of registration.
-
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 tofont
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 aFont
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 aGameComponent
from a file.static GameComponent
getGameComponentFromFile(java.io.File file, boolean reportError)
Reads aGameComponent
from a file.static GameComponent
getGameComponentFromStream(java.io.InputStream in, java.lang.String sourceDescription, boolean reportError)
Reads aGameComponent
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 bygetImage(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, theirtoString()
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)
Returnstrue
if one or more fonts with the specified family name have been registered throughregisterFont(java.lang.String)
.static boolean
isResourceStatic(java.net.URL composedResourceURL)
Returnstrue
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 aGameComponent
to a file.
-
-
-
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, callStrangeEons.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):
- 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 theres://
prefix was not present. Absolute URLs are indicated by the presence of a colon (:) in the identifier. - The contents of the user resource folder, if any.
- The
resources
folders of the main application and all installed plug-in bundles, in the order of installation. - 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
- 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
-
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 bycomposeResourceURL(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 torelativePathToResource
- 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. BecausecomposeResourceURL(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:
- If the identifier is
null
, it will be returned unchanged. - 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.
- If the identifier is an absolute URL identifier, then it may be changed to a virtual resource path that points to the same file.
- 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
- If the identifier is
-
isResourceStatic
public static boolean isResourceStatic(java.net.URL composedResourceURL)
Returnstrue
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 existjava.io.IOException
- if an I/O error occurs while opening the streamjava.lang.NullPointerException
- if the specified resource isnull
-
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 installedTheme
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
- ificonResource
isnull
- 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 istrue
, 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 isnull
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 bygetImage(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 isnull
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 callinggetImageQuietly(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 loadoutputImages
- 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 isnull
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
ifimage
wasnull
-
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 returnedVectorIcon
.- Parameters:
resource
- the image resource to create an icon oficonWidth
- the initial width of the icon, in pixelsiconHeight
- 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 aFont
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 viagetBodyFamily()
rather than byFont
. 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 isnull
InvalidFileFormatException
- if the resource is not a supported font file format or the font is corruptjava.io.FileNotFoundException
- if the resource file does not existjava.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 usinggetFont(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 isnull
InvalidFileFormatException
- if the resource is not a supported font file format or the font is corruptjava.io.FileNotFoundException
- if the resource file does not existjava.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 byregisterFont(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 forTextStyle
s by callingResourceKit.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 isnull
InvalidFileFormatException
- if any resource is not a supported font file format or the font is corruptjava.io.FileNotFoundException
- if any resource file does not existjava.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)
Returnstrue
if one or more fonts with the specified family name have been registered throughregisterFont(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 isnull
-
enableKerningAndLigatures
public static java.awt.Font enableKerningAndLigatures(java.awt.Font font)
Returns a font instance that is equivalent tofont
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 thanFont
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 isnull
-
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 isnull
-
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, theirtoString()
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 benull
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 benull
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 benull
in which case the main application window is usedbaseName
- 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 benull
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 benull
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 benull
in which case the main application window is usedbaseName
- 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 benull
in which case the main application window is usedbase
- the base location or filefileTypeDescription
- a description of the file typefileNameExtensions
- 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 benull
in which case the main application window is usedbase
- the base location or filefileType
- a description of the file typefileExtensions
- 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 benull
in which case the main application window is usedbasename
- the base location or filefileType
- a description of the file typefileExtension
- 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 benull
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 benull
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 benull
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 benull
- 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 isnull
).- Parameters:
string
- the string to make safe for HTML display (may benull
)- 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 namesdefaultFamily
- 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 aGameComponent
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, andnull
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 aGameComponent
from a file. If an error occurs while reading or creating the component, andreportError
istrue
, 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 thennull
will be returned.- Parameters:
file
- the file to load the component fromreportError
- iffalse
, 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 aGameComponent
from an input stream. If an error occurs while reading or creating the component, andreportError
istrue
, 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 thennull
will be returned.- Parameters:
in
- the input stream to read fromsourceDescription
- 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 anyreportError
- iftrue
, 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 aGameComponent
to a file.- Parameters:
f
- the file to write togc
- 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 pathicons/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 cursorhotspot
- the location of the hotspot on the base imagecursorName
- the cursor name, for accessibilityfallback
- 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 isicons/banner
.- Returns:
- an image with a transparent lower edge
- Throws:
java.lang.NullPointerException
- if the source image isnull
-
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
-
-