PfExtentFractTextCharPositions()

Calculate individual character positions, using fractional scaling

Synopsis:

#include <photon/Pf.h>

int PfExtentFractTextCharPositions(
       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,
       uint32_t uiXscale,
       uint32_t uiYscale );

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

A pointer to a NUL-terminated constant character string, containing the stem name of the particular font. You should use PfGenerateFontName() to create this.

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.

uiXscale, uiYscale

Horizontal and vertical scaling factors in 16.16 format.

Library:

ph

Description:

PfExtentFractTextCharPositions() lets you obtain the pen's x position after every index specified in the function call. It's similar to PfExtentTextCharPositions(), except that fractional scaling is applied.

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.

Classification:

Photon

See also:

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

Fonts chapter of the Photon Programmer's Guide