org.hermit.android.instruments
Class Gauge

java.lang.Object
  extended by org.hermit.android.instruments.Gauge
Direct Known Subclasses:
PowerGauge, SpectrumGauge, TextGauge, WaveformGauge

public class Gauge
extends java.lang.Object

A graphical display which shows some data in a region within a view. The data may come from an Instrument or some other source.

Configuration

Your gauge will be notified of its geometry by a call to setGeometry(Rect). This is where you should note your position and size and perform any internal layout you need to do.

Note that if you are running in an app which handles screen configuration changes, setGeometry(Rect) will be called any time the screen changes size or shape (e.g. on an orientation change). You should be prepared to handle these subsequent calls by re-creating data structures, re-doing layout, etc., as required.

Data Updating

It is assumed that your gauge has some kind of data source, but how this works is up to you.

Drawing Sequence -- User

A gauge may have a background which is rendered separately from its content, for performance reasons. Hence, a Gauge user must request the background to be drawn, and then the gauge content to be drawn. If the caller is going to cache the background, the background need be requested only when the geometry changes.

There are two options. In the non-caching case, the caller may simply call draw(Canvas, long, boolean), passing true as the last argument. This asks the Gauge to draw its background and its content.

In the caching case, the caller should call drawBackground(Canvas) to ask the gauge to draw its background into the given canvas. Since the gauge will use the same co-ordinates that it uses to draw to the screen, the canvas will need to be the size of the screen (or you can translate the co-ordinates). Then, to draw the gauge, the caller should render the stored background and then call draw(Canvas, long, boolean).

Drawing Sequence -- Implementor

From the Gauge implementor's point of view, there are two routines to implement: drawBackgroundBody(Canvas, Paint) (optional), and drawBody(Canvas, Paint, long).

If your implementation of drawBody(Canvas, Paint, long) draws a complete, opaque rendition of the gauge, that's all you need; there's no need to provide an implementation of drawBackgroundBody(). But if your gauge has a separate, persistent background appearance, you may reap a performance benefit by separating out its drawing. Do this by implementing drawBackgroundBody(Canvas, Paint). This routine should draw the gauge background at the gauge's configured position in the specified Canvas.

A facility is provided for caching background images. To use this, call cacheBackground() once your layout is set up -- for example at the end of setGeometry(Rect). At that point, your background will be fetched (by calling your implementation of drawBackgroundBody()) and stored; then when someone asks us to draw our background, the request will be satisfied using the stored bitmap, without calling your drawBackgroundBody() again.


Constructor Summary
Gauge(SurfaceRunner parent)
          Set up this view.
Gauge(SurfaceRunner parent, int options)
          Set up this view.
Gauge(SurfaceRunner parent, int grid, int plot)
          Set up this view.
Gauge(SurfaceRunner parent, int options, int grid, int plot)
          Set up this view.
 
Method Summary
protected  void cacheBackground()
          Fetch and cache an image of the background now, then use that to draw the background on future draw requests.
 void draw(Canvas canvas, long now, boolean bg)
          This method is called to ask the element to draw its dynamic content.
 void drawBackground(Canvas canvas)
          This method is called to ask the element to draw its static content; i.e.
protected  void drawBackgroundBody(Canvas canvas, Paint paint)
          Do the subclass-specific parts of drawing the background for this element.
protected  void drawBody(Canvas canvas, Paint paint, long now)
          Do the subclass-specific parts of drawing for this element.
protected  void drawFinish(Canvas canvas, Paint paint, long now)
          Wrap up drawing of this element.
protected  void drawStart(Canvas canvas, Paint paint, long now)
          Do initial parts of drawing for this element.
 void error(int error)
          An error has occurred.
 int getBackgroundColor()
          Get the background colour of this element.
static float getBaseTextSize()
          Get the base size for text.
 Rect getBounds()
          Get the bounding rect of this Element.
 int getGridColor()
          Get the data scale / grid colour of this element.
static float getHeadTextSize()
          Get the size for header text.
 int getHeight()
          Get the height of this element -- i.e.
static int getInnerGap()
          Get the amount of padding within atoms within an element.
static int getInterPadding()
          Get the amount of padding between major elements in a view.
static float getMiniTextSize()
          Get the size for mini text.
protected  Paint getPaint()
          Get this element's Paint.
 int getPlotColor()
          Get the data plot colour of this element.
 int getPreferredHeight()
          Get the minimum preferred height for this atom.
 int getPreferredWidth()
          Get the minimum preferred width for this atom.
static int getSidebarWidth()
          Get the sidebar width.
protected  SurfaceRunner getSurface()
          Get the app context of this Element.
static float getTextScaleX()
          Get the base size for text based on this screen's size.
static Typeface getTextTypeface()
          Get the default font for all text.
static float getTinyTextSize()
          Get the size for tiny text based on this screen's size.
 int getWidth()
          Get the width of this element -- i.e.
 boolean haveBounds()
          Determine whether we have the bounding rect of this Element.
protected  void initializePaint(Paint paint)
          Set up the paint for this element.
 boolean optionSet(int option)
          Check whether the given option flag is set on this surface.
 void setBackgroundColor(int col)
          Set the background colour of this element.
static void setBaseTextSize(float size)
          Set the base size for text.
 void setDataColors(int grid, int plot)
          Set the plot colours of this element.
 void setGeometry(Rect bounds)
          This is called during layout when the size of this element has changed.
 void setGridColor(int grid)
          Set the data scale / grid colour of this element.
static void setHeadTextSize(float size)
          Set the size for header text.
static void setInnerGap(int gap)
          Set the amount of padding within atoms within an element.
static void setInterPadding(int pad)
          Set the amount of padding between major elements in a view.
static void setMiniTextSize(float size)
          Set the size for mini text.
 void setPlotColor(int plot)
          Set the data plot colour of this element.
static void setSidebarWidth(int width)
          Set the sidebar width.
static void setTextScaleX(float scale)
          Set the horizontal scaling of the font; this can be used to produce a tall, thin font.
static void setTextTypeface(Typeface face)
          Set the default font for all text.
static void setTinyTextSize(float size)
          Set the size for tiny text.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Gauge

public Gauge(SurfaceRunner parent)
Set up this view.

Parameters:
parent - Parent surface.

Gauge

public Gauge(SurfaceRunner parent,
             int options)
Set up this view.

Parameters:
parent - Parent surface.
options - Options for this SurfaceRunner. A bitwise OR of GAUGE_XXX constants.

Gauge

public Gauge(SurfaceRunner parent,
             int grid,
             int plot)
Set up this view.

Parameters:
parent - Parent surface.
grid - Colour for drawing a data scale / grid.
plot - Colour for drawing data plots.

Gauge

public Gauge(SurfaceRunner parent,
             int options,
             int grid,
             int plot)
Set up this view.

Parameters:
parent - Parent surface.
options - Options for this SurfaceRunner. A bitwise OR of GAUGE_XXX constants.
grid - Colour for drawing a data scale / grid.
plot - Colour for drawing data plots.
Method Detail

initializePaint

protected void initializePaint(Paint paint)
Set up the paint for this element. This is called during initialization. Subclasses can override this to do class-specific one-time initialization.

Parameters:
paint - The paint to initialize.

optionSet

public boolean optionSet(int option)
Check whether the given option flag is set on this surface.

Parameters:
option - The option flag to test; one of GAUGE_XXX.
Returns:
true iff the option is set.

setTextTypeface

public static void setTextTypeface(Typeface face)
Set the default font for all text.

Parameters:
face - The default font for all text.

getTextTypeface

public static Typeface getTextTypeface()
Get the default font for all text.

Returns:
The default font for all text.

setBaseTextSize

public static void setBaseTextSize(float size)
Set the base size for text.

Parameters:
size - Base text size for the app.

getBaseTextSize

public static float getBaseTextSize()
Get the base size for text.

Returns:
Base text size for the app.

setHeadTextSize

public static void setHeadTextSize(float size)
Set the size for header text.

Parameters:
size - Header text size for the app.

getHeadTextSize

public static float getHeadTextSize()
Get the size for header text.

Returns:
Header text size for the app.

setMiniTextSize

public static void setMiniTextSize(float size)
Set the size for mini text.

Parameters:
size - Mini text size for the app.

getMiniTextSize

public static float getMiniTextSize()
Get the size for mini text.

Returns:
Mini text size for the app.

setTinyTextSize

public static void setTinyTextSize(float size)
Set the size for tiny text.

Parameters:
size - Tiny text size for the app.

getTinyTextSize

public static float getTinyTextSize()
Get the size for tiny text based on this screen's size.

Returns:
Tiny text size for the app.

setTextScaleX

public static void setTextScaleX(float scale)
Set the horizontal scaling of the font; this can be used to produce a tall, thin font.

Parameters:
scale - Horizontal scaling of the font.

getTextScaleX

public static float getTextScaleX()
Get the base size for text based on this screen's size.

Returns:
Horizontal scaling of the font.

setSidebarWidth

public static void setSidebarWidth(int width)
Set the sidebar width.

Parameters:
width - The sidebar width.

getSidebarWidth

public static int getSidebarWidth()
Get the sidebar width.

Returns:
The sidebar width.

setInterPadding

public static void setInterPadding(int pad)
Set the amount of padding between major elements in a view.

Parameters:
pad - The amount of padding between major elements in a view.

getInterPadding

public static int getInterPadding()
Get the amount of padding between major elements in a view.

Returns:
The amount of padding between major elements in a view.

setInnerGap

public static void setInnerGap(int gap)
Set the amount of padding within atoms within an element. Specifically the small gaps in side bars.

Parameters:
gap - The amount of padding within atoms within an element

getInnerGap

public static int getInnerGap()
Get the amount of padding within atoms within an element. Specifically the small gaps in side bars.

Returns:
The amount of padding within atoms within an element

setGeometry

public void setGeometry(Rect bounds)
This is called during layout when the size of this element has changed. This is where we first discover our size, so set our geometry to match.

Parameters:
bounds - The bounding rect of this element within its parent View.

cacheBackground

protected void cacheBackground()
Fetch and cache an image of the background now, then use that to draw the background on future draw requests. The cached image is invalidated the next time the geometry changes.

Implementations should call this method once their layout is set -- for example at the end of setGeometry(Rect) -- if they have a significant static background that they wish to have cached.


getPreferredWidth

public int getPreferredWidth()
Get the minimum preferred width for this atom.

Returns:
The minimum preferred width for this atom. Returns zero if we don't know yet.

getPreferredHeight

public int getPreferredHeight()
Get the minimum preferred height for this atom.

Returns:
The minimum preferred height for this atom. Returns zero if we don't know yet.

haveBounds

public final boolean haveBounds()
Determine whether we have the bounding rect of this Element.

Returns:
True if our geometry has been set up.

getBounds

public final Rect getBounds()
Get the bounding rect of this Element.

Returns:
The bounding rect of this element within its parent View. This will be 0, 0, 0, 0 if setGeometry() has not been called yet.

getWidth

public final int getWidth()
Get the width of this element -- i.e. the current configured width.

Returns:
The width of this element within its parent View. This will be 0 if setGeometry() has not been called yet.

getHeight

public final int getHeight()
Get the height of this element -- i.e. the current configured height.

Returns:
The height of this element within its parent View. This will be 0 if setGeometry() has not been called yet.

setBackgroundColor

public void setBackgroundColor(int col)
Set the background colour of this element.

Parameters:
col - The new background colour, in ARGB format.

getBackgroundColor

public int getBackgroundColor()
Get the background colour of this element.

Returns:
The background colour, in ARGB format.

setDataColors

public void setDataColors(int grid,
                          int plot)
Set the plot colours of this element.

Parameters:
grid - Colour for drawing a data scale / grid.
plot - Colour for drawing data plots.

setGridColor

public void setGridColor(int grid)
Set the data scale / grid colour of this element.

Parameters:
grid - Colour for drawing a data scale / grid.

setPlotColor

public void setPlotColor(int plot)
Set the data plot colour of this element.

Parameters:
plot - Colour for drawing a data plot.

getGridColor

public int getGridColor()
Get the data scale / grid colour of this element.

Returns:
Colour for drawing a data scale / grid.

getPlotColor

public int getPlotColor()
Get the data plot colour of this element.

Returns:
Colour for drawing data plots.

error

public void error(int error)
An error has occurred. Notify the user somehow.

Subclasses can override this to do something neat.

Parameters:
error - ERR_XXX code describing the error.

getPaint

protected Paint getPaint()
Get this element's Paint.

Returns:
The Paint which was set up in initializePaint().

drawBackground

public void drawBackground(Canvas canvas)
This method is called to ask the element to draw its static content; i.e. the background / chrome.

Parameters:
canvas - Canvas to draw into.

drawBackgroundBody

protected void drawBackgroundBody(Canvas canvas,
                                  Paint paint)
Do the subclass-specific parts of drawing the background for this element. Subclasses should override this if they have significant background content which they would like to draw once only. Whatever is drawn here will be saved in a bitmap, which will be rendered to the screen before the dynamic content is drawn.

Obviously, if implementing this method, don't clear the screen when drawing the dynamic part.

Parameters:
canvas - Canvas to draw into.
paint - The Paint which was set up in initializePaint().

draw

public void draw(Canvas canvas,
                 long now,
                 boolean bg)
This method is called to ask the element to draw its dynamic content.

Parameters:
canvas - Canvas to draw into.
now - Nominal system time in ms. of this update.
bg - Iff true, tell the gauge to draw its background first. This is cheaper than calling drawBackground(Canvas) before this method.

drawStart

protected void drawStart(Canvas canvas,
                         Paint paint,
                         long now)
Do initial parts of drawing for this element.

Parameters:
canvas - Canvas to draw into.
paint - The Paint which was set up in initializePaint().
now - Nominal system time in ms. of this update.

drawBody

protected void drawBody(Canvas canvas,
                        Paint paint,
                        long now)
Do the subclass-specific parts of drawing for this element. Subclasses should override this to do their drawing.

Parameters:
canvas - Canvas to draw into.
paint - The Paint which was set up in initializePaint().
now - Nominal system time in ms. of this update.

drawFinish

protected void drawFinish(Canvas canvas,
                          Paint paint,
                          long now)
Wrap up drawing of this element.

Parameters:
canvas - Canvas to draw into.
paint - The Paint which was set up in initializePaint().
now - Nominal system time in ms. of this update.

getSurface

protected SurfaceRunner getSurface()
Get the app context of this Element.

Returns:
The app context we're running in.