Name
TextOut -- draw text to screen
Synopsis
TextOut(x, y, text$[, table])
Function
This function outputs the text specified by 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:
Allows you to specify the text's alignment. The following alignments are currently supported:

#LEFT
Left alignment.

#RIGHT
Right alignment.

#CENTER
Center lines.

#JUSTIFIED
Lay out text in justified lines. (V7.0)

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:
This argument can be used to specify the character encoding inside text$. This defaults to the text library default encoding as set by SetDefaultEncoding()). See SetDefaultEncoding for details. (V4.7)

Color:
This tag allows you to specify the text color. The color must be provided as an ARGB value. If you do not specify this tag, TextOut() will use the color value that was set using the SetFontColor() command instead. (V5.0)

Pen:
When palette mode is #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:
This tag allows you to adjust the space between lines. You can set this to a positive or negative value. A positive value will increase the space between lines, a negative value will decrease it. (V9.0)

Charspacing:
Allows you to adjust the space between characters. You can set this to a positive or negative value. A positive value will increase the space between characters, a negative value will decrease it. (V10.0)

Tabs:
If you want to use tabs, you need to set this tag to a table containing the desired tab stops. Tab stops must be passed as pixel values relative to the x-position passed to 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:
Set this tag to 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:
Use this tag to set the default bullet to use when 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:
Dash bullet. This is the default.

#BULLET_CROSS:
Cross bullet.

#BULLET_CIRCLE:
Circle bullet.

#BULLET_HOLLOWCIRCLE:
Hollow circle bullet. (V9.1)

#BULLET_BOX:
Box bullet.

#BULLET_CHECKMARK:
Checkmark bullet.

#BULLET_ARROW:
Arrow bullet.

#BULLET_DIAMOND:
Diamond bullet.

#BULLET_NUMERIC:
Numbered list: 1. 2. 3...

#BULLET_NUMERICSINGLE:
Numbered list: 1) 2) 3)...

#BULLET_NUMERICDOUBLE:
Numbered list: (1) (2) (3)...

#BULLET_LALPHA:
Numbered list: a. b. c...

#BULLET_LALPHASINGLE:
Numbered list: a) b) c)...

#BULLET_LALPHADOUBLE:
Numbered list: (a) (b) (c)...

#BULLET_UALPHA:
Numbered list: A. B. C...

#BULLET_UALPHASINGLE:
Numbered list: A) B) C)...

#BULLET_UALPHADOUBLE:
Numbered list: (A) (B) (C)...

#BULLET_LROMAN:
Numbered list: i. ii. iii...

#BULLET_LROMANSINGLE:
Numbered list: i) ii) iii)...

#BULLET_LROMANDOUBLE:
Numbered list: (i) (ii) (iii)...

#BULLET_UROMAN:
Numbered list: I. II. III...

#BULLET_UROMANSINGLE:
Numbered list: I) II) III)...

#BULLET_UROMANDOUBLE:
Numbered list: (I) (II) (III)...

#BULLET_NONE:
No bullet.

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:
If you want to use different types of bullets in your list, you have to set this tag to a table that contains the individual bullets your list should use. 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:
This tag can be used to specify the number of spaces to use for indenting list items. The default indent is 4 which means that by default, list items will be indented using 4 spaces. You can also specify custom levels of indentation for specific lists. This can be done by using the ListIndent tag, see below for more details. (V9.0)

ListIndent:
If you want to use different levels of indentation in your list, you have to set this tag to a table that contains the individual indentations your list should use. 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:
When using a numbered bullet type like #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:
If you want to use different offset levels in your list, you have to set this tag to a table that contains the individual offsets your list should use. 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:
This tag can be used to specify the default spacing to be used between the items in the individual lists. This defaults to 0. You can also specify custom spacing values for specific lists. This can be done by using the ListSpacing tag, see below for more details. (V9.1)

ListSpacing:
If you want to use different levels of line spacings for your lists, you have to set this tag to a table that contains the individual spacing values your lists should use. 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:
When using 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:
When using this frame mode, only a single list item will be visible per frame, i.e. frame 2 will just contain the first list item, frame 3 will just contain the second list item and so on.

#FRAMEMODE_FULL:
When using this frame mode, all previous list items will always be visible as well. This means that frame 3 will contain the first and the second list item, frame 4 will contain the first three list items and so on.

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:
When using 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:
If this is set to 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.

Inputs
x
x position for the text
y
y position for the text
text$
string to output
table
optional: table containing additional configuration parameters (see above) (V4.0)
Example
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().

Show TOC