PfExtent(), PfExtentCx()

Calculate the extent rectangle of a text string

Synopsis:

int PfExtent( PhRect_t *extent,
              PhPoint_t const *pos, 
              const char *font,
              long adata,
              long bdata, 
              const char *str,
              int len,
              int flags, 
              PhRect_t const *clip );

int PfExtentCx( struct _Pf_ctrl *context,
                PhRect_t *extent,
                PhPoint_t const *pos, 
                const char *font,
                long adata,
                long bdata, 
                const char *str,
                int len,
                int flags, 
                PhRect_t const *clip );

Arguments:

context

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

extent

A pointer to a PhRect_t structure where the function stores the calculated extent. The members are:

• ul.x -- the left bearing.
• lr.x -- the maximum x distance.
• ul.y -- the ascender.
• lr.y -- the descender.

The baseline of the font is at position y=0; the width of the string is:

lr.x - min(ul.x, 0) + 1
  

pos

A pointer to a PhPoint_t structure that specifies an offset to apply to the extent. If pos is NULL, no offset is applied.

font

The base font, which you should create by calling PfGenerateFontName().

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.

str

The string whose extent you want to calculate. The string is a UTF-8 multibyte one by default.

len

The length of the string, str, in bytes. If len is 0, the function uses strlen(str).

flags

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_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.
• PF_RECT -- make the function behave like PfExtentTextToRect(). If you set this flag, use the clip argument to specify the rectangle to extent within. If successful, the function returns the number of characters that fit within the rectangle.

clip

A pointer to a PhRect_t structure that's a suggested clipping rectangle for the font manager to abide by.

Library:

ph

Description:

These functions calculate the extent rectangle of a text string. The base font determines the ascender and descender values of the extent. The width depends on the string; the actual font used by characters within the string may be different than this base font (as specified in the fontext and fontmap files).

The difference between PfExtent() and PfExtentCx() is that PfExtentCx() lets you specify the font context to use.

If metrics for the base font have been loaded locally (see PfLoadMetrics()), the extent are calculated internally; otherwise a request is sent to the font server.

The generic design of these routines allows for future expansion.

Returns:

If you set PF_RECT in the flags argument, PfExtent() and PfExtentCx() return the number of characters that fit within the rectangle specified by clip, or -1 if an error occurred.

If you don't set PF_RECT in the flags argument, these functions return 0 on success, or -1 if an error occurred.

Classification:

Photon

See also:

PfAttach(), PfDetach(), PfExtentComponents(), PfExtentFractTextCharPositions(), PfExtentText(), PfExtentTextCharPositions(), PfExtentTextToRect(), PfExtentWideText(), PfFractionalExtentText(), PfGenerateFontName(), PfLoadMetrics(), PhPoint_t, PhRect_t