Package com.adobe.xfa.gfx

Class GFXMappingList

  • public class GFXMappingList
extends java.lang.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 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)

    • 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.