ru.zorin.pictfont
Class PictFont

java.lang.Object
  extended by ru.zorin.pictfont.PictFont

public class PictFont
extends java.lang.Object

The PictFont repersents custom fonts and font metrics. Fonts CAN be created by applications. Class PictFont allows you to use custom fonts in your MIDlet for mobile phone. Fonts may be proportional, multi-colored or even animated. You can use several fonts in one MIDlet. Fonts can be loaded from jar-file or from the net or from Record Store.


Nested Class Summary
 class PictFont.RSFilter
          Auxiliary class for using as filter in enumerateRecords()
 
Field Summary
static short SYM_FIRST
          Code for first symbol included in this font
static short SYM_SPACE
          Code of space symbol
static short SYM_UNKNOWN
          Code of unknown symbol
 
Constructor Summary
PictFont()
          Constructor
 
Method Summary
 int charsWidth(char[] ch, int offset, int length)
          Returns the advance width of the characters in ch, starting at the specified offset and for the specified number of characters (length).
 int charWidth(char ch)
          Gets the advance width of the specified character in this Font.
 void drawChar(javax.microedition.lcdui.Graphics g, char character, int x, int y, int anchor)
          Draws the specified character using this PictFont.
 void drawChars(javax.microedition.lcdui.Graphics g, char[] data, int offset, int length, int x, int y, int anchor)
          Draws the specified characters using this PictFont.
 int drawCode(javax.microedition.lcdui.Graphics g, short code, int x, int y)
          Draws character with specified code using anchor=LEFT|TOP.
 int drawCode(javax.microedition.lcdui.Graphics g, short code, int x, int y, int anchor)
          Draws character with specified code.
 int drawCodes(javax.microedition.lcdui.Graphics g, short[] codes, int x, int y)
          Draws characters with specified codes using anchor=LEFT|TOP.
 int drawCodes(javax.microedition.lcdui.Graphics g, short[] codes, int x, int y, int anchor)
          Draws characters with specified codes.
 void drawString(javax.microedition.lcdui.Graphics g, java.lang.String str, int x, int y, int anchor)
          Draws the specified String using the this PictFont.
 void drawSubstring(javax.microedition.lcdui.Graphics g, java.lang.String str, int offset, int len, int x, int y, int anchor)
          Draws the specified String using the current font and color.
 int getBaselinePosition()
          Gets the distance in pixels from the top of the text to the text's baseline.
 short getCode(char ch)
          Gets intrernal code of character.
 short[] getCodes(java.lang.String str)
          Gets short array with internal codes of all characters of the string.
 int getFace()
          Gets the face of the font.
 int getHeight()
          Gets the standard height of a line of text in this font.
 int getLeading()
          Gets the leading in pixels.
 int getLetterSpacing()
          Gets the distance in pixels between two letters.
 int getMidline()
          Gets the distance in pixels from the top of the text to the text's midline.
 int getSet()
          Gets number of currently used set of symbols.
 int getSize()
          Gets the size of the font.
 int getStyle()
          Gets the style of the font.
 int getWidth(short code)
          Gets actual width of character with specified code.
 int getWidth(short[] codes)
          Gets actual width of character string with specified codes.
 boolean isBold()
          Returns true if the font is bold.
 boolean isItalic()
          Returns true if the font is italic.
 boolean isPlain()
          Returns true if the font is plain.
 boolean isUnderlined()
          Returns true if the font is underlined.
 int loadFromBinaryResource(java.lang.String info_name, java.lang.String image_name)
          Loads font data from files stored in midlet jar.
 int loadFromResource(java.lang.String info_name, java.lang.String image_name)
          Loads font data from files stored in midlet jar.
 int loadFromStore(java.lang.String name)
          Load font data from Record Store.
 int recolor(int color)
          Recolor pixels of mainColor with new color.
 int saveToStore(java.lang.String name)
          Save font data to Record Store.
 int setSet(int set)
          Defines set of symbol for using.
 int stringWidth(java.lang.String str)
          Gets the total advance width for showing the specified String in this Font.
 int substringWidth(java.lang.String str, int offset, int len)
          Gets the total advance width for showing the specified substring in this Font.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

SYM_UNKNOWN

public static final short SYM_UNKNOWN
Code of unknown symbol

See Also:
Constant Field Values

SYM_SPACE

public static final short SYM_SPACE
Code of space symbol

See Also:
Constant Field Values

SYM_FIRST

public static final short SYM_FIRST
Code for first symbol included in this font

See Also:
Constant Field Values
Constructor Detail

PictFont

public PictFont()
Constructor

Method Detail

loadFromResource

public int loadFromResource(java.lang.String info_name,
                            java.lang.String image_name)
Loads font data from files stored in midlet jar.

Parameters:
info_name - file name of description
image_name - file name of image
Returns:
status: 0 - successful, negative - failed

saveToStore

public int saveToStore(java.lang.String name)
Save font data to Record Store.

Parameters:
name - name used for identification font in Record Store
Returns:
status: 0 - successful, negative - failed ( -1 - common error, -2 - record storage is full, -3 - out of memory error )

loadFromStore

public int loadFromStore(java.lang.String name)
Load font data from Record Store.

Parameters:
name - name used for identification font in Record Store
Returns:
status: 0 - successful, negative - failed

loadFromBinaryResource

public int loadFromBinaryResource(java.lang.String info_name,
                                  java.lang.String image_name)
Loads font data from files stored in midlet jar.

Parameters:
info_name - file name of description
image_name - file name of image
Returns:
status: 0 - successful, negative - failed

getStyle

public int getStyle()
Gets the style of the font. The value is an OR'ed combination of STYLE_BOLD, STYLE_ITALIC, and STYLE_UNDERLINED; or the value is zero (STYLE_PLAIN).

Returns:
style of the this font
See Also:
Font.getStyle()

getSize

public int getSize()
Gets the size of the font.

Returns:
one of SIZE_SMALL, SIZE_MEDIUM, SIZE_LARGE
See Also:
Font.getSize()

getFace

public int getFace()
Gets the face of the font.

Returns:
one of FACE_SYSTEM, FACE_PROPORTIONAL, FACE_MONOSPACE
See Also:
Font.getFace()

isPlain

public boolean isPlain()
Returns true if the font is plain.

Returns:
true if font is plain
See Also:
Font.isPlain()

isBold

public boolean isBold()
Returns true if the font is bold.

Returns:
true if font is bold
See Also:
Font.isBold()

isItalic

public boolean isItalic()
Returns true if the font is italic.

Returns:
true if font is italic
See Also:
Font.isItalic()

isUnderlined

public boolean isUnderlined()
Returns true if the font is underlined.

Returns:
true if font is underlined
See Also:
Font.isUnderlined()

getHeight

public int getHeight()
Gets the standard height of a line of text in this font. This value includes sufficient spacing to ensure that lines of text painted this distance from anchor point to anchor point are spaced as intended by the font designer and the device. This extra space (leading) occurs below the text.

Returns:
standard height of a line of text in this font (a non-negative value)
See Also:
Font.getHeight()

getBaselinePosition

public int getBaselinePosition()
Gets the distance in pixels from the top of the text to the text's baseline.

Returns:
the distance in pixels from the top of the text to the text's baseline
See Also:
Font.getBaselinePosition()

getMidline

public int getMidline()
Gets the distance in pixels from the top of the text to the text's midline. Midline (aka mean line) is the line that determines where non-ascending lowercase letters terminate (such as u,n,a,c,e).

Returns:
the distance in pixels from the top of the text to the text's midline
See Also:
midline at Wikipedia

getLeading

public int getLeading()
Gets the leading in pixels. Leading is amount of added vertical spacing between lines of type.

Returns:
the leading in pixels.
See Also:
Leading at Wikipedia

getLetterSpacing

public int getLetterSpacing()
Gets the distance in pixels between two letters.

Returns:
the distance in pixels between letters
See Also:
Letter-spacing at Wikipedia

recolor

public int recolor(int color)
Recolor pixels of mainColor with new color.

Parameters:
color - new color
Returns:
status: 0 - successful, negative - failed

charWidth

public int charWidth(char ch)
Gets the advance width of the specified character in this Font. The advance width is the horizontal distance that would be occupied if ch were to be drawn using this Font, including inter-character spacing following ch necessary for proper positioning of subsequent text.

Parameters:
ch - the character to be measured
Returns:
the total advance width (a non-negative value)
See Also:
Font.charWidth(char)

charsWidth

public int charsWidth(char[] ch,
                      int offset,
                      int length)
Returns the advance width of the characters in ch, starting at the specified offset and for the specified number of characters (length). The advance width is the horizontal distance that would be occupied if the characters were to be drawn using this Font, including inter-character spacing following the characters necessary for proper positioning of subsequent text.

The offset and length parameters must specify a valid range of characters within the character array ch. The offset parameter must be within the range [0..(ch.length)], inclusive. The length parameter must be a non-negative integer such that (offset + length) <= ch.length.

Parameters:
ch - the array of characters
offset - the index of the first character to measure
length - the number of characters to measure
Returns:
the width of the character range
Throws:
java.lang.ArrayIndexOutOfBoundsException - if offset and length specify an invalid range
java.lang.NullPointerException - - if ch is null
See Also:
Font.charsWidth(char[], int, int)

stringWidth

public int stringWidth(java.lang.String str)
Gets the total advance width for showing the specified String in this Font. The advance width is the horizontal distance that would be occupied if str were to be drawn using this Font, including inter-character spacing following str necessary for proper positioning of subsequent text.

Parameters:
str - the String to be measured
Returns:
the total advance width
Throws:
java.lang.NullPointerException - - if str is null
See Also:
Font.stringWidth(java.lang.String)

substringWidth

public int substringWidth(java.lang.String str,
                          int offset,
                          int len)
Gets the total advance width for showing the specified substring in this Font. The advance width is the horizontal distance that would be occupied if the substring were to be drawn using this Font, including inter-character spacing following the substring necessary for proper positioning of subsequent text.

The offset and len parameters must specify a valid range of characters within str. The offset parameter must be within the range [0..(str.length())], inclusive. The len parameter must be a non-negative integer such that (offset + len) <= str.length().

Parameters:
str - the String to be measured
offset - zero-based index of first character in the substring
len - length of the substring
Returns:
the total advance width
Throws:
java.lang.StringIndexOutOfBoundsException - if offset and length specify an invalid range
java.lang.NullPointerException - if str is null
See Also:
Font.substringWidth(java.lang.String, int, int)

drawChar

public void drawChar(javax.microedition.lcdui.Graphics g,
                     char character,
                     int x,
                     int y,
                     int anchor)
Draws the specified character using this PictFont.

Parameters:
g - the Graphics object to be used for drawing
character - the character to be drawn
x - the x coordinate of the anchor point
y - the y coordinate of the anchor point
anchor - the anchor point for positioning the text;
Throws:
java.lang.IllegalArgumentException - if anchor is not a legal value
See Also:
Graphics.drawChar(char, int, int, int)

drawChars

public void drawChars(javax.microedition.lcdui.Graphics g,
                      char[] data,
                      int offset,
                      int length,
                      int x,
                      int y,
                      int anchor)
Draws the specified characters using this PictFont.

The offset and length parameters must specify a valid range of characters within the character array data. The offset parameter must be within the range [0..(data.length)], inclusive. The length parameter must be a non-negative integer such that (offset + length) <= data.length.

Parameters:
g - the Graphics object to be used for drawing
data - the array of characters to be drawn
offset - the array of characters to be drawn
length - the number of characters to be drawn
x - the x coordinate of the anchor point
y - the y coordinate of the anchor point
anchor - the anchor point for positioning the text
Throws:
java.lang.ArrayIndexOutOfBoundsException - if offset and length do not specify a valid range within the data array
java.lang.IllegalArgumentException - if anchor is not a legal value
java.lang.NullPointerException - if data is null
See Also:
Graphics.drawChars(char[], int, int, int, int, int)

drawString

public void drawString(javax.microedition.lcdui.Graphics g,
                       java.lang.String str,
                       int x,
                       int y,
                       int anchor)
Draws the specified String using the this PictFont. The x,y position is the position of the anchor point.

Parameters:
g - the Graphics object to be used for drawing
str - the String to be drawn
x - the x coordinate of the anchor point
y - the y coordinate of the anchor point
anchor - the anchor point for positioning the text
See Also:
Graphics.drawString(java.lang.String, int, int, int)

drawSubstring

public void drawSubstring(javax.microedition.lcdui.Graphics g,
                          java.lang.String str,
                          int offset,
                          int len,
                          int x,
                          int y,
                          int anchor)
Draws the specified String using the current font and color. The x,y position is the position of the anchor point.

The offset and len parameters must specify a valid range of characters within the string str. The offset parameter must be within the range [0..(str.length())], inclusive. The len parameter must be a non-negative integer such that (offset + len) <= str.length().

Parameters:
g - the Graphics object to be used for drawing
str - the String to be drawn
offset - zero-based index of first character in the substring
len - length of the substring
x - the x coordinate of the anchor point
y - the y coordinate of the anchor point
anchor - the anchor point for positioning the text
See Also:
Graphics.drawSubstring(java.lang.String, int, int, int, int, int)

getSet

public int getSet()
Gets number of currently used set of symbols.

Returns:
number of set

setSet

public int setSet(int set)
Defines set of symbol for using.

Parameters:
set - new set
Returns:
old set

getCode

public short getCode(char ch)
Gets intrernal code of character. Returns SYM_UNKNOWN if character is not found in this PictFont.

Parameters:
ch - character
Returns:
internal code of this character

getCodes

public short[] getCodes(java.lang.String str)
Gets short array with internal codes of all characters of the string.

Parameters:
str - string
Returns:
short array with internal codes

getWidth

public int getWidth(short code)
Gets actual width of character with specified code. This is not advance width of character which used in Font.charWidth(char ch). Actual width does not include inter-character space.

Parameters:
code -
Returns:
actual width of character with code

getWidth

public int getWidth(short[] codes)
Gets actual width of character string with specified codes. This is not advance width of character which used in Font.charWidth(char ch). Actual width does not include inter-character space.

Parameters:
codes - array of character codes
Returns:
actual width of character string with codes

drawCode

public int drawCode(javax.microedition.lcdui.Graphics g,
                    short code,
                    int x,
                    int y)
Draws character with specified code using anchor=LEFT|TOP.

Parameters:
g - Graphics
code - code of character
x - the x coordinate of top left corner
y - the y coordinate of top left corner
Returns:
actual width of drawn character

drawCode

public int drawCode(javax.microedition.lcdui.Graphics g,
                    short code,
                    int x,
                    int y,
                    int anchor)
Draws character with specified code.

Parameters:
g - Graphics
code - code of character
x - the x coordinate of top left corner
y - the y coordinate of top left corner
Returns:
actual width of drawn character

drawCodes

public int drawCodes(javax.microedition.lcdui.Graphics g,
                     short[] codes,
                     int x,
                     int y)
Draws characters with specified codes using anchor=LEFT|TOP.

Parameters:
g - Graphics object
codes - array of character codes
x - the x coordinate of top left corner
y - the y coordinate of top left corner
Returns:
actual width of drawn characters

drawCodes

public int drawCodes(javax.microedition.lcdui.Graphics g,
                     short[] codes,
                     int x,
                     int y,
                     int anchor)
Draws characters with specified codes.

Parameters:
g - Graphics
codes - code array with string of characters
x - the x coordinate of top left corner
y - the y coordinate of top left corner
Returns:
actual width of drawn character