org.hermit.android.instruments
Class InstrumentSurface

java.lang.Object
  extended by SurfaceView
      extended by org.hermit.android.core.SurfaceRunner
          extended by org.hermit.android.instruments.InstrumentSurface

public abstract class InstrumentSurface
extends SurfaceRunner

Common base for applications which display instruments. This class is an extension of SurfaceRunner which provides additional functions to manage the instruments embedded in it.

When using this class in an app, the app context must call these methods (usually from its corresponding Activity methods):

The surface is enabled once it is created and sized, and SurfaceRunner.onStart() and SurfaceRunner.onResume() have been called. You then start and stop it by calling SurfaceRunner.surfaceStart() and SurfaceRunner.surfaceStop().


Field Summary
static int SURFACE_CACHE_BG
          Instrument Surface runner option: cache a background bitmap.
 
Fields inherited from class org.hermit.android.core.SurfaceRunner
LOOPED_TICKER, SURFACE_DYNAMIC
 
Constructor Summary
InstrumentSurface(Activity app)
          Create a SurfaceRunner instance.
InstrumentSurface(Activity app, int options)
          Create a SurfaceRunner instance.
 
Method Summary
 void addGauge(Gauge i)
          Add a gauge to this surface.
 void addInstrument(Instrument i)
          Add an instrument to the system, associated with this surface.
protected  void animStart()
          We are starting the animation loop.
protected  void animStop()
          We are stopping the animation loop, for example to pause the app.
protected  void appSize(int width, int height, Bitmap.Config config)
          Set the screen size.
protected  void appStart()
          The application is starting.
protected  void appStop()
          The application is closing down.
protected  void doDraw(Canvas canvas, long now)
          Draw the current frame of the application.
protected  void doUpdate(long now)
          Update the state of the application for the current frame.
protected abstract  void layout(int width, int height)
          Lay out the display for a given screen size.
 
Methods inherited from class org.hermit.android.core.SurfaceRunner
getBitmap, getBitmap, getRes, onPause, onResume, onStart, onStop, onSurfaceThread, onWindowFocusChanged, optionSet, postUpdate, setDebugPerf, setDebugPos, setDelay, statsCount, statsCreate, statsTime, surfaceChanged, surfaceCreated, surfaceDestroyed, surfaceStart, surfaceStop
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

SURFACE_CACHE_BG

public static final int SURFACE_CACHE_BG
Instrument Surface runner option: cache a background bitmap. If set, we will ask all the gauges to draw their backgrounds into a full- screen bitmap; this bitmap will then be drawn prior to drawing the gauge contents each frame.

See Also:
Constant Field Values
Constructor Detail

InstrumentSurface

public InstrumentSurface(Activity app)
Create a SurfaceRunner instance.

Parameters:
app - The application context we're running in.

InstrumentSurface

public InstrumentSurface(Activity app,
                         int options)
Create a SurfaceRunner instance.

Parameters:
app - The application context we're running in.
options - Options for this SurfaceRunner. A bitwise OR of SURFACE_XXX constants.
Method Detail

addInstrument

public void addInstrument(Instrument i)
Add an instrument to the system, associated with this surface. Is is presumed that the app will create one or more Gauges for this instrument and add them to the surface with addGauge(Gauge).

All instruments added here will be started and stopped when the application starts and stops, and will have their measurement turned on when the app is visible and running. Their Instrument.doUpdate(long) method will be called each time round the main animation loop.

All instruments must be added before the application starts running.

Parameters:
i - The instrument to add.

addGauge

public void addGauge(Gauge i)
Add a gauge to this surface. If this gauge has an associated Instrument, it should be attached to the surface with addInstrument(Instrument).

All gauges added here will have their Gauge.draw(Canvas, long, boolean) method called each time round the main animation loop.

All gauges must be added before the application starts running.

Parameters:
i - The gauge to add.

layout

protected abstract void layout(int width,
                               int height)
Lay out the display for a given screen size. Subclasses must implement this, and should use it to lay out the gauges.

Parameters:
width - The new width of the surface.
height - The new height of the surface.

appStart

protected void appStart()
The application is starting. Perform any initial set-up prior to starting the application. We may not have a screen size yet, so this is not a good place to allocate resources which depend on that.

If subclasses override this, they must call through to this method.

Specified by:
appStart in class SurfaceRunner

appSize

protected void appSize(int width,
                       int height,
                       Bitmap.Config config)
Set the screen size. This is guaranteed to be called before animStart(), but perhaps not before appStart().

We call the layout() method here, so subclasses generally don't need to override this. If subclasses do override this, they must call through to this method.

Specified by:
appSize in class SurfaceRunner
Parameters:
width - The new width of the surface.
height - The new height of the surface.
config - The pixel format of the surface.

animStart

protected void animStart()
We are starting the animation loop. The screen size is known.

doUpdate() and doDraw() may be called from this point on.

If subclasses override this, they must call through to this method.

Specified by:
animStart in class SurfaceRunner

animStop

protected void animStop()
We are stopping the animation loop, for example to pause the app.

doUpdate() and doDraw() will not be called from this point on.

If subclasses override this, they must call through to this method.

Specified by:
animStop in class SurfaceRunner

appStop

protected void appStop()
The application is closing down. Clean up any resources.

Specified by:
appStop in class SurfaceRunner

doUpdate

protected void doUpdate(long now)
Update the state of the application for the current frame.

Applications must override this, and can use it to update for example the physics of a game. This may be a no-op in some cases.

doDraw() will always be called after this method is called; however, the converse is not true, as we sometimes need to draw just to update the screen. Hence this method is useful for updates which are dependent on time rather than frames.

Specified by:
doUpdate in class SurfaceRunner
Parameters:
now - Nominal time of the current frame in ms.

doDraw

protected void doDraw(Canvas canvas,
                      long now)
Draw the current frame of the application.

Applications must override this, and are expected to draw the entire screen into the provided canvas.

This method will always be called after a call to doUpdate(), and also when the screen needs to be re-drawn.

Specified by:
doDraw in class SurfaceRunner
Parameters:
canvas - The Canvas to draw into.
now - Nominal time of the current frame in ms.