PgDrawTextArea(), PgDrawTextAreaCx()

Draw text within an area

Synopsis:

int PgDrawTextArea( char const *ptr,
                    int len,
                    PhRect_t const *rect,
                    int flags );

int PgDrawTextAreaCx( void *dc,
                      char const *ptr,
                      int len,
                      PhRect_t const *rect,
                      int flags );

Library:

ph

Description:

These functions draw text within an area, using the font specified by a previous call to PgSetFont*(). This area is clipped to the dimensions of the rectangle specified by the PhRect_t structure pointed to by rect.

The len parameter specifies the number of bytes required to store the string. For pure ASCII strings (characters 0 to 127), this is the number of characters. For multibyte strings, len may be larger than the number of characters. For double-byte strings, len is twice the number of characters.

By default, the text is left-aligned (Pg_TEXT_LEFT), and the text is drawn with its baseline centered inside the drawing area.

The flags can be a combination of:

Pg_BACK_FILL

Fill the text extent with fill-color parameters.

Pg_TEXT_WIDECHAR

The text is specified as wide characters. Each character is represented by 16 bits.

Pg_TEXT_ELLIPSIS

If the text doesn't fit into the specified rectangle, draw an ellipsis (...) instead of part of the text, in accordance with the text's alignment. For example, if the text is left-aligned, draw the ellipsis instead of the end of the text; if the text is right-aligned, draw the ellipsis instead of the beginning.

Pg_TEXT_ELLIPSIS_MIDDLE

Draw the ellipsis in the middle of the string. You must also set Pg_TEXT_ELLIPSIS.

Pg_TEXT_ELLIPSIS_INVERT

Invert the ellipsis location. You must also set Pg_TEXT_ELLIPSIS.

Pg_TEXT_LEFT

Align text to left edge of rect (rect->ul.l).

Pg_TEXT_RIGHT

Align text to right edge of rect (rect->lr.r).

Pg_TEXT_CENTER

Center text horizontally within rect.

Pg_TEXT_TOP

Align text to top edge of rect (rect->ul.y).

Pg_TEXT_BOTTOM

Align text to bottom edge of rect (rect->lr.y).

Pg_TEXT_MIDDLE

Center text vertically within rect.

PgDrawTextArea() works on the current draw context, while you can specify the draw context dc for PgDrawTextAreaCx().

Returns:

0

Success.

-1

An error occurred.

Classification:

Photon

Caveats:

PgDrawTextArea() doesn't work in any context that involves the render library, such as printing or Phindows. If your application needs to use the render library, you should:

1. Calculate the position at which to print the text, based on the extent of the text and the desired alignment inside the drawing area.
2. Set a clipping rectangle with PgSetUserClip*() or PgSetUserClipAbsolute*().
3. Call PgDrawText() to display the text.

See also:

PgDrawMultiTextArea*(), PgDrawString*(), PgDrawText*(), PgFlush*(), PgSetFillColor*(), PgSetFillDither*(), PgSetFillTransPat*(), PgSetFont*(), PgSetTextColor*(), PgSetTextDither*(), PgSetTextTransPat*(), PgSetTextXORColor*(), PgSetUnderline(), PhRect_t

“Text” in the Raw Drawing and Animation chapter of the Photon Programmer's Guide