[nx, ny, textbounds] = DrawFormattedText
(win, tstring [, sx][, sy][, color][, wrapat][, flipHorizontal][, flipVertical][, vSpacing][, righttoleft][, winRect])
Draws a string of text 'tstring' into Psychtoolbox window 'win'. Allows
some basic formatting. The text string 'tstring' may contain newline
characters '\n'. Whenever a newline character '\n' is encountered, a
linefeed and carriage return is performed, breaking the text string into
lines. 'sx' defines the left border of the text: If it is
left out, text starts at x-position zero, otherwise it starts at the
specified position 'sx'. If sx=='center', then each line of text is
horizontally centered in the window. 'sy' defines the top border of the
text. If left out, it starts at the top of the window, otherwise it
starts at the specified vertical pixel position. If sy=='center', then
the whole text is vertically centered in the window. 'color' is the color
value of the text (color index or [r g b] triplet or [r g b a]
quadruple). If color is left out, the current text color from previous
text drawing commands is used. 'wrapat', if provided, will automatically
break text strings longer than 'wrapat' characters into newline separated
strings of roughly 'wrapat' characters. This is done by calling the
function (See 'help WrapString
'). 'wrapat' mode may not work
reliably with non-ASCII text strings, e.g., UTF-8 encoded uint8 strings
on all systems.
The optional flag 'flipHorizontal' if set to 1 will mirror the text
horizontally, whereas the optional flag 'flipVertical' if set to 1 will
mirror the text vertically (upside down).
The optional argument 'vSpacing' sets the spacing between the lines. Default
value is 1.
The optional argument 'righttoleft' if set to 1, will ask to draw the
text string in right-to-left reading direction, e.g., for scripts which
read right to left
The optional argument 'winRect' allows to specify a [left top right bottom]
rectange, in which the text should be centered/placed etc. By default,
the rectangle of the whole 'win'dow is used.
The function employs clipping by default. Text lines that are detected as
lying completely outside the 'win'dow or optional 'winRect' will not be
drawn, but clipped away. This allows to draw multi-page text (multiple
screen heights) without too much loss of drawing speed. If you find the
clipping to interfere with text layout of exotic texts/fonts at exotic
sizes and formatting, you can define the global variable...
... and set it like this ...
ptb_drawformattedtext_disableClipping = 1;
... to disable the clipping.
Clipping also gets disabled if you request the optional 3rd return
parameter 'textbounds' to ensure correct computation of a bounding box
that covers the complete text. You can enforce clipping by setting
ptb_drawformattedtext_disableClipping = -1; however, computed bounding
boxes will then only describe the currently visible (non-clipped) text.
The function returns the new (nx, ny) position of the text drawing cursor
and the bounding rectangle 'textbounds' of the drawn string. (nx,ny) can
be used as new start position for connecting further text strings to the
bottom of the drawn text string. Calculation of these bounds is
approximative, so it may give wrong results with some text fonts and
styles on some operating systems.
for a usage example.