enginemidlet.java

j2me编写的游戏基础引擎,作为学习很不错.

package engine.kernel;

import javax.microedition.midlet.*;
import javax.microedition.lcdui.*;
import java.util.*;

/**
*	引擎入口基类(抽象类)<br>
*	所有的一本引擎为基础开发的程序的MIDlet类，都必须继承这个类。因为这里是整个引擎的入口。
*	@see javax.microedition.midlet.MIDlet
*	@author 贾永明
*	@version 2.8.0
*	@since HuoHouStudioEngine1.0
*/
public abstract class EngineMIDlet extends MIDlet{
	/**
	*	MIDlet constructor。<br>获取MIDlet实例，获取按键布局和创建按键的存储空间，产生{@link engine.kernel.EngineThread EngineThread}实例，并且启动，同时会依据硬件和开发者意愿创建绘制缓冲背屏，以及其他的一些数据创建，创建旧屏幕保留的空间，进入入口屏幕，创建旧屏幕的保留的空间，设置持续按键的时延。
	*	@param <b>continueAfterException</b> 发生严重异常的情况下的处理方式，true：发生严重异常之后仍然继续运行，false：发生严重异常之后关闭应用程序。
	*	@param <b>scrWidthAdjust</b> 屏幕宽度调整，本引擎所获取的屏幕的宽度是通过Canvas自带的getWidth()方法获取的，但是，出于某些不可预料的原因，本引擎所获取的屏幕的宽度不能够准确的表现屏幕的真实的宽度的时候或者不是程序员希望的数据，需要程序员在这里给出宽度的修正数据。
	*	@param <b>scrHeightAdjust</b> 屏幕高度调整，本引擎所获取的屏幕的宽度是通过Canvas自带的getWidth()方法获取的，但是，出于某些不可预料的原因，本引擎所获取的屏幕的高度不能够准确的表现屏幕的真实的高度的时候或者不是程序员希望的数据，需要程序员在这里给出高度的修正数据。
	*	@param <b>isDoubleBuffered</b> 是否启用双缓冲绘制，true：启用，false：不启用。
	*	@param <b>fps</b> 引擎的刷新频率，应该是正数，如果是负数或者0，会被认为是最低刷新率，即不刷新。
	*	@param <b>reservedScreenNormalCapacity</b> 保留屏幕的空间容量，非负数。
	*	@param <b>backgroundCapacity</b> 后台运行的屏幕的空间容量，非负数。
	*	@param <b>keyMapURL</b> 按键布局的路径，当按键布局的路径为不合法的时候，就会抛出异常<br>Error: the file of "<EM>keyMapURL</EM>" is invalid<br>keyMapUrl是按键布局的路径具体信息。
	*	@param <b>maxCombineKey</b> 组合按键的最大按键数量，多个按键先后按下的组合情况下，可能出现的最大的按键数。
	*	@param <b>tbkh</b> 按键保持状态的时间基数，time base key hold 的缩写，用于控制按键处于持续状态的时间的具体数值，该时间等于该参数与每帧刷新时间的乘积，这里需要注意的是如果tbkh传入的是非正数不会有任何异常出现，但是，在实际应用当中没有任何意义，因为这种情况下，任何按键操作都会被当成是保持状态，都是超时。
	*	@param <b>appendCommandSoftX</b> 是否需要添加高级命令按钮作为左右软键，true：需要添加，false：不需要添加，由于有些硬件的左右软键在Canvas里面捕捉不到，这里需要用高级命令按钮Command代替。
	*	@throws Exception 一切可能产生的异常。
	*/
	protected EngineMIDlet(boolean continueAfterException, int scrWidthAdjust, int scrHeightAdjust, boolean isDoubleBuffered, int fps, int reservedScreenNormalCapacity, int backgroundCapacity, String keyMapURL, int maxCombineKey, int tbkh, boolean appendCommandSoftX) throws Exception{
		//获取MIDlet实例
		EngineManager.engineMidlet = this;
		if(!EngineManager.hasStarted){
			//获取按键布局
			EngineKey.keyMap = EngineManager.getByteArrayFromFile(keyMapURL);
			if(EngineKey.keyMap == null){
				throw new Error("the file of \"" + keyMapURL + "\" is invalid");
			}
			//创建按键的存储空间
			EngineKey.pressState = new StringBuffer(2);
			EngineKey.holdState = new StringBuffer(EngineKey.keyMap.length);
			EngineKey.combineState = new StringBuffer((maxCombineKey << 2));
			//创建旧屏幕保留的空间
			EngineManager.scrList = new Vector(reservedScreenNormalCapacity);
			//创建后台运行的屏幕的ID的存储空间，以char为原型，最大容量backgroundCapacity
			EngineManager.backgroundID = new StringBuffer(backgroundCapacity);
			//产生EngineThread实例，并且启动
			new Thread(EngineManager.engineThread = new EngineThread(scrWidthAdjust, scrHeightAdjust, continueAfterException, isDoubleBuffered, appendCommandSoftX)).start();
			//进入入口屏幕
			EngineManager.switchScreen(this.entrance(EngineManager.engineThread.scrWidth, EngineManager.engineThread.scrHeight), EngineManager.NONE_OPERATE, fps);
			//设置持续按键的时延
			EngineKey.setHoldKeyTimeout(tbkh);
		}
	}
	/**
	*	MIDlet类的接口。<br>在把MIDlet标志为Active状态的时候被调用。
	*/
	protected final void startApp(){
		if(EngineManager.hasStarted && EngineManager.isPause){
			EngineManager.engineMidlet.load(EngineManager.STARTAPP_CALLER);
			EngineManager.isPause = false;
		}
	}
	/**
	*	MIDlet类的接口。<br>在把MIDlet标志为Paused状态的时候被调用。
	*/
	protected final void pauseApp(){
		if(EngineManager.hasStarted && !EngineManager.isPause){
			EngineManager.engineMidlet.save(EngineManager.PAUSEAPP_CALLER);
			EngineManager.isPause = true;
		}
	}
	/**
	*	MIDlet类的接口。<br>用于告知应用程序管理器MIDlet打算转入Destroyed状态。
	*	@param <b>unconditional</b> 通知应用程序管理是否可以强行中止当前应用程序，true 代表可以强行中止当前应用程序，false 代表不可以强行中止当前应用程序。
	*/
	protected final void destroyApp(boolean unconditional){
		if(EngineManager.hasStarted){
			EngineManager.hasStarted = false;
			 if(!EngineManager.isPause){
			 	EngineManager.engineMidlet.save(EngineManager.DESTROYAPP_CALLER);
			}
		}
		EngineManager.scrListener = null;
		if(EngineManager.scrList != null){
			EngineManager.scrList.removeAllElements();
			EngineManager.scrList = null;
		}
		EngineKey.keyMap = null;
		EngineKey.clrAllKeyState();
		EngineKey.pressState = EngineKey.holdState = null;
		EngineKey.combineState = null;
		if(EngineManager.engineThread != null){
			EngineManager.engineThread.keyInfo = null;
			EngineManager.engineThread.bufferedGraphics = null;
			EngineManager.engineThread.bufferedImage = null;
			EngineManager.engineThread = null;
		}
	}
	/**
	*	保存程序数据的方法。<br>抽象的方法，由继承的子类具体实现。当程序被暂停的时候该方法会被调用，比如按到了挂机键，或者是外部事件等等。
	*	@param <b>caller</b> 该方法的调用者。<br><br>
	*	如下数值被引擎本身使用：<br>
	*	<TABLE BORDER="1" WIDTH="80%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
	*	<TR BGCOLOR="#9988cc">
	*	<TD WIDTH="8%"><FONT SIZE="+1"><B>数值</B></FONT></TD>
	*	<TD WIDTH="40%"><FONT SIZE="+1"><B>说明</B></FONT></TD>
	*	<TR BGCOLOR="#CCCCFF">
	*	<TD WIDTH="8%">0</TD><TD WIDTH="40%">{@link engine.kernel.EngineMIDlet#startApp startApp()}调用。</TD>
	*	</TR>
	*	<TR BGCOLOR="#CCCCFF">
	*	<TD WIDTH="8%">1</TD><TD WIDTH="40%">{@link engine.kernel.EngineMIDlet#pauseApp pauseApp()}调用。</TD>
	*	</TR>
	*	<TR BGCOLOR="#CCCCFF">
	*	<TD WIDTH="8%">2</TD><TD WIDTH="40%">{@link engine.kernel.EngineMIDlet#destroyApp(boolean) destroyApp(boolean unconditional)}调用。</TD>
	*	</TR>
	*	<TR BGCOLOR="#CCCCFF">
	*	<TD WIDTH="8%">3</TD><TD WIDTH="40%">{@link engine.kernel.EngineThread#hideNotify hideNotify()}调用。</TD>
	*	</TR>
	*	<TR BGCOLOR="#CCCCFF">
	*	<TD WIDTH="8%">4</TD><TD WIDTH="40%">{@link engine.kernel.EngineThread#showNotify showNotify()}调用。</TD>
	*	</TR>
	*	<TR BGCOLOR="#FFFF00">
	*	<TD COLSPAN=2 WIDTH="8%"><FONT SIZE="-1"><B>以上数据建议使用本引擎的开发人员不要使用，以免发生混乱。</B></FONT></TD>
	*	</TR>
	*	</TABLE>
	*/
	protected abstract void save(int caller);
	/**
	*	读取程序数据的方法。<br>抽象的方法，由继承的子类具体实现。当程序被重新激活，即由暂停状态进入到了活动状态的时候该方法会被调用，比如外部事件结束之后返回程序等等。
	*	@param <b>caller</b> 该方法的调用者。<br><br>
	*	如下数值被引擎本身使用：<br>
	*	<TABLE BORDER="1" WIDTH="80%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
	*	<TR BGCOLOR="#9988cc">
	*	<TD WIDTH="8%"><FONT SIZE="+1"><B>数值</B></FONT></TD>
	*	<TD WIDTH="40%"><FONT SIZE="+1"><B>说明</B></FONT></TD>
	*	<TR BGCOLOR="#CCCCFF">
	*	<TD WIDTH="8%">0</TD><TD WIDTH="40%">{@link engine.kernel.EngineMIDlet#startApp startApp()}调用。</TD>
	*	</TR>
	*	<TR BGCOLOR="#CCCCFF">
	*	<TD WIDTH="8%">1</TD><TD WIDTH="40%">{@link engine.kernel.EngineMIDlet#pauseApp pauseApp()}调用。</TD>
	*	</TR>
	*	<TR BGCOLOR="#CCCCFF">
	*	<TD WIDTH="8%">2</TD><TD WIDTH="40%">{@link engine.kernel.EngineMIDlet#destroyApp(boolean) destroyApp(boolean unconditional)}调用。</TD>
	*	</TR>
	*	<TR BGCOLOR="#CCCCFF">
	*	<TD WIDTH="8%">3</TD><TD WIDTH="40%">{@link engine.kernel.EngineThread#hideNotify hideNotify()}调用。</TD>
	*	</TR>
	*	<TR BGCOLOR="#CCCCFF">
	*	<TD WIDTH="8%">4</TD><TD WIDTH="40%">{@link engine.kernel.EngineThread#showNotify showNotify()}调用。</TD>
	*	</TR>
	*	<TR BGCOLOR="#FFFF00">
	*	<TD COLSPAN=2 WIDTH="8%"><FONT SIZE="-1"><B>以上数据建议使用本引擎的开发人员不要使用，以免发生混乱。</B></FONT></TD>
	*	</TR>
	*	</TABLE>
	*/
	protected abstract void load(int caller);
	/**
	*	获取引擎的入口屏幕。
	*	@param <b>scrWidth</b> 屏幕的宽度，由引擎的主线程传给应用程序。
	*	@param <b>scrHeight</b> 屏幕的高度，由引擎的主线程传给应用程序。
	*	@return 入口屏幕，必须是Screen或者{@link engine.kernel.EventListener EventListener}、{@link engine.kernel.DrawListener DrawListener}的实例，否则，屏幕将得不到任何响应，程序处于假死状态。
	*	@throws Exception 一切可能产生的异常。
	*/
	protected abstract Object entrance(int scrWidth, int scrHeight) throws Exception;
}