[Previous] [Contents] [Index] [Next]

PgDrawText(), PgDrawTextmx(), PgDrawTextChars()

Draw text

Synopsis:

int PgDrawText( char const *ptr,
                int len,
                PhPoint_t const *pos,
                int flags );

int PgDrawTextmx( char const *ptr,
                  int len,
                  PhPoint_t const *pos,
                  int flags );

int PgDrawTextChars( char const *ptr,
                     int len,
                     PhPoint_t const *pos,
                     int flags );

Description:

Each of these functions builds a command in the draw buffer to draw the text indicated by ptr at location pos.

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 function assumes that all strings consist of multibyte characters that conform to the ISO/IEC 10646-1 UTF-1 multibyte format. However, if Pg_TEXT_WIDECHAR is set, the function assumes each character is represented by 2 bytes that conform to the ISO/IEC 10646-1 UCS-2 double-byte format.


Note: PgDrawTextChars() assumes that len is the number of characters to draw. Using this number, PgDrawTextChars() determines the number of bytes required to store the string.

In order to: You can:
Define the color of the text Use PgSetTextColor() or PgSetTextDither()
Mask the text Use PgSetTextTransPat()
Fill the extent of the text Set the background color with PgSetFillColor() or PgSetFillDither() and specify the Pg_BACK_FILL flag to PgDrawText() or PgDrawTextmx()
Underline the text Use PgSetUnderline()

By default, the text is left-aligned (Pg_TEXT_LEFT), and the text is drawn with pos->y as its baseline. You can set flags to 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_LEFT
Left align text to pos (text is drawn to the right).
Pg_TEXT_RIGHT
Right align text to pos (text is drawn to the left).
Pg_TEXT_CENTER
Center text horizontally on pos.
Pg_TEXT_TOP
Top align text to pos (text is drawn below).
Pg_TEXT_BOTTOM
Bottom align text to pos (text is drawn above).
Pg_TEXT_MIDDLE
Center text vertically on pos.

Note: If you call the "mx" forms of these functions, the data isn't physically copied into the draw buffer. Instead, a pointer to the string is stored until the draw buffer is flushed. Make sure you call PgFlush() before you modify the text.

Returns:

0
Success.
-1
The draw buffer is too small to hold the current draw state, the draw command and the data. Increase the size of the draw buffer, or decrease the size of the string.

Examples:

The following example:

DrawSimpleText() {
    char *s = "Hello World!";
    PhPoint_t p = { 8, 30 };

    PgSetFont( "helv18" );
    PgSetTextColor( Pg_WHITE );
    PgDrawText( s, strlen( s ), &p, 0 );
}

will draw:

PgDrawText

The following example:

DrawBackFillText() {
    char *s = "Hello World!";
    PhPoint_t p = { 8, 30 };

    PgSetFont( "helv18" );
    PgSetTextColor( Pg_WHITE );
    PgSetFillColor( Pg_PURPLE );
    PgDrawText( s, strlen( s ), &p, Pg_BACK_FILL );
}

will draw:

PgDrawText

The following example:

DrawUnderlineText() {
    char *s = "Hello World!";
    PhPoint_t p = { 8, 30 };

    PgSetFont( "helv18" );
    PgSetTextColor( Pg_WHITE );
    PgSetUnderline( Pg_RED, Pg_TRANSPARENT, 0 );
    PgDrawText( s, strlen( s ), &p, 0 );
    PgSetUnderline( Pg_TRANSPARENT, Pg_TRANSPARENT, 0 );
}

will draw:

PgDrawText

The following example:

DrawBackFillUnderlineText() {
    char *s = "Hello World!";
    PhPoint_t p = { 8, 30 };

    PgSetFont( "helv18" );
    PgSetTextColor( Pg_WHITE );
    PgSetFillColor( Pg_PURPLE );
    PgSetUnderline( Pg_RED, Pg_TRANSPARENT, 0 );
    PgDrawText( s, strlen( s ), &p, Pg_BACK_FILL );
    PgSetUnderline( Pg_TRANSPARENT, Pg_TRANSPARENT, 0 );
}

will draw:

PgDrawText

Classification:

Photon

Safety:
Interrupt handler No
Signal handler No
Thread No

See also:

PgDrawString(), PgFlush(), PgSetFillColor(), PgSetFillDither(), PgSetFillTransPat(), PgSetFont(), PgSetTextColor(), PgSetTextDither(), PgSetTextTransPat(), PgSetUnderline()


[Previous] [Contents] [Index] [Next]