Provided by: allegro5-doc_5.2.3.0-1_all bug

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)