PfExtentTextCharPositionsCx()

Calculate individual character positions, specifying a font context

Synopsis:

int PfExtentTextCharPositionsCx(
       struct _Pf_ctrl *context,
       PhRect_t *ptsExtent,
       PhPoint_t *ptsPos,
       char *psz,
       const char *pckFont,
       long adata,
       long bdata,
       int32_t *piIndices,
       int32_t *piPenPositions,
       int32_t iArrayLen,
       uint32_t ulFlags,
       int32_t iBytes,
       uint32_t uiExtentLen,
       PhRect_t const *pktsClip );

Arguments:

context

A pointer to the font context to use, which you can get by calling PfAttach().

ptsExtent

A pointer to a PhRect_t structure where the function stores the extent of the string.

ptsPos

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

psz

A pointer to a NUL-terminated character string.

pckFont

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

adata

The horizontal fractional point size, if you set PF_FRACTIONAL in the flags argument.

bdata

The vertical fractional point size, if you set PF_FRACTIONAL in the flags argument.

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.

iArrayLen

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

ulFlags

Flags that affect the behavior of the function.

You can set up to one of the following to indicate the format of the string:

• PF_WIDE_CHARS -- the string is composed of 16-bit wide characters. If you set this flag, the function assumes that each character is represented by 2 bytes that conform to the ISO/IEC 10646-1 UCS-2 double-byte format.
• PF_WIDE_CHAR32 -- the string is composed of 32-bit wide characters. If you set this flag, the function assumes that each character is represented by 4 bytes that conform to the ISO/IEC 10646-1 UCS-4 four-byte format.

  ---

  Although this flag allows for 32-bit wide characters, the underlying font system currently supports only characters up to Unicode U+FFFE.

  ---

If you don't set either of the above, the function assumes that the string is composed of UTF-8 multibyte characters.

You can OR in any of these flags:

• PF_CHAR_DRAW_POSITIONS -- if set, 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.

• PF_FRACTIONAL -- use a fractional 16.16 point size. If you set this flag, use the adata argument to specify the horizontal fractional point size, and bdata to specify the vertical fractional point size.

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:

PfExtentTextCharPositionsCx() lets you obtain the pen's x position after every index specified in the function call. This routine is useful when an application has mutiple _Pf_ctrl contexts defined.

The generic design of this routine allows for future expansion.

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 refers to 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:

In this example, 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 the symbol L, index 1 corresponds to the position after L, index 2 corresponds to the position after u, and so on:

#include <stdio.h>
#include <photon/PtProto.h>
#include <photon/Pf.h>
#include <errno.h>
#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];

int main(int argc, char * argv[])
{  struct _Pf_ctrl * pf;

   if(PtInit(NULL) == -1)
     return(EXIT_FAILURE);

   if((pf = PfAttach( NULL, 0 )) == NULL)
     return(EXIT_FAILURE);

   PfGenerateFontNameCx( pf, "Helvetica", 0, 24, caBuff);

   if( PfExtentTextCharPositionsCx( pf, &tsExtent, NULL,
       "Lucy", caBuff, 0, 0, iaIndex, iaPosition,
        MAX_INDICES, 0L, 0, 0, NULL) != EOK)
   {
      printf("Error in PfExtentTextCharPositionsCx().\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],
         iaPosition[4]);
   }

   PfDetach(pf);

   return(EXIT_SUCCESS);
}

Classification:

Photon

See also:

PfAttach(), PfDetach(), PfExtentFractTextCharPositions(), PfExtentTextCharPositions(), PfGenerateFontName(), PhPoint_t, PhRect_t