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

Safety:
Interrupt handler No
Signal handler No
Thread No

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