GF4J 0.9.4 Beta

gameframe
Class GameFrame

java.lang.Object
  |
  +--gameframe.GameFrame
Direct Known Subclasses:
AppletGameFrame

public class GameFrame
extends java.lang.Object

The GameFrame librarys main entry point class. The methods in this class are mainly used when the game is starting, after that this class is normally not used at all. For this reason many of the methods in this class aren't optimized for speed, but for lesser memory usage. Only exception is the getGameFramePath() method that might be used by implementations to find out e.g. the location of the default font bitmap. This one method is made to be as fast as possible.

Since:
GameFrame for Java 0.9
Version:
GameFrame for Java 0.9.4
Author:
Pasi Keränen 16. May 1999

Field Summary
static int BUILD_NUMBER
          The build number of this library.
static java.lang.Class ENGINE_FACTORY_CLASS
          The engine factory class (used when finding engine factories).
static java.lang.String ENGINE_FACTORY_GET_INSTANCE_METHOD_NAME
          The engine factory's get instance method name.
static java.lang.Class[] ENGINE_FACTORY_GET_INSTANCE_METHOD_PARAM_CLASSES
          The engine factory's get instance methods parameter classes.
static java.lang.String ENGINE_FACTORY_IS_RUNNABLE_METHOD_NAME
          The engine factory's is runnable on current platform method name.
static java.lang.String ENGINE_MAIN_PACKAGE_NAME
          The package name of the main package for engines.
static java.lang.String ENGINE_SUBDIR_NAME
          The subdirectory name of the directory for engines.
static java.lang.String GAME_FRAME_PACKAGE_NAME
          The package name of the main package for engines.
static boolean IS_STABLE_RELEASE
          Is this release a stable release.
static int MAJOR_VERSION
          The major version number of this library.
static int MINOR_VERSION
          The minor version number of this library.
 
Constructor Summary
GameFrame()
          Constructs the GameFrame using default settings.
GameFrame(GameFrameSettings settings)
          Constructs the GameFrame using the given settings.
 
Method Summary
static Timer createTimer()
          Returns a new timer instance.
static void exit(int iValue)
          Exits cleanly from application that has used GameFrame by first finalizing the whole library (that ensures all native resources are freed) and then calling carbage collector and waiting for a while and THEN exiting the application just like System.exit() method.
 void finalize()
          Finalizes this GameFrame instance and finalizes the whole GameFrame library.
static int getBuild()
          Returns the build number of the GameFrame library.
 java.lang.String getDefaultFontBitmapFilename()
          Filename that can be used to load the default font bitmap.
 java.awt.Image getDefaultIcon()
          Returns the Image that is set as the default image icon for all graphics engine windows.
static java.lang.String getDescription()
          Returns the (possibly multiline) description of the currently used implementation.
 java.lang.String getGameFramePath()
          Returns the absolute path to the main directory of the library that contains the GameFrame public classes.
static GraphicsEngine getGraphicsEngine()
          Returns the recommended graphics engine for the current platform or null if graphics engine was for some reason not created.
static InputEngine getInputEngine()
          Returns the recommended input engine for the current platform or null if input engine was for some reason not created.
static GameFrame getInstance()
          Returns the singleton instance of the GameFrame class.
static int getMajorVersion()
          Returns the major version of the GameFrame library.
static int getMinorVersion()
          Returns the minor version of the GameFrame library.
static java.lang.String getName()
          Returns the short name (max 8 characters) of the currently used implementation e.g.
static SoundEngine getSoundEngine()
          Returns the recommended sound engine for the current platform or null if sound engine was for some reason not created.
static int getSuitabilityForPlatform()
          Returns the suitability of the currently used implementation for the current platform as one of the enumerated EngineFactory.SUITABILITY_xxx values.
static java.lang.String[] getSupportedResolutions()
          Returns all the fullscreen graphics modes supported by recommended graphics engine.
static boolean isInitialized()
          Returns whether GF4J library is initialized at the moment or not.
static boolean isStableVersion()
          Returns true if this version is a stable release (not prerelease, beta or alpha or anything like that) meant for anyones use.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

MAJOR_VERSION

public static final int MAJOR_VERSION
The major version number of this library.
Since:
GameFrame for Java 0.9

MINOR_VERSION

public static final int MINOR_VERSION
The minor version number of this library.
Since:
GameFrame for Java 0.9

BUILD_NUMBER

public static final int BUILD_NUMBER
The build number of this library.
Since:
GameFrame for Java 0.9.1

IS_STABLE_RELEASE

public static final boolean IS_STABLE_RELEASE
Is this release a stable release.
Since:
GameFrame for Java 0.9.1

GAME_FRAME_PACKAGE_NAME

public static final java.lang.String GAME_FRAME_PACKAGE_NAME
The package name of the main package for engines.

ENGINE_MAIN_PACKAGE_NAME

public static final java.lang.String ENGINE_MAIN_PACKAGE_NAME
The package name of the main package for engines.

ENGINE_SUBDIR_NAME

public static final java.lang.String ENGINE_SUBDIR_NAME
The subdirectory name of the directory for engines.

ENGINE_FACTORY_CLASS

public static final java.lang.Class ENGINE_FACTORY_CLASS
The engine factory class (used when finding engine factories).

ENGINE_FACTORY_GET_INSTANCE_METHOD_NAME

public static final java.lang.String ENGINE_FACTORY_GET_INSTANCE_METHOD_NAME
The engine factory's get instance method name.

ENGINE_FACTORY_IS_RUNNABLE_METHOD_NAME

public static final java.lang.String ENGINE_FACTORY_IS_RUNNABLE_METHOD_NAME
The engine factory's is runnable on current platform method name.

ENGINE_FACTORY_GET_INSTANCE_METHOD_PARAM_CLASSES

public static final java.lang.Class[] ENGINE_FACTORY_GET_INSTANCE_METHOD_PARAM_CLASSES
The engine factory's get instance methods parameter classes.
Constructor Detail

GameFrame

public GameFrame()
          throws SettingsException,
                 GameFrameException
Constructs the GameFrame using default settings. Also initializes the recommended engines for the current platform, so that when any of the getXXXXEngine() methods is called no exceptions are thrown.
Throws:
SettingsException - Thrown if a GameFrame instance allready exists. GameFrame instance can be destroyed by calling the finalize() method.
GameFrameException - Thrown if some engine fails to initialize.
Since:
GameFrame for Java 0.9.1
See Also:
GameFrameSettings

GameFrame

public GameFrame(GameFrameSettings settings)
          throws SettingsException,
                 GameFrameException
Constructs the GameFrame using the given settings. Also initializes the recommended engines for the current platform, so that when any of the getXXXXEngine() methods is called no exceptions are thrown.
Parameters:
settings - The settings to use inside the GameFrame library. If null is provided uses default settings.
Throws:
SettingsException - Thrown if a GameFrame instance allready exists. GameFrame instance can be destroyed by calling the finalize() method.
GameFrameException - Thrown if some engine fails to initialize.
Since:
GameFrame for Java 0.9.1
See Also:
GameFrameSettings
Method Detail

isInitialized

public static boolean isInitialized()
Returns whether GF4J library is initialized at the moment or not.
Returns:
The true if the library is initialized, false if not.
Since:
GameFrame for Java 0.9.4

getInstance

public static GameFrame getInstance()
Returns the singleton instance of the GameFrame class.
Returns:
The singleton instance of the library main class if one has been created.
Throws:
NullPointerException - Thrown if GameFrame has not been created.
Since:
GameFrame for Java 0.9.1

getGameFramePath

public java.lang.String getGameFramePath()
Returns the absolute path to the main directory of the library that contains the GameFrame public classes. Uses the singleton instance reference and internal overridable version of the method.
Returns:
The directory that is the main directory of the GameFrame library or null if not found.
Since:
GameFrame for Java 0.9

getDefaultIcon

public java.awt.Image getDefaultIcon()
Returns the Image that is set as the default image icon for all graphics engine windows.
Returns:
Default icon for engine windows.

getDefaultFontBitmapFilename

public java.lang.String getDefaultFontBitmapFilename()
Filename that can be used to load the default font bitmap.
Returns:
The default fontbitmap filename.

isStableVersion

public static boolean isStableVersion()
Returns true if this version is a stable release (not prerelease, beta or alpha or anything like that) meant for anyones use. This of course can't quarantee bugfree implementation, but it should notify that the library has been tested and found working on most platforms. This means that any needed pre-release testing has been done.
Returns:
True if this is a stable library version, false if this is a experimental library version.
Since:
GameFrame for Java 0.9.1

getMajorVersion

public static int getMajorVersion()
Returns the major version of the GameFrame library. This will be incremented by one upon each new public stable release that will change existing functions in a major way or adds major new functionality. Major versions might break downwards compatibility, but are don't allways do that. Breaking downwards compatibility must allways be done in a major version update and must be well documented. Backwards compatibility should be preserved for as long as possible.
Returns:
GameFrame library's major version.
Since:
GameFrame for Java 0.9

getMinorVersion

public static int getMinorVersion()
Returns the minor version of the GameFrame library. This will be incremented by one upon each new public release that adds (or changes in a minor way) functionality to the library's interfaces. This means versions that are bugfix versions or include new engine implementations for the existing interfaces. Upon new major version release this version number will be reset to 0. The game shouldn't need to check for minor version, as minor versions are compatible between eachother as far as the interfaces go. But if you know that you use a feature in the library that was fully functional only after a certain minor release, you can check that the library's minor version meets your requirements. The game should allways check for "at least version" as the game library should be downwards compatible inside the same major version.
Returns:
GameFrame library's minor version.
Since:
GameFrame for Java 0.9

getBuild

public static int getBuild()
Returns the build number of the GameFrame library. This is incremented by each build, one minor version can have (theoretically) up to 2147483647 builds (that is the limit of the used integer number). A build is considered being a compiling of edited source code that is given to person/persons outside the development team. This means that there is no need to count the number of compiles inside the development team.
Returns:
The build number of the library.
Since:
GameFrame for Java 0.9.1

getName

public static java.lang.String getName()
Returns the short name (max 8 characters) of the currently used implementation e.g. "Java 1.1" or "MSDX".
Returns:
The short name of the engine factory.
Since:
GameFrame for Java 0.9

getDescription

public static java.lang.String getDescription()
Returns the (possibly multiline) description of the currently used implementation.
Returns:
A description of the engine factory.
Since:
GameFrame for Java 0.9

getSuitabilityForPlatform

public static int getSuitabilityForPlatform()
Returns the suitability of the currently used implementation for the current platform as one of the enumerated EngineFactory.SUITABILITY_xxx values.
Returns:
Suitability of the implementation for this platform.
Since:
GameFrame for Java 0.9

getGraphicsEngine

public static GraphicsEngine getGraphicsEngine()
Returns the recommended graphics engine for the current platform or null if graphics engine was for some reason not created. If no exception is thrown when the GameFrame instance is created this method is quaranteed to return a non-null value.
Returns:
Recommended graphics engine for the current platform or null if not initialized.
Since:
GameFrame for Java 0.9.1

getInputEngine

public static InputEngine getInputEngine()
Returns the recommended input engine for the current platform or null if input engine was for some reason not created. If no exception is thrown when the GameFrame instance is created this method is quaranteed to return a non-null value.
Returns:
Recommended input engine for the current platform or null if not initialized.
Since:
GameFrame for Java 0.9.1

getSoundEngine

public static SoundEngine getSoundEngine()
Returns the recommended sound engine for the current platform or null if sound engine was for some reason not created. If no exception is thrown when the GameFrame instance is created this method is quaranteed to return a non-null value.
Returns:
Recommended sound engine for the current platform or null if not initialized.
Since:
GameFrame for Java 0.9.1

getSupportedResolutions

public static java.lang.String[] getSupportedResolutions()
Returns all the fullscreen graphics modes supported by recommended graphics engine. If the recommended graphics engine supports only windowed modes, this method returns null.
Returns:
Supported fullscreen modes or null.
Since:
GameFrame for Java 0.9.1

createTimer

public static Timer createTimer()
                         throws GameFrameException
Returns a new timer instance. Several timers can be created with this method. If a native timer can't be for some reason created, this method returns the basic implementation CTimer from the GameFrame.jdk11x package. If even this doesn't succeed throws GameFrameException exception.
Returns:
A new timer instance.
Throws:
GameFrameException - Thrown if timer creation fails.
Since:
GameFrame for Java 0.9

exit

public static void exit(int iValue)
Exits cleanly from application that has used GameFrame by first finalizing the whole library (that ensures all native resources are freed) and then calling carbage collector and waiting for a while and THEN exiting the application just like System.exit() method.
Parameters:
iValue - The integer value to be returned by the exit method to the native system.

finalize

public void finalize()
Finalizes this GameFrame instance and finalizes the whole GameFrame library. In short resets the GameFrame for Java library.
Since:
GameFrame for Java 0.9

GF4J 0.9.4 Beta