com.adobe.xfa.gfx

Class GFXMappingList

java.lang.Object

com.adobe.xfa.gfx.GFXMappingList

public class GFXMappingList
extends Object

A mapping list represents the complete set of mappings for some set of glyphs and corresponding Unicode characters. The mapping list does not store Unicode character values nor Glyph IDs; instead it stores simply indexes. The caller must maintain its character and glyph arrays separately.

The mapping list is made up of individual mappings. Each mapping describes the smallest indivisible relationship between one or more characters and one or more glyphs. For example, a mapping list that describes a simple 1:1 relationship between N left-to-right characters and their corresponding N glyphs would contain N individual mappings.

Character indexes and lengths refer to actual Unicode characters stored elsewhere by the application. If it chooses to use class String to store Unicode characters, it needs to be aware that these indexes are not the same as the UTF-8 byte indexes prevalent in many String method signatures. Fortunately, that class also provides Unicode character iteration methods.

Both Unicode character indexes and glyph indexes start at zero.

Field Summary

Fields

Modifier and Type	Field and Description
static int	MAPPING_ERR_CHAR_MAP_RANGE
static int	MAPPING_ERR_CHAR_OVERLAP
static int	MAPPING_ERR_CHAR_UNMAPPED
static int	MAPPING_ERR_GLYPH_MAP_RANGE
static int	MAPPING_ERR_GLYPH_OVERLAP
static int	MAPPING_ERR_GLYPH_UNMAPPED

Constructor Summary

Constructors

Constructor and Description
GFXMappingList() Default constructor.
GFXMappingList(GFXMappingList source)
GFXMappingList(int nSizeHint)
GFXMappingList(int nSizeHint, boolean bAutoMap) Constructor that initializes the mapping list.

Method Summary

Modifier and Type	Method and Description
void	addMapping(GFXMapping oMapping) Add one character/glyph mapping to the line.
void	addMapping(int nCharStart, int nGlyphStart)
void	addMapping(int nCharStart, int nGlyphStart, int nCharLength)
void	addMapping(int nCharStart, int nGlyphStart, int nCharLength, int nGlyphLength) Add one character/glyph mapping to the line.
void	autoMap(int nMappings) Repopulate the mapping list with a simple Latin-based 1:1 LTR mapping.
void	copyFrom(GFXMappingList source)
GFXMapping	getMapping(int nIndex) Extract one mapping from the list, by index.
int	getMappingCount() Return the number of mappings currently in the list.
void	orderByCharacter() Rearrange the mappings in the list, so that they are ordered by lowest character index in each mapping.
void	orderByGlyph() Rearrange the mappings in the list, so that they are ordered by lowest glyph index in each mapping.
void	reset() Reset the mapping list to its initial state.
void	validate()
void	validate(int pnExpectedChars)
void	validate(int pnExpectedChars, int pnExpectedGlyphs) Validate the contents of the mapping list.

Methods inherited from class java.lang.Object

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

Field Detail

MAPPING_ERR_CHAR_OVERLAP

public static final int MAPPING_ERR_CHAR_OVERLAP

See Also:

Constant Field Values

MAPPING_ERR_CHAR_UNMAPPED

public static final int MAPPING_ERR_CHAR_UNMAPPED

See Also:

Constant Field Values

MAPPING_ERR_CHAR_MAP_RANGE

public static final int MAPPING_ERR_CHAR_MAP_RANGE

See Also:

Constant Field Values

MAPPING_ERR_GLYPH_OVERLAP

public static final int MAPPING_ERR_GLYPH_OVERLAP

See Also:

Constant Field Values

MAPPING_ERR_GLYPH_UNMAPPED

public static final int MAPPING_ERR_GLYPH_UNMAPPED

See Also:

Constant Field Values

MAPPING_ERR_GLYPH_MAP_RANGE

public static final int MAPPING_ERR_GLYPH_MAP_RANGE

See Also:

Constant Field Values

Constructor Detail

GFXMappingList

public GFXMappingList()

Default constructor.

Constructs a mapping list that is initially empty of any mappings.

GFXMappingList

public GFXMappingList(int nSizeHint,
                      boolean bAutoMap)

Constructor that initializes the mapping list.

The caller can provide a size hint to reduce the number of reallocations that occur in building the mapping. In addition, the caller can request an automatic mapuseful if the text is simple 1:1 left-to-right Latin, with no substitutions.

Parameters:

nSizeHint - - Size to pre-allocate the internal list of mappings. This can be larger or smaller than the eventual number of mappings; the implementation will not use excess space, and will reallocate if necessary when mappings are added.

bAutoMap - - If true, the mapping list is initialized to represent a simple 1:1 left-to-right Latin mapping, with no substitutions. The size hint indicates the number of mappings required.

GFXMappingList

public GFXMappingList(int nSizeHint)

GFXMappingList

public GFXMappingList(GFXMappingList source)

Method Detail

reset

public void reset()

Reset the mapping list to its initial state.

The client typically calls this method after consuming the contents of a mapping list, if it wishes to reuse the object instance. There is no harm in calling Reset() repeatedly or calling it on a just-created mapping list object.

autoMap

public void autoMap(int nMappings)

Repopulate the mapping list with a simple Latin-based 1:1 LTR mapping.

This is a convenience method that maps glyphs to characters 1:1 from left to right. Any previous contents of the mapping list are first removed.

Parameters:

nMappings - - Number of 1:1 mappings to create.

addMapping

public void addMapping(GFXMapping oMapping)

Add one character/glyph mapping to the line. This overload allows the caller to add a single mapping to the list, with complete control over the contents of that mapping. For more information, see the documentation for class GFXMapping.

Parameters:

oMapping - - Mapping to add to the list.

addMapping

public void addMapping(int nCharStart,
                       int nGlyphStart,
                       int nCharLength,
                       int nGlyphLength)

Add one character/glyph mapping to the line.

This is a convenience method that eliminates the need to create a GFXMapping object, but does not allow for the rare case of disjoint character or glyph ranges.

The client specifies the mapping in terms of four parameters identifying both a sequential run of characters and a sequential run of glyphs. Given the parameter names listed in the method declaration, the mapping is interpreted as the nCharLength characters in the Unicode text, starting at index nCharIndex, map to the nGlyphLength glyphs in the rendering starting at nGlyphIndex.

Note that it takes multiple mappings to ensure all characters and glyphs are mapped, even when the mapping for each is 1:1. For example, specifying that two consecutive characters map to two consecutive glyphs in no way implies that the first character of the pair maps to the first glyph of the pair. It simply means there is a mapping between the pair of glyphs and the pair of characters that cannot be further refined.

Typically (though not always) at least one length parameter has a value of one; often both lengths have a value of one.

Parameters:

nCharStart - - Starting character index of the mapping.

nGlyphStart - - Starting glyph index of the mapping.

nCharLength - - Number of consecutive Unicode characters in the mapping.

nGlyphLength - - Number of consecutive glyphs in the mapping.

addMapping

public void addMapping(int nCharStart,
                       int nGlyphStart,
                       int nCharLength)

addMapping

public void addMapping(int nCharStart,
                       int nGlyphStart)

getMappingCount

public int getMappingCount()

Return the number of mappings currently in the list.

Returns:

Number of mappings currently in the list.

getMapping

public GFXMapping getMapping(int nIndex)

Extract one mapping from the list, by index.

Parameters:

nIndex - - Index of the desired mapping. Index numbers start at zero. Unpredictable results will occur if the index is out of range.

Returns:

The desired mapping.

validate

public void validate(int pnExpectedChars,
                     int pnExpectedGlyphs)

Validate the contents of the mapping list.

Validation ensures that no glyph or character is included in two or more mappings. In addition, the caller can request that characters and/or glyphs be tested for coverage and overflow. If the client specifies the number of characters expected, the validation process also ensures that every character index is included in a mapping and that no character index exceeds the maximum. The caller can request similar testing of glyph indexes by providing the maximum number of glyphs expected.

This method reports errors as exceptions, using the XTG exception mechanism.

Parameters:

pnExpectedChars - - Pointer to number of characters. If null, no character index coverage or overflow testing occurs.

pnExpectedGlyphs - - Pointer to number of glyphs. If null, no glyph index coverage or overflow testing occurs.

validate

public void validate(int pnExpectedChars)

validate

public void validate()

orderByCharacter

public void orderByCharacter()

Rearrange the mappings in the list, so that they are ordered by lowest character index in each mapping.

This is useful for applications that are driven by the Unicode content.

orderByGlyph

public void orderByGlyph()

Rearrange the mappings in the list, so that they are ordered by lowest glyph index in each mapping.

This is useful for applications that are driven by the rendered glyphs.

copyFrom

public void copyFrom(GFXMappingList source)