TextOut(x, y, text$[, table])
text$
at the position
specified by coordinates x
and y
. This function has the advantage that you
can use Hollywood's special constants as the coordinates (e.g. #CENTER
,
#BOTTOM
...) which is not possible with Print() because the Locate()
function does not handle them.
If layers are enabled, this command will add a new layer of the type
#TEXTOUT
to the layer stack.
Starting with Hollywood 2.5, you can use format tags in the string
you pass to TextOut()
. Using these tags you can control the font
style and color of your text on-the-fly. Format tags always
start and end with a square bracket ('['). In case you just
want to print a square bracket, you will have to use two square
brackets. If there is only one square bracket Hollywood will
always expect a format tag. See Format tags for details.
In Hollywood 4.0 the syntax of this function changed slightly. While the old syntax is still supported for compatibility, new scripts should use the new syntax which accepts a table as argument 4. The table can contain the following elements:
Align:
#LEFT
#RIGHT
#CENTER
#JUSTIFIED
The default value for Align
is #LEFT
.
WordWrap:
TextOut()
can do automatic word-wrapping for you if you specify
this additional parameter. You can use this parameter to specify
a maximum width for your text. TextOut()
will then use word
wrapping to make sure that no text runs beyond this limit. If
you do not set this argument or set it to 0 (which is also the
default), the text will be as wide as it is required. Starting
with Hollywood 9.1, you can also use soft hyphens or zero-width
space characters to customize word wrapping but since these are
Unicode characters, you need to make sure that you use UTF-8
encoding in that case.
Encoding:
text$
. This defaults to the text library default encoding
as set by SetDefaultEncoding()).
See SetDefaultEncoding for details. (V4.7)
Color:
TextOut()
will use the color value that was set using the
SetFontColor() command instead. (V5.0)
Pen:
#PALETTEMODE_PEN
, this tag can be used to
set the pen that should be used for drawing the text. If palette
mode is #PALETTEMODE_PEN
and Pen
is not specified, the pen set
using SetDrawPen() will be used instead. (V9.0)
Linespacing:
Charspacing:
Tabs:
TextOut()
. If
the string you pass to TextOut()
contains tabs and you don't
set this tag, all tabs will be converted to spaces. (V9.0)
ListMode:
True
to put TextOut()
into list mode. List mode
allows you to create ordered and unordered lists with TextOut()
.
When in list mode, you need to use tabs in the string you pass
to TextOut()
to signal the desired level of indentation. By default,
all list items will use the bullet specified in DefListBullet
. It
is also possible to tell TextOut()
to use custom bullets by setting
the ListBullet
tag. The same is true for the list's indentation,
offset and spacing where the default values can be set using DefListIndent
,
DefListOffset
and DefListSpacing
and custom values can be set using ListIndent
,
ListOffset
and ListSpacing
. Please see below for more details on all these
options. Also note that ListMode
and Tabs
are mutually exclusive.
You cannot use both at the same time. (V9.0)
DefListBullet:
TextOut()
is in list mode. This can be set to a Unicode character (passed
as its numeric codepoint, not as a string!) or one of the following
constants:
#BULLET_DASH:
#BULLET_CROSS:
#BULLET_CIRCLE:
#BULLET_HOLLOWCIRCLE:
#BULLET_BOX:
#BULLET_CHECKMARK:
#BULLET_ARROW:
#BULLET_DIAMOND:
#BULLET_NUMERIC:
#BULLET_NUMERICSINGLE:
#BULLET_NUMERICDOUBLE:
#BULLET_LALPHA:
#BULLET_LALPHASINGLE:
#BULLET_LALPHADOUBLE:
#BULLET_UALPHA:
#BULLET_UALPHASINGLE:
#BULLET_UALPHADOUBLE:
#BULLET_LROMAN:
#BULLET_LROMANSINGLE:
#BULLET_LROMANDOUBLE:
#BULLET_UROMAN:
#BULLET_UROMANSINGLE:
#BULLET_UROMANDOUBLE:
#BULLET_NONE:
If you need to use different types of bullets in your list, you need
to use the ListBullet
tag instead. See below for more information.
Also note that the starting offset of numbered bullet types like
#BULLET_NUMERIC
, #BULLET_LALPHA
, etc. can be set using the DefListOffset
and ListOffset
tags. See below for more information.
By default, bullets will use the color set using SetFontColor(). To set a different color, use the SetBulletColor() function. See SetBulletColor for details. (V9.0)
ListBullet:
TextOut()
will then extract a new bullet type from your table for each new list
it starts. Like DefListBullet
, the individual items in the table you pass to
ListItems
can be either numeric Unicode codepoints or predefined #BULLET_XXX
constants as described above. If there are more lists than table elements in
ListBullet
, the bullet specified in DefListBullet
will be used. (V9.0)
DefListIndent:
ListIndent
tag, see below for more details. (V9.0)
ListIndent:
TextOut()
will then extract a new indentation value from your table for each new list
it starts. If there are more lists than table elements in ListIndent
,
the default indentation specified in DefListIndent
will be used. (V9.0)
DefListOffset:
#BULLET_NUMERIC
or #BULLET_LALPHA
,
you can use this tag to specify a starting offset for the numbering. Note
that offsets are counted from 0. Thus, specifying an offset of 0 here,
will start numbering from 1 for #BULLET_NUMERIC
and from "a" for #BULLET_ALPHA
.
This tag defaults to 0. You can also specify custom offset levels for specific
lists. This can be done by using the ListOffset
tag, see below for more details. (V9.0)
ListOffset:
TextOut()
will then extract a new list offset value from your table for each new list
it starts. If there are more lists than table elements in ListOffset
,
the default list offset specified in DefListOffset
will be used. (V9.0)
DefListSpacing:
ListSpacing
tag, see below for more details.
(V9.1)
ListSpacing:
TextOut()
will then extract a new spacing value from your table for each new list
it starts. If there are more lists than table elements in ListSpacing
,
the default spacing value specified in DefListSpacing
will be used. (V9.1)
FrameMode:
TextOut()
in list mode and layers are enabled, the resulting layer of
type #TEXTOUT
will have multiple frames that you can cycle through using NextFrame()
or all other layer functions that support anim layers. This makes it possible to
cycle through the list items one by one or show one item after the other. The first
frame will always contain all list items. The content of the other frames will depend
on what was specified in the FrameMode
tag. This tag can be set to the following
constants:
#FRAMEMODE_SINGLE:
#FRAMEMODE_FULL:
If not specified, FrameMode
defaults to #FRAMEMODE_FULL
. Note that you can use
the Frame
tag (see below) to specify which frame should be initially visible. (V9.0)
Frame:
TextOut()
in list mode and layers are enabled, the resulting layer of
type #TEXTOUT
will have multiple frames that you can cycle through using NextFrame()
or all other layer functions that support anim layers. This makes it possible to
cycle through the list items one by one or show one item after the other. The first
frame will always contain all list items. The content of the other frames will depend
on what was specified in the FrameMode
tag (see above). The Frame
tag can be used
to specify the frame that should be initially visible. Frames are counted from 1. (V9.0)
SimpleList:
True
, TextOut()
won't successively extract the list bullet configuration
from the ListBullet
et al. tables but just statically use the item at the specified tab
index, i.e. tab position 1 will always use the bullet specified at index 1 in the ListBullet
table, tab position 2 will use the bullet specified at index 2 in the ListBullet
table and
so on. This will restrict your flexibility but can make things easier if you always want to
have the same configuration for each tab position. (V9.1)
Furthermore, the optional table argument can also contain one or more of the standard tags for all drawing commands. See Standard draw tags for details.
Note that Hollywood currently only supports standard left-to-right based text aligned on horizontal lines. Right to left and vertical text is currently not supported.
Note that when drawing to a palette-based target and the palette mode is set
to #PALETTEMODE_PEN
, this function will draw using the pen set via SetDrawPen()
instead of the color set via SetFontColor() or the Color
tag above.
TextOut(#CENTER, #CENTER, "Hello World!")The above code prints "Hello World!" in the center of your display.
For Local k = 100 To 600 Step 100 Do Line(k, 0, k, 480, #RED) TextOut(0, 0, "One\tTwo\tThree\tFour\tFive\tSix", {Tabs = {100, 200, 300, 400, 500}})This code shows how to use tabs with
TextOut()
.
SetFont(#SANS, 18) TextOut(0, 0, "Pizzas\n".. "\tProsciutto\n".. "\tFunghi\n".. "\tMargarita\n".. "Drinks\n".. "\tAlcoholic\n".. "\t\tBeer\n".. "\t\tWine\n".. "\tNon-alcoholic\n".. "\t\tCoke\n".. "\t\tWater", {ListMode = True, DefListBullet = #BULLET_CIRCLE, ListBullet = {#BULLET_DASH}})The code above shows how to create a list with
TextOut()
.