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

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.
protected  EngineFactory m_currentEngineFactory
          The current engine factory or null if not searched.
protected  java.util.Vector m_engineFactories
          Vector of the engine factories that are found.
protected  boolean m_fGameFrameMainDirectorySearched
          Flag that indicates if the path to the GameFrame classes has been searched at least once.
protected  GameFrameSettings m_settings
          The settings that are used to find the engine factory.
protected  java.lang.String m_strGameFrameMainDirectory
          The main directory of GameFrame library.
static int MAJOR_VERSION
          The major version number of this library.
static int MINOR_VERSION
          The minor version number of this library.
protected static GraphicsEngine mStatic_graphicsEngine
          The recommended graphics engine.
protected static InputEngine mStatic_inputEngine
          The recommended input engine.
protected static GameFrame mStatic_singletonInstance
          The singleton instance of GameFrame class.
protected static SoundEngine mStatic_soundEngine
          The recommended sound engine.
 
Constructor Summary
  GameFrame()
          Constructs the GameFrame using default settings.
protected GameFrame(boolean fDoNotInitialize)
          For use by subclasses that don't want to initialize the GameFrame in this classes constructors, but want to call the initFromSettings() by themselves when they are ready.
  GameFrame(GameFrameSettings settings)
          Constructs the GameFrame using the given settings.
 
Method Summary
protected  void addEngineFactoryClasses(java.util.Vector engineFactoryClasses)
          Tries to instantiate the given EngineFactory classes by invoking their static "getInstance(GameFrameSettings)" methods.
protected  void addFactory(EngineFactory factory)
          Adds the given factory instance to the list of factories if the given factory is runnable on this platform.
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.
protected  java.util.Vector findClassesInSubdirectoriesThatImplementInterface(java.lang.String strParentDirectoryName, java.util.Vector subDirectories, java.lang.Class targetInterface)
          Finds the classes that implement the given interface and that reside in one of the subdirectories in the given list of directories.
protected  java.util.Vector findSubdirectories(java.lang.String strDirectory)
          Finds the subdirectories under the given directory name.
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.
protected  EngineFactory getRecommendedEngineFactory()
          Upon invocation decides which of the engine factory implementations meets the set requirements and suits the current platform the best and returns it.
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.
protected  void initEngines()
          Initializes the recommended engines for the current platform, so that when any of the static getXXXXEngine() methods are called no exceptions are thrown.
protected  void initFromSettings(GameFrameSettings settings)
          Initializes the library instance from the given settings object.
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.
protected  void searchEngineFactories()
          Does the core job of adding all engine factories to the list of runnable factories (engine factories that can run on the current platform).
 
Methods inherited from class java.lang.Object
, clone, equals, getClass, hashCode, notify, notifyAll, registerNatives, 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.

mStatic_singletonInstance

protected static GameFrame mStatic_singletonInstance
The singleton instance of GameFrame class.
Since:
GameFrame for Java 0.9.1

m_strGameFrameMainDirectory

protected java.lang.String m_strGameFrameMainDirectory
The main directory of GameFrame library. Defaults to null, initialized upon first invocation of method getGameFramePath().
Since:
GameFrame for Java 0.9

m_fGameFrameMainDirectorySearched

protected boolean m_fGameFrameMainDirectorySearched
Flag that indicates if the path to the GameFrame classes has been searched at least once. Defaults to false (classes not searched).
Since:
GameFrame for Java 0.9

m_settings

protected GameFrameSettings m_settings
The settings that are used to find the engine factory.
Since:
GameFrame for Java 0.9

m_currentEngineFactory

protected EngineFactory m_currentEngineFactory
The current engine factory or null if not searched.
Since:
GameFrame for Java 0.9.1

m_engineFactories

protected java.util.Vector m_engineFactories
Vector of the engine factories that are found. Sorted so that the best implementation is found at the index 0.
Since:
GameFrame for Java 0.9

mStatic_graphicsEngine

protected static GraphicsEngine mStatic_graphicsEngine
The recommended graphics engine.

mStatic_soundEngine

protected static SoundEngine mStatic_soundEngine
The recommended sound engine.

mStatic_inputEngine

protected static InputEngine mStatic_inputEngine
The recommended input engine.
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

GameFrame

protected GameFrame(boolean fDoNotInitialize)
For use by subclasses that don't want to initialize the GameFrame in this classes constructors, but want to call the initFromSettings() by themselves when they are ready.
Parameters:
fDoNotInitialize - Ignored...
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

initFromSettings

protected void initFromSettings(GameFrameSettings settings)
                         throws SettingsException,
                                GameFrameException
Initializes the library instance from the given settings object.
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.4
See Also:
GameFrameSettings

initEngines

protected void initEngines()
                    throws GameFrameException
Initializes the recommended engines for the current platform, so that when any of the static getXXXXEngine() methods are called no exceptions are thrown.
Throws:
GameFrameException - Thrown if some engine fails to initialize.
Since:
GameFrame for Java 0.9.2
See Also:
GameFrameSettings

getRecommendedEngineFactory

protected EngineFactory getRecommendedEngineFactory()
Upon invocation decides which of the engine factory implementations meets the set requirements and suits the current platform the best and returns it. Also registers the found engine factory and returns that engine factory upon every later invocation.
Returns:
The best engine factory for this platform.
Since:
GameFrame for Java 0.9

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.

searchEngineFactories

protected void searchEngineFactories()

Does the core job of adding all engine factories to the list of runnable factories (engine factories that can run on the current platform). Later added engine factories that have the same suitability value will override engine factories that were added earlier.

Note to engine implementors: Engine implementors that add new engines must add their engine factories in this method. Also this is the method to override if you want to make your own custom GameFrame subclass.

Since:
GameFrame for Java 0.9

findSubdirectories

protected java.util.Vector findSubdirectories(java.lang.String strDirectory)
Finds the subdirectories under the given directory name.
Parameters:
The - directory whose subdirectories are searched.
Returns:
The subdirectories (as java.io.File) of the given directory.
Since:
GameFrame for Java 0.9.1

findClassesInSubdirectoriesThatImplementInterface

protected java.util.Vector findClassesInSubdirectoriesThatImplementInterface(java.lang.String strParentDirectoryName,
                                                                             java.util.Vector subDirectories,
                                                                             java.lang.Class targetInterface)
Finds the classes that implement the given interface and that reside in one of the subdirectories in the given list of directories.
Parameters:
strParentDirectoryName - The name of the parent directory (used as the main package name).
subDirectories - The subdirectories that are searched through.
targetInterface - The interface whose implementors are to be searched.
Returns:
Class objects that meet the aforementioned criteria.
Since:
GameFrame for Java 0.9.1

addEngineFactoryClasses

protected void addEngineFactoryClasses(java.util.Vector engineFactoryClasses)
Tries to instantiate the given EngineFactory classes by invoking their static "getInstance(GameFrameSettings)" methods. After successfull instantiation the EngineFactory class is added to the sorted list of engine factories.
Parameters:
engineFactoryClasses - The EngineFactory classes to be instantiated and added.
Since:
GameFrame for Java 0.9.1

addFactory

protected void addFactory(EngineFactory factory)
Adds the given factory instance to the list of factories if the given factory is runnable on this platform.
Parameters:
factory - The engine factory to be added to list of factories.
Since:
GameFrame for Java 0.9

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.
Overrides:
finalize in class java.lang.Object
Since:
GameFrame for Java 0.9

GF4J 0.9.4 Beta