bionic (3) al_draw_multiline_text.3alleg5.gz

NAME

       al_draw_multiline_text - Allegro 5 API

SYNOPSIS

              #include <allegro5/allegro_font.h>

              void al_draw_multiline_text(const ALLEGRO_FONT *font,
                   ALLEGRO_COLOR color, float x, float y, float max_width, float line_height,
                   int flags, const char *text)

DESCRIPTION

       Like  al_draw_text(3alleg5),  but  this  function supports drawing multiple lines of text.  It will break
       text in lines based on its contents and the max_width parameter.  The lines are then layed out vertically
       depending on the line_height parameter and drawn each as if al_draw_text(3alleg5) was called on them.

       A  newline  \n  in  the text will cause a "hard" line break after its occurrence in the string.  The text
       after a hard break is placed on a new line.  Carriage return \r is not supported, will not cause  a  line
       break, and will likely be drawn as a square or a space depending on the font.

       The  max_width  parameter  controls  the  maximum  desired width of the lines.  This function will try to
       introduce a "soft" line break after the longest possible series of words that will fit in max_length when
       drawn with the given font.  A "soft" line break can occur either on a space or tab (\t) character.

       However,  it  is possible that max_width is too small, or the words in text are too long to fit max_width
       when drawn with font.  In that case, the word that is too wide will simply be drawn completely on a  line
       by   itself.    If   you  don't  want  the  text  that  overflows  max_width  to  be  visible,  then  use
       al_set_clipping_rectangle(3alleg5) to clip it off and hide it.

       The lines text was split into will each  be  drawn  using  the  font,  x,  color  and  flags  parameters,
       vertically  starting  at  y and with a distance of line_height between them.  If line_height is zero (0),
       the value returned by calling al_get_font_line_height(3alleg5) on font will be used as a default instead.

       The flags ALLEGRO_ALIGN_LEFT, ALLEGRO_ALIGN_CENTRE, ALLEGRO_ALIGN_RIGHT and ALLEGRO_ALIGN_INTEGER will be
       honoured by this function.

       If  you want to calculate the size of what this function will draw without actually drawing it, or if you
       need a complex and/or custom layout, you can use al_do_multiline_text(3alleg5).

SINCE

       5.1.9

SEE ALSO

       al_do_multiline_text(3alleg5), al_draw_multiline_text(3alleg5), al_draw_multiline_textf(3alleg5)