com.codename1.ui

Class Font

java.lang.Object

com.codename1.ui.CN1Constants

com.codename1.ui.CN

com.codename1.ui.Font

public class Font
extends CN

Codename One currently supports 3 font types:

• System fonts - these are very simplistic builtin fonts. They work on all platforms and come in one of 3 sizes. However, they are ubiquitous and work in every platform in all languages. A system font can be created using createSystemFont(int, int, int).
• TTF files - you can just place a TTF file in the src directory of the project and it will appear in the Codename One Designer as an option. You can load such a font using createTrueTypeFont(java.lang.String, java.lang.String).
• Native fonts - these aren't supported on all platforms but generally they allow you to use a set of platform native good looking fonts. E.g. on Android the devices Roboto font will be used and on iOS Helvetica Neue will be used. You can load such a font using createTrueTypeFont(java.lang.String, java.lang.String).

WARNING: If you use a TTF file MAKE SURE not to delete the file when there MIGHT be a reference to it. This can cause hard to track down issues!
IMPORTANT: due to copyright restrictions we cannot distribute Helvetica and thus can't simulate it. In the simulator you will see Roboto as the fallback in some cases and not the device font unless you are running on a Mac. Notice that the Roboto font from Google doesn't support all languages and thus special characters might not work on the simulator but would work on the device.

The sample code below demonstrates a catalog of available fonts, the scr

The demo code on the iPad simulator on a Mac

The demo code on an Android 5.1 OPO device (OnePlus One)

The Font class also supports bitmap fonts but this support is strictly aimed at legacy applications. We no longer maintain that functionality.

Field Summary

Fields inherited from class com.codename1.ui.CN

BASELINE, BOTTOM, CENTER, CENTER_BEHAVIOR_CENTER, CENTER_BEHAVIOR_CENTER_ABSOLUTE, CENTER_BEHAVIOR_SCALE, CENTER_BEHAVIOR_TOTAL_BELOW, EAST, FACE_MONOSPACE, FACE_PROPORTIONAL, FACE_SYSTEM, LEFT, NATIVE_ITALIC_BLACK, NATIVE_ITALIC_BOLD, NATIVE_ITALIC_LIGHT, NATIVE_ITALIC_REGULAR, NATIVE_ITALIC_THIN, NATIVE_MAIN_BLACK, NATIVE_MAIN_BOLD, NATIVE_MAIN_LIGHT, NATIVE_MAIN_REGULAR, NATIVE_MAIN_THIN, NORTH, RIGHT, SIZE_LARGE, SIZE_MEDIUM, SIZE_SMALL, SOUTH, STYLE_BOLD, STYLE_ITALIC, STYLE_PLAIN, STYLE_UNDERLINED, TOP, WEST

Fields inherited from class com.codename1.ui.CN1Constants

DENSITY_2HD, DENSITY_4K, DENSITY_560, DENSITY_HD, DENSITY_HIGH, DENSITY_LOW, DENSITY_MEDIUM, DENSITY_VERY_HIGH, DENSITY_VERY_LOW, GALLERY_ALL, GALLERY_ALL_MULTI, GALLERY_IMAGE, GALLERY_IMAGE_MULTI, GALLERY_VIDEO, GALLERY_VIDEO_MULTI, PICKER_TYPE_CALENDAR, PICKER_TYPE_DATE, PICKER_TYPE_DATE_AND_TIME, PICKER_TYPE_DURATION, PICKER_TYPE_DURATION_HOURS, PICKER_TYPE_DURATION_MINUTES, PICKER_TYPE_STRINGS, PICKER_TYPE_TIME, SMS_BOTH, SMS_INTERACTIVE, SMS_NOT_SUPPORTED, SMS_SEAMLESS

Method Summary

Modifier and Type	Method and Description
void	addContrast(byte value) Deprecated. bitmap font functionality is now deprecated
int	charsWidth(char[] ch, int offset, int length) Return the width of the given characters in this font instance
int	charWidth(char ch) Return the width of the specific character when rendered alone
static void	clearBitmapCache() Deprecated. bitmap font functionality is now deprecated
static Font	create(String lookup) Creates a new font instance based on the platform specific string name of the font.
static Font	createBitmapFont(Image bitmap, int[] cutOffsets, int[] charWidth, String charsets) Deprecated. bitmap font functionality is now deprecated
static Font	createBitmapFont(String name, Image bitmap, int[] cutOffsets, int[] charWidth, String charsets) Deprecated. bitmap font functionality is now deprecated
static Font	createSystemFont(int face, int style, int size) Creates a system native font in a similar way to common MIDP fonts
static Font	createTrueTypeFont(String fontName) Shorthand for createTrueTypeFont(name, name) which is useful for cases such as native: fonts.
static Font	createTrueTypeFont(String fontName, float sizeMm) Shorthand for createTrueTypeFont(name, name) & derive(size) which is useful for cases such as native: fonts.
static Font	createTrueTypeFont(String fontName, float size, byte sizeUnit) Shorthand for createTrueTypeFont(name, name) & derive(size) which is useful for cases such as native: fonts.
static Font	createTrueTypeFont(String fontName, String fileName) Creates a true type font with the given name/filename (font name might be different from the file name and is required by some devices e.g.
Font	derive(float sizePixels, int weight) Creates a font based on this truetype font with the given pixel, WARNING! This method will only work in the case of truetype fonts! Important some platforms e.g.
Font	derive(float size, int weight, byte unitType) Creates a font based on this truetype font with the given pixel, WARNING! This method will only work in the case of truetype fonts! Important some platforms e.g.
boolean	equals(Object o) Indicates whether some other object is "equal to" this one.
int	getAscent() The ascent is the amount by which the character ascends above the baseline.
static Font	getBitmapFont(String fontName) Deprecated. bitmap font functionality is now deprecated
String	getCharset() Returns a string containing all the characters supported by this font.
static Font	getDefaultFont() Return the global default font instance
int	getDescent() The descent is the amount by which the character descends below the baseline
int	getFace() Return Optional operation returning the font face for system fonts
int	getHeight() Return the total height of the font
Object	getNativeFont() Returns the internal implementation specific font object
float	getPixelSize() Returns the size with which the font object was created in case of truetype fonts/derived fonts.
int	getSize() Return Optional operation returning the font size for system fonts
int	getStyle() Return Optional operation returning the font style for system fonts
static boolean	isBitmapFontEnabled() Indicates whether bitmap fonts should be enabled when loading or the fallback system font should be used instead.
static boolean	isCreationByStringSupported() Returns true if the underlying platform allows creating a font based on a user submitted string.
static boolean	isNativeFontSchemeSupported() Indicates whether the implementation supports loading a font "natively" to handle one of the common native prefixes
static boolean	isTrueTypeFileSupported() Returns true if the underlying platform supports loading truetype fonts from a file.
boolean	isTTFNativeFont() Indicates if this is a TTF native font that can be derived and manipulated.
static void	setBitmapFontEnabled(boolean enabled) Indicates whether bitmap fonts should be enabled by default when loading or the fallback system font should be used instead.
static void	setDefaultFont(Font f) Sets the global default font instance
int	stringWidth(String str) Return the width of the given string in this font instance
int	substringWidth(String str, int offset, int len) Return the width of the given string subset in this font instance

Methods inherited from class com.codename1.ui.CN

addDefaultHeader, addEdtErrorHandler, addMessageListener, addNetworkErrorListener, addNetworkProgressListener, addToQueue, addToQueueAndWait, callSerially, callSeriallyAndWait, callSeriallyAndWait, callSeriallyOnIdle, canDial, canExecute, canForceOrientation, canInstallOnHomescreen, captureScreen, clearStorage, clearStorageCache, convertToPixels, convertToPixels, convertToPixels, convertToPixels, createSoftWeakRef, createStorageInputStream, createStorageOutputStream, createThread, delete, deleteStorageFile, deregisterPush, dial, execute, existsInFileSystem, existsInStorage, exitApplication, exitFullScreen, extractHardRef, flushStorageCache, getAppHomePath, getCachesDir, getCurrentForm, getDeviceDensity, getDisplayHeight, getDisplayWidth, getDragStartPercentage, getFileLastModifiedFile, getFileLength, getFileSystemRootAvailableSpace, getFileSystemRoots, getFileSystemRootSizeBytes, getFileSystemRootType, getPlatformName, getPluginSupport, getProperty, getResourceAsStream, getSharedJavascriptContext, getSMSSupport, hasCachesDir, hasCamera, invokeAndBlock, invokeWithoutBlocking, invokeWithoutBlockingWithResultSync, isDarkMode, isDesktop, isDirectory, isEdt, isEnableAsyncStackTraces, isFullScreenSupported, isHiddenFile, isInFullScreenMode, isMinimized, isNativePickerTypeSupported, isNativeShareSupported, isPortrait, isScreenSaverDisableSupported, isSimulator, isTablet, killAndWait, listFiles, listStorageEntries, lockOrientation, log, log, minimizeApplication, mkdir, onCanInstallOnHomescreen, openFileInputStream, openFileOutputStream, openFileOutputStream, openGallery, postMessage, promptInstallOnHomescreen, readObjectFromStorage, registerPush, removeEdtErrorHandler, removeMessageListener, removeNetworkErrorListener, removeNetworkProgressListener, renameFile, requestFullScreen, restoreMinimizedApplication, restoreToBookmark, scheduleBackgroundTask, sendLog, sendMessage, sendSMS, sendSMS, setBookmark, setDarkMode, setDragStartPercentage, setEnableAsyncStackTraces, setHiddenFile, setInterval, setProperty, setScreenSaverEnabled, setTimeout, share, share, showNativePicker, startThread, storageEntrySize, unlockOrientation, updateNetworkThreadCount, vibrate, writeObjectToStorage

Methods inherited from class java.lang.Object

clone, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getBitmapFont

public static Font getBitmapFont(String fontName)

Deprecated. bitmap font functionality is now deprecated

Returns a previously loaded bitmap font from cache

Parameters:

fontName - the font name is the logical name of the font

Returns:

the font object

See Also:

clearBitmapCache()

clearBitmapCache

public static void clearBitmapCache()

Deprecated. bitmap font functionality is now deprecated

Bitmap fonts are cached this method allows us to flush the cache thus allows us to reload a font

isTrueTypeFileSupported

public static boolean isTrueTypeFileSupported()

Returns true if the underlying platform supports loading truetype fonts from a file.

Returns:

true if the underlying platform supports loading truetype fonts from a file

isCreationByStringSupported

public static boolean isCreationByStringSupported()

Returns true if the underlying platform allows creating a font based on a user submitted string.

Returns:

true if the underlying platform allows creating a font based on a user submitted string

isNativeFontSchemeSupported

public static boolean isNativeFontSchemeSupported()

Indicates whether the implementation supports loading a font "natively" to handle one of the common native prefixes

Returns:

true if the "native:" prefix is supported by loadTrueTypeFont

createTrueTypeFont

public static Font createTrueTypeFont(String fontName)

Shorthand for createTrueTypeFont(name, name) which is useful for cases such as native: fonts. If a TTF file is passed this method will throw an exception!

Parameters:

fontName - the native font name. Notice that TTF file names are prohibited

Returns:

a font object

createTrueTypeFont

public static Font createTrueTypeFont(String fontName,
                                      float sizeMm)

Shorthand for createTrueTypeFont(name, name) & derive(size) which is useful for cases such as native: fonts.

Parameters:

fontName - the native font name

sizeMm - the size in mm

Returns:

a font object

createTrueTypeFont

public static Font createTrueTypeFont(String fontName,
                                      float size,
                                      byte sizeUnit)

Shorthand for createTrueTypeFont(name, name) & derive(size) which is useful for cases such as native: fonts.

Parameters:

fontName - the native font name

size - the size in the specified unit.

sizeUnit - The unit type of the size. One of Style.UNIT_TYPE_DIPS, * Style.UNIT_TYPE_PIXELS, * Style.UNIT_TYPE_REM, * Style.UNIT_TYPE_VW, * Style.UNIT_TYPE_VH, * Style.UNIT_TYPE_VMIN, * Style.UNIT_TYPE_VMAX.

Returns:

a font object

Since:

8.0

createTrueTypeFont

public static Font createTrueTypeFont(String fontName,
                                      String fileName)

Creates a true type font with the given name/filename (font name might be different from the file name and is required by some devices e.g. iOS). The font file must reside in the src root of the project in order to be detectable. The file name should contain no slashes or any such value.
Important some platforms e.g. iOS don't support changing the weight of the font and require you to use the font name matching the weight, so the weight argument to derive will be ignored!
This system also supports a special "native:" prefix that uses system native fonts e.g. HelveticaNeue on iOS and Roboto on Android. It supports the following types: native:MainThin, native:MainLight, native:MainRegular, native:MainBold, native:MainBlack, native:ItalicThin, native:ItalicLight, native:ItalicRegular, native:ItalicBold, native:ItalicBlack. Important due to copyright restrictions we cannot distribute Helvetica and thus can't simulate it. In the simulator you will see Roboto and not the device font unless you are running on a Mac

Parameters:

fontName - the name of the font

fileName - the file name of the font as it appears in the src directory of the project, it MUST end with the .ttf extension!

Returns:

the font object created or null if true type fonts aren't supported on this platform

derive

public Font derive(float size,
                   int weight,
                   byte unitType)

Creates a font based on this truetype font with the given pixel, WARNING! This method will only work in the case of truetype fonts!
Important some platforms e.g. iOS don't support changing the weight of the font and require you to use the font name matching the weight, so the weight argument to derive will be ignored!

Parameters:

size - the size of the font in the specified unit type.

weight - PLAIN, BOLD or ITALIC weight based on the constants in this class

unitType - The unit type of the size. One of Style.UNIT_TYPE_DIPS, Style.UNIT_TYPE_PIXELS, Style.UNIT_TYPE_REM, Style.UNIT_TYPE_VW, Style.UNIT_TYPE_VH, Style.UNIT_TYPE_VMIN, Style.UNIT_TYPE_VMAX.

Returns:

scaled font instance

Since:

8.0

derive

public Font derive(float sizePixels,
                   int weight)

Creates a font based on this truetype font with the given pixel, WARNING! This method will only work in the case of truetype fonts!
Important some platforms e.g. iOS don't support changing the weight of the font and require you to use the font name matching the weight, so the weight argument to derive will be ignored!

Parameters:

sizePixels - the size of the font in pixels

weight - PLAIN, BOLD or ITALIC weight based on the constants in this class

Returns:

scaled font instance

isTTFNativeFont

public boolean isTTFNativeFont()

Indicates if this is a TTF native font that can be derived and manipulated. This is true for a font loaded from file (TTF) or using the native: font name

Returns:

true if this is a native font

create

public static Font create(String lookup)

Creates a new font instance based on the platform specific string name of the font. This method isn't supported on some platforms.

Parameters:

lookup - a set of platform specific names delimited by commas, the first succefully loaded font will be used

Returns:

newly created font or null if creation failed

addContrast

public void addContrast(byte value)

Deprecated. bitmap font functionality is now deprecated

Increase the contrast of the bitmap font for rendering on top of a surface whose color is darker. This is useful when drawing anti-aliased bitmap fonts using a light color (e.g. white) on top of a dark surface (e.g. black), the font often breaks down if its contrast is not increased due to the way alpha blending appears to the eye.

Notice that this method only works in one way, contrast cannot be decreased properly in a font and it should be cleared and reloaed with a Look and Feel switch.

Parameters:

value - the value to increase

createBitmapFont

public static Font createBitmapFont(String name,
                                    Image bitmap,
                                    int[] cutOffsets,
                                    int[] charWidth,
                                    String charsets)

Deprecated. bitmap font functionality is now deprecated

Creates a bitmap font with the given arguments and places said font in the cache

Parameters:

name - the name for the font in the cache

bitmap - a transparency map in red and black that indicates the characters

cutOffsets - character offsets matching the bitmap pixels and characters in the font

charWidth - The width of the character when drawing... this should not be confused with the number of cutOffset[o + 1] - cutOffset[o]. They are completely different since a character can be "wider" and "seep" into the next region. This is especially true with italic characters all of which "lean" outside of their bounds.

charsets - the set of characters in the font

Returns:

a font object to draw bitmap fonts

createBitmapFont

public static Font createBitmapFont(Image bitmap,
                                    int[] cutOffsets,
                                    int[] charWidth,
                                    String charsets)

Deprecated. bitmap font functionality is now deprecated

Creates a bitmap font with the given arguments

Parameters:

bitmap - a transparency map in red and black that indicates the characters

cutOffsets - character offsets matching the bitmap pixels and characters in the font

charWidth - The width of the character when drawing... this should not be confused with the number of cutOffset[o + 1] - cutOffset[o]. They are completely different since a character can be "wider" and "seep" into the next region. This is especially true with italic characters all of which "lean" outside of their bounds.

charsets - the set of characters in the font

Returns:

a font object to draw bitmap fonts

createSystemFont

public static Font createSystemFont(int face,
                                    int style,
                                    int size)

Creates a system native font in a similar way to common MIDP fonts

Parameters:

face - One of FACE_SYSTEM, FACE_PROPORTIONAL, FACE_MONOSPACE

style - one of STYLE_PLAIN, STYLE_ITALIC, STYLE_BOLD

size - One of SIZE_SMALL, SIZE_MEDIUM, SIZE_LARGE

Returns:

A newly created system font instance

charsWidth

public int charsWidth(char[] ch,
                      int offset,
                      int length)

Return the width of the given characters in this font instance

Parameters:

ch - array of characters

offset - characters offsets

length - characters length

Returns:

the width of the given characters in this font instance

substringWidth

public int substringWidth(String str,
                          int offset,
                          int len)

Return the width of the given string subset in this font instance

Parameters:

str - the given string

offset - the string offset

len - the len od string

Returns:

the width of the given string subset in this font instance

stringWidth

public int stringWidth(String str)

Return the width of the given string in this font instance

Parameters:

str - the given string *

Returns:

the width of the given string in this font instance

charWidth

public int charWidth(char ch)

Return the width of the specific character when rendered alone

Parameters:

ch - the specific character

Returns:

the width of the specific character when rendered alone

getHeight

public int getHeight()

Return the total height of the font

Returns:

the total height of the font

getDefaultFont

public static Font getDefaultFont()

Return the global default font instance

Returns:

the global default font instance

setDefaultFont

public static void setDefaultFont(Font f)

Sets the global default font instance

Parameters:

f - the global default font instance

getFace

public int getFace()

Return Optional operation returning the font face for system fonts

Returns:

Optional operation returning the font face for system fonts

getSize

public int getSize()

Return Optional operation returning the font size for system fonts

Returns:

Optional operation returning the font size for system fonts

getStyle

public int getStyle()

Return Optional operation returning the font style for system fonts

Returns:

Optional operation returning the font style for system fonts

getCharset

public String getCharset()

Returns a string containing all the characters supported by this font. Will return null for system fonts.

Returns:

String containing the characters supported by a bitmap font or null otherwise.

setBitmapFontEnabled

public static void setBitmapFontEnabled(boolean enabled)

Indicates whether bitmap fonts should be enabled by default when loading or the fallback system font should be used instead. This allows easy toggling of font loading.

Parameters:

enabled - true to enable bitmap font loading (if they exist in the resource)

isBitmapFontEnabled

public static boolean isBitmapFontEnabled()

Indicates whether bitmap fonts should be enabled when loading or the fallback system font should be used instead. This allows easy toggling of font loading.

Returns:

true by default indicating that bitmap font loading is enabled

getNativeFont

public Object getNativeFont()

Returns the internal implementation specific font object

Returns:

platform specific font object for use by implementation classes or native code

equals

public boolean equals(Object o)

Indicates whether some other object is "equal to" this one. The equals method implements an equivalence relation: It is reflexive: for any reference value x, x.equals(x) should return true. It is symmetric: for any reference values x and y, x.equals(y) should return true if and only if y.equals(x) returns true. It is transitive: for any reference values x, y, and z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true. It is consistent: for any reference values x and y, multiple invocations of x.equals(y) consistently return true or consistently return false, provided no information used in equals comparisons on the object is modified. For any non-null reference value x, x.equals(null) should return false. The equals method for class Object implements the most discriminating possible equivalence relation on objects; that is, for any reference values x and y, this method returns true if and only if x and y refer to the same object (x==y has the value true).

Overrides:

equals in class Object

getAscent

public int getAscent()

The ascent is the amount by which the character ascends above the baseline.

Returns:

the ascent in pixels

getDescent

public int getDescent()

The descent is the amount by which the character descends below the baseline

Returns:

the descent in pixels

getPixelSize

public float getPixelSize()

Returns the size with which the font object was created in case of truetype fonts/derived fonts. This is useful since a platform might change things slightly based on platform constraints but this value should be 100% consistent

Returns:

the size requested in the derive method