PgDrawMultiTextArea(), PgDrawMultiTextAreaCx()

Draw multiline text in an area

Synopsis:

int PgDrawMultiTextArea( char *text,
                         int len,
                         PhRect_t *canvas,
                         int text_flags,
                         int canvas_flags,
                         int linespacing );

int PgDrawMultiTextAreaCx( void *dc,
                           char *text,
                           int len,
                           PhRect_t *canvas,
                           int text_flags,
                           int canvas_flags,
                           int linespacing );

Arguments:

dc

PgDrawMultiTextAreaCx() only. A void pointer to any type of draw context. Examples of draw contexts are:

a PhDrawContext_t returned by PhDCCreate()
a PmMemoryContext_t returned by PmMemCreateMC()
a PpPrintContext_t returned by PpCreatePC()
a PdOffscreenContext_t returned by PdCreateOffscreenContext()

text

The multiline text string to be drawn.

len

The number of characters to draw. If this argument is 0, all the characters are drawn.

canvas

A pointer to a PhRect_t structure that defines the area into which the text is to be drawn.

text_flags

Flags that affect how the text is drawn within the text-extent rectangle:

Pg_TEXT_LEFT — left align the text.
Pg_TEXT_RIGHT — right align the text.
Pg_TEXT_CENTER — horizontally center the text.
Pg_BACK_FILL — backfill the text_extent rect with the currently set fill color.

canvas_flags

Flags that affect how the text-extent rectangle is aligned within the canvas:

Pg_TEXT_LEFT
Pg_TEXT_RIGHT
Pg_TEXT_CENTER — horizontally center the text-extent rectangle within the canvas.
Pg_TEXT_TOP
Pg_TEXT_BOTTOM
Pg_TEXT_MIDDLE — vertically center the text-extent rectangle within the canvas.

linespacing

The leading (spacing) between lines, in pixels. A positive linespacing has the obvious effect: increased spacing between lines, and a taller extent. A negative linespacing causes the function to compute an extent for overlapping lines. Larger negative line spacings make the extent decrease in height. The minimum height of the extent is the height of the current font.

Library:

ph

Description:

These functions draw multiline text within an area called a canvas, using the font specified by a previous call to PgSetFont().

These functions call PgExtentMultiText() to compute the extent of the text. Text can be aligned within the text-extent rectangle, and the text-extent rectangle itself can be aligned within the canvas.

Returns:

0: Success.
-1: An error occurred.

Examples:

#include <stdio.h>
#include <stdlib.h>
#include <Pt.h>

void MultiTextDraw( PtWidget_t *widget,
                    PhTile_t *damage )
{
    PhRect_t canvas;
    int r;
    char Helvetica14b[MAX_FONT_TAG];

    char s[100] = " clever \n is \n not he who wins \n \
but he who \n wins \n easily ";

    // Find the size of the canvas on which the text
    // will be drawn

    PtCalcCanvas(widget, &canvas);

    // Paint the canvas red

    PgSetFillColor( Pg_RED );
    PgDrawRect( &canvas, Pg_DRAW_FILL );

    // Set the fill color, text color, and font.

    PgSetFillColor( Pg_BLUE );
    PgSetTextColor( Pg_WHITE );

    if(PfGenerateFontName("Helvetica", PF_STYLE_BOLD, 14,
                          Helvetica14b) == NULL) {
        perror("Unable to find font");
    } else {
        PgSetFont( Helvetica14b );
    }

    // Draw multiline text. Note the text-extent and
    // canvas flags, and the linespacing.

    r = PgDrawMultiTextArea( s, 0, &canvas,
          Pg_TEXT_RIGHT|Pg_BACK_FILL,
          Pg_TEXT_CENTER|Pg_TEXT_MIDDLE, 10 );

    if ( r == -1 )
        fprintf( stderr, "\n Error." );
}

int main(int argc, char **argv)
{
    PtWidget_t *base;
    PtArg_t args[2];
    PhDim_t dim;

    // Initialize Photon and create a base window

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

    dim.w = 250; dim.h = 250;
    PtSetArg( &args[0], Pt_ARG_DIM, &dim, 0 );

    if ((base = PtCreateWidget(PtWindow, Pt_NO_PARENT,
                               1, args)) == NULL)
      PtExit(EXIT_FAILURE);

    // Create a raw widget parented to the base window

    PtSetArg( &args[1], Pt_ARG_RAW_DRAW_F,
              (long) MultiTextDraw, 0 );
    PtCreateWidget( PtRaw, base, 2, args );

    // Realize the base window. This will realize the
    // raw widget, which in turn will draw itself with
    // the MultiTextDraw() function above.

    PtRealizeWidget(base);

    PtMainLoop();
    return EXIT_SUCCESS;
}

This code produces the following output:

Example of PgDrawMultiTextArea()

Classification:

Photon

Safety:
Interrupt handler	No
Signal handler	No
Thread	No