PfExtentTextCharPositions()

Calculate individual character positions

Synopsis:

int PfExtentTextCharPositions( 
        PhRect_t * ptsExtent,
        PhPoint_t * ptsPos,
        char * psz, 
        const char * pckFont,
        int32_t * piIndices,
        int32_t * piPenPositions, 
        int32_t iArrayLen,
        uint32_t ulFlags,
        int32_t iBytes,
        uint32_t uiExtentLen,
        PhRect_t const * pktsClip );

Arguments:

ptsExtent

A pointer to a PhRect_t structure that's used to store the extent of the string.

ptsPos

A pointer to a PhPoint_t structure that's used as an offset to apply against the extent. If NULL, no offset is added to the extent values.

psz

A pointer to a NUL-terminated character string.

pckFont

The font name, as created by PfGenerateFontName().

iArrayLen

The number of integer entries in the piIndices and piPenPositions arrays.

piIndices

A pointer to an integer array of length iArrayLen. An index corresponds to a location within the string pointed to by psz.

For example, index 0 relates to the pen's x position at the start of the string, index 1 corresponds to the pen's x position after character 1, index 2 corresponds to the pen's x position after character 2, and so on.

The indexes must be in numerical order, in order to function as expected.

piPositions

A pointer to an integer array of length iArrayLen. This array contains the resulting pen x values (in pixels), for each index.

ulFlags

A 32-bit value used for flags. Values that can be ORed in are:

• PF_WIDE_CHARS -- the characters pointed to by psz are an array of wchar_t characters. By default, the function assumes the characters are multibyte.

  ---

  This function assumes each character is represented by 2 bytes that conform to the ISO/IEC 10646-1 UCS-2 double-byte format.

  ---

• PF_CHAR_DRAW_POSITIONS -- if turned on, the bearing x value of the next symbols aren't applied to the returned pen x positions. This is useful when placing cursors:

  

  If this bit isn't set, the bearing x value of the next symbols are applied to the pen x positions. This is useful when drawing symbols individually, where you need to know where to place the x origin of each symbol:

  

iBytes

The number of bytes in the string. If this is 0, the function assumes that the number of bytes is:

strlen( psz ) / wstrlen( psz )
  

uiExtentLen

The number of characters from the beginning of the string to include in the extent. If 0, the entire string is extented, as permitted by the clipping rectangle.

pktsClip

A clipping rectangle to be used to reduce processing, depending on the value of pktsClip->lr.x (in pixels). If pktsClip is NULL, no clipping is applied.

Library:

ph

Description:

PfExtentTextCharPositions() lets you obtain the pen's x position after every index specified in the function call.

Returns:

0

Success.

-1

An error occurred; errno is set.

Errors:

ERANGE

The font manager couldn't fulfill the request; one of the following is true:

• The iArrayLen argument is larger than strlen(psz).
• If index 0 is requested, then iArrayLen is larger than strlen(psz) + 1.
• The iArrayLen argument is less than or equal to 0.
• An index in piIndices references a character greater than strlen(psz).

EFAULT

One of ptsExtent, piIndices, piPenPositions, pckFont, or psz is NULL.

EINVAL

The font is fixed-width, and an error occurred when trying to retrieve the common width of all characters in that particular font.

EMORE

Something unexpected occurred while processing a run of characters.

Examples:

#define MAX_INDICES 5
#define FALSE 0

int iaIndex[MAX_INDICES] = {0, 1, 2, 3, 4};
int iaPosition[MAX_INDICES];
PhRect_t tsExtent;
char caBuff[MAX_FONT_TAG];

PfGenerateFontName("Helvetica", 0, 24, caBuff);

if( PfExtentTextCharPositions( &tsExtent, NULL,
       "Lucy", caBuff, iaIndex, iaPositon,
        MAX_INDICES, 0L, 0, 0, NULL) != EOK)
  printf("Error in PfExtentTextCharPositions().\n");
else
  printf("Pixel penx positions after each character \
in string %s, are as follows: %d %d %d %d %d.\n",
         "Lucy", iaPosition[0], iaPosition[1],
         iaPosition[2], iaPosition[3],
         iaPositionArray[4]);

The pixel pen x positions for each character in the string Lucy are placed in the integer array iaPos, according to the indexes specified in iaIndex. Index 0 corresponds to the position before symbol L, index 1 corresponds to the position after L, index 2 corresponds to the position after u, and so on.

Classification:

Photon

See also:

PfExtent(), PfExtentCx(), PfExtentText(), PfExtentTextCharPositionsCx(), PfExtentTextToRect(), PfExtentFractTextCharPositions(), PfFractionalExtentText(), PfGenerateFontName(), PhPoint_t, PhRect_t

Fonts chapter of the Photon Programmer's Guide