momelog.listener
Class LogCanvas

java.lang.Object
  javax.microedition.lcdui.Displayable
      javax.microedition.lcdui.Canvas
          javax.microedition.lcdui.game.GameCanvas
              momelog.listener.LogCanvas

All Implemented Interfaces:

Runnable, Configurable, LogListener

public class LogCanvas
extends GameCanvas
implements LogListener, Runnable, Configurable

LogListener implementation intended to display formatted logging events on device's or emulator's screen. LogCanvas extends GameCanvas. It makes use of key events, and, of course, doesn't suppress them. It's view consists of scrollable text area. It is refreshed on every logging event's arrival. All formatted logging events are wrapped on character basis and displayed on text area. Scrollbar is shown only, when logging information occupies more than one page. Scrollbar's cursor has different color at the edge positions (top and bottom) from that at the middle, This indicates first and last (at that moment ;-)) line. See LogCanvas Screen Shots. Users can scroll one line or page up or down, move to the top or bottom of logging, toggle fullscreen mode or reset buffer by pressing only one key. Key events are processed in separate thread (started when LogCanvas is shown and stopped on hide). This eliminates conflicts with callbacks processing thread and provides for better resources use. All logging events are converted to strings and appended to the StringBuffer. Developer can explore any logging event at any time.

LogCanvas can be used like any other Displayable. Developers can (or even should) add/remove commands, set CommandListener or title. LogCanvas is preset with the title of "Logging". No commands are added, and no CommandListener is set. It is initially not in fullscreen mode. fullscreen mode of LogCanvas can be changed at any time and it's view will be adjusted.

LogCanvas can be instantiated using null-arg constructor LogCanvas(). If MoMELog logging framework was configured to use LogCanvas for processing logging events (see MoMELog Guide), LogCanvas instance can be obtained by calling Logger.getLogListener() static method.

LogCanvas is fully customizable. It provides means to completely configure it's view and partly behavior. LogCanvas implements Configurable interface. It can be configured declaratively from character sequence and/or programmatically by using setter methods. See LogCanvas Guide for more details.

Font used for rendering text can be set by using setFont(Font) method. Background or foreground colors can be configured by calling setBgColor(int) or setFgColor(int) respective methods. Developers can set scrollbar, scrollbar's cursor at the middle positions or scrollbar's cursor at the edge positions colors by invoking setScrollbarColor(int), setScrollbarCursorColor(int) or setScrollbarCursorEdgeColor(int) respective methods. The above methods should be called, when LogCanvas is hidden. In other case these methods throw IllegalStateException.

As mentioned above, all logging information is saved in StringBuffer. When dealing with very detailed logging and running application on device, that restricts memory very much, there is possibility of memory shortage (I didn't encounter such situations). In such situations, developers can reset buffer by invoking resetBuffer() method. This method actually doesn't reset buffer, but frees buffer reference, sets a new one and runs garbage collector (if property runGCOnReset is set to true (the default)). Property runGCOnReset can be set or queried by respective setter or getter methods (setRunGCOnReset(boolean), isRunGCOnReset()).

See LogCanvas Guide for more details about LogCanvas.

Version:

1.0

Author:

Sergio Morozov

Field Summary

static int	DEFAULT_BG_COLOR Default background color (dark green).
static int	DEFAULT_FG_COLOR Default foreground color (white).
static Font	DEFAULT_FONT Default font for rendering text (proportional,plain.small).
static int	DEFAULT_SCROLLBAR_COLOR Default scrollbar color (green).
static int	DEFAULT_SCROLLBAR_CURSOR_COLOR Default color of scrollbar's cursor at the middle positions (white).
static int	DEFAULT_SCROLLBAR_CURSOR_EDGE_COLOR Default color of scrollbar's cursor at the edge positions (red).

Fields inherited from class javax.microedition.lcdui.game.GameCanvas

DOWN_PRESSED, FIRE_PRESSED, GAME_A_PRESSED, GAME_B_PRESSED, GAME_C_PRESSED, GAME_D_PRESSED, LEFT_PRESSED, RIGHT_PRESSED, UP_PRESSED

Fields inherited from class javax.microedition.lcdui.Canvas

DOWN, FIRE, GAME_A, GAME_B, GAME_C, GAME_D, KEY_NUM0, KEY_NUM1, KEY_NUM2, KEY_NUM3, KEY_NUM4, KEY_NUM5, KEY_NUM6, KEY_NUM7, KEY_NUM8, KEY_NUM9, KEY_POUND, KEY_STAR, LEFT, RIGHT, UP

Constructor Summary

LogCanvas()
Instantiates LogCanvas.

Method Summary

void	configure(char[] lines, int offset, int length) Configures LogCanvas instance from the specified character sequence.
boolean	isRunGCOnReset() Tests whether garbage collector is running run after buffer reset.
void	onLog(LogEvent event) Formats given logging event by configured Formatter and appends it to the buffer.
void	resetBuffer() Resets logging buffer.
void	run() Processes commands.
void	setBgColor(int color) Sets background color of text.
void	setFgColor(int color) Sets foreground color of text.
void	setFont(Font font) Sets font for rendering text.
void	setFullScreenMode(boolean mode)
void	setRunGCOnReset(boolean runGCOnReset) Sets whether garbage collector should be run after buffer reset.
void	setScrollbarColor(int color) Sets color of scrollbar.
void	setScrollbarCursorColor(int color) Sets color of scrollbar's cursor at the middle positions.
void	setScrollbarCursorEdgeColor(int color) Sets color of scrollbar's cursor at the edge positions.

Methods inherited from class javax.microedition.lcdui.game.GameCanvas

flushGraphics, flushGraphics, getKeyStates, paint

Methods inherited from class javax.microedition.lcdui.Canvas

getGameAction, getKeyCode, getKeyName, hasPointerEvents, hasPointerMotionEvents, hasRepeatEvents, isDoubleBuffered, repaint, repaint, serviceRepaints

Methods inherited from class javax.microedition.lcdui.Displayable

addCommand, getHeight, getTicker, getTitle, getWidth, isShown, removeCommand, setCommandListener, setTicker, setTitle

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_FONT

public static final Font DEFAULT_FONT

Default font for rendering text (proportional,plain.small).

Since:

1.0

DEFAULT_BG_COLOR

public static final int DEFAULT_BG_COLOR

Default background color (dark green).

Since:

1.0

See Also:

Constant Field Values

DEFAULT_FG_COLOR

public static final int DEFAULT_FG_COLOR

Default foreground color (white).

Since:

1.0

See Also:

Constant Field Values

DEFAULT_SCROLLBAR_COLOR

public static final int DEFAULT_SCROLLBAR_COLOR

Default scrollbar color (green).

Since:

1.0

See Also:

Constant Field Values

DEFAULT_SCROLLBAR_CURSOR_COLOR

public static final int DEFAULT_SCROLLBAR_CURSOR_COLOR

Default color of scrollbar's cursor at the middle positions (white).

Since:

1.0

See Also:

Constant Field Values

DEFAULT_SCROLLBAR_CURSOR_EDGE_COLOR

public static final int DEFAULT_SCROLLBAR_CURSOR_EDGE_COLOR

Default color of scrollbar's cursor at the edge positions (red).

Since:

1.0

See Also:

Constant Field Values

Constructor Detail

LogCanvas

public LogCanvas()

Instantiates LogCanvas. Initializes it with title of "Logging".

Method Detail

resetBuffer

public void resetBuffer()

Resets logging buffer. This method frees reference to StringBuffer containing formatted logging information, sets buffer to a newly constructed StringBuffer and then, if runGCOnReset property is set to true (default), runs garbage collector.

Note: All of these operations are performed in a separate thread.

Note: These operations are performed only when key events processing thread is running (i.e. LogCanvas is shown). If this method is called, when LogCanvas is hidden, it queues the respective command and returns immediately. Buffer reset will occur after LogCanvas displaying.

setFullScreenMode

public void setFullScreenMode(boolean mode)

Overrides:

setFullScreenMode in class Canvas

setRunGCOnReset

public void setRunGCOnReset(boolean runGCOnReset)

Sets whether garbage collector should be run after buffer reset. This method can be called at any time even when LogCanvas is shown.

Parameters:

runGCOnReset - if true garbage collector should be run after buffer reset, not otherwise.

isRunGCOnReset

public boolean isRunGCOnReset()

Tests whether garbage collector is running run after buffer reset.

Returns:

true if garbage collector is running after buffer reset, false otherwise.

setBgColor

public void setBgColor(int color)

Sets background color of text. This method must be called, when LogCanvas is hidden.

Parameters:

color - color to set.

Throws:

IllegalStateException - if LogCanvas is shown.

setFgColor

public void setFgColor(int color)

Sets foreground color of text. This method must be called, when LogCanvas is hidden.

Parameters:

color - color to set.

Throws:

IllegalStateException - if LogCanvas is shown.

setScrollbarColor

public void setScrollbarColor(int color)

Sets color of scrollbar. This method must be called, when LogCanvas is hidden.

Parameters:

color - color to set.

Throws:

IllegalStateException - if LogCanvas is shown.

setScrollbarCursorColor

public void setScrollbarCursorColor(int color)

Sets color of scrollbar's cursor at the middle positions. This method must be called, when LogCanvas is hidden.

Parameters:

color - color to set.

Throws:

IllegalStateException - if LogCanvas is shown.

setScrollbarCursorEdgeColor

public void setScrollbarCursorEdgeColor(int color)

Sets color of scrollbar's cursor at the edge positions. This method must be called, when LogCanvas is hidden.

Parameters:

color - color to set.

Throws:

IllegalStateException - if LogCanvas is shown.

setFont

public void setFont(Font font)

Sets font for rendering text. This method must be called, when LogCanvas is hidden.

Parameters:

font - font to set.

Throws:

IllegalStateException - if LogCanvas is shown.

onLog

public void onLog(LogEvent event)

Formats given logging event by configured Formatter and appends it to the buffer. Sends command to refresh it's view.

Specified by:

onLog in interface LogListener

Parameters:

event - LogEvent instance containing information about logging event.

See Also:

LogListener.onLog(momelog.LogEvent)

configure

public void configure(char[] lines,
                      int offset,
                      int length)

Configures LogCanvas instance from the specified character sequence. Character sequence should consist of lines separated by new-line character ('\n'). Each line should contain name-value pair separated by equal sign (=). White spaces around names and values are allowed and ignored. If some property is specified more than one time, the last occurrence prevails.

LogCanvas supports following properties.

Property Name	Description	Default Value
"bgcolor"	Specifies background color of text. Since version 1.0	002F00 (dark green)
"fgcolor"	Specifies foreground color of text. Since version 1.0	FFFFFF (white)
"font"	Specifies font to use for rendering text. The format of this property is <Face>,<Style>,<Size> Face = PROPRTIONAL|MONOSPACE|SYSTEM Style = (PLAIN|BOLD|ITALIC|UNDERLINED)(;(PLAIN|BOLD|ITALIC|UNDERLINED))* Size = LARGE|MEDIUM|SMALL Note No spaces are allowed. Keywords are case insensitive. Since version 1.0	proportional,plain,small
"rungconreset"	Specifies whether garbage collector is running after buffer reset. if true, on or yes garbage collector is running, not otherwise. Since version 1.0	true (is run)
"scrollbarcolor"	Specifies color of scrollbar. Since version 1.0	00BF00 (green)
"scrollbarcursorcolor"	Specifies color of scrollbar's cursor at the middle positions. Since version 1.0	FFFFFF (white)
"scrollbarcursoredgecolor"	Specifies color of scrollbar's cursor at the edge (top or bottom) positions. Since version 1.0	EF1F00 (dark red)

For example following initialization file snippet configures LogCanvas to not run garbage collector on buffer reset, sets font to proportional, bold, italic and small, background color to white, foreground - black, scrollbar - gray, scrollbar cursor at middle positions - yellow and scrollbar cursor at edge positions to white.

  #sets LogCanvas as logListener
  listener = momelog.listener.LogCanvas
    
  #don't run gc
  listener.rungconreset = off
    
  #view setting
  listener.font = proportional,bold;italic,small
  listener.bgcolor = FFFFFF
  listener.fgcolor = 0
  listener.scrollbarcolor = BFBFBF
  listener.scrollbarcursorcolor = EFEF00
  listener.scrollbarcursoredgecolor = FFFFFF
 

See LogCanvas Guide for details.

Specified by:

configure in interface Configurable

Parameters:

lines - char array containing character sequence.

offset - position of the first character of sequence in given array.

length - length of the sequence in characters.

run

public void run()

Processes commands.

Specified by:

run in interface Runnable