A quick guide to text_draw

Showing a text draw

Text draw's are very powerful in that they are really limited only by your imagination. That said they can be tricky to get right. If you’re a beginner to text draw's I recommend you first start with the basics. Create the text draw (you can define these anywhere in your script), show it and then build on it from there.

pawn Code:
new Text:txt;
txt = TextDrawCreate(10.0, 100.0, "Sample text draw under the chat box");
TextDrawUseBox(txt, 1);
TextDrawShowForPlayer(playerid, txt);

The text you show or pass to TextDrawCreate must not be an empty string. Also, don't forget that you will need to hide/destroy the text draw eventually for it to be removed from a players screen.

For example, the following code will show a server welcome text for new players that enter your server...

Add this to the top of your script:
pawn Code:
new Text:gTextDraw;

In the OnGameModeInit() callback add:
pawn Code:
gTextDraw = TextDrawCreate(10.0, 100.0, "Welcome to my server!");
TextDrawUseBox(gTextDraw, 1);

In the OnPlayerConnect(playerid) callback add:
pawn Code:
TextDrawShowForPlayer(playerid, gTextDraw);

In the OnPlayerRequestSpawn(playerid) callback add:
pawn Code:
TextDrawHideForPlayer(playerid, gTextDraw);

Your now well on your way to mastering text draw's. With practice creating something like this is easy:

Changing the text of a text draw

In SA:MP 0.2.2 we were blessed with the native "TextDrawSetString(Text:text, string[]);". Reference the Text variable and pass a new string to update a text draw's text (all existing text draw properties are kept).

Checking if a text draw is valid

You may have noticed there is a invalid text draw define:
pawn Code:

However you cannot simply compare a text draw against this define to determine if its valid.

For example, the following will give a tag mismatch warning at compile time:
pawn Code:
new Text:gTextDraw;
if(gTextDraw == INVALID_TEXT_DRAW) {
// blah, do code here

To get arround the tag mismatch, you have two options.
pawn Code:
new Text:gTextDraw;
if(_:gTextDraw == INVALID_TEXT_DRAW) { // _: removes the tag from gTextDraw
// blah, do code here
or ...
pawn Code:
new Text:gTextDraw;
if(gTextDraw == Text:INVALID_TEXT_DRAW) { // adds the "Text" tag to INVALID_TEXT_DRAW
// blah, do code here

I prefer the first method, however if you like the second method its probably easier to just redefine INVALID_TEXT_DRAW in your gamemode. To do this, add this to the top of your gamemode:
pawn Code:

Text draw native fuctions explained

native Text:TextDrawCreate(Float:x, Float:y, text[]);
Use: Creates a text draw area in memory (does not display to the screen).
Notes: The x,y coordinate is the top left coordinate for the text draw area based on a 640x480 "canvas" (irrespective of screen resolution). If you plan on using TextDrawAlignment with alignment 3 (right), the x,y coordinate is the top right coordinate for the text draw. Do not pass an empty string to this function (eg. where text = ""). In 0.2.2 the max text draw's you can create is 1024.

native TextDrawDestroy(Text:text);
Use: Destroys a text draw.
Notes: None.

native TextDrawLetterSize(Text:text, Float:x, Float:y);
Use: Sets the width and height of the letters.
Notes: Use with TextDrawSetProportional if you want even spacing.

native TextDrawTextSize(Text:text, Float:x, Float:y);
Use: When used with TextDrawUseBox it changes the size of the box.
Notes: When used with TextDrawAlignment of alignment 3 (right), the x and y are the coordinates of the left most corner of the box. For alignment 2 (center) the x and y values need to inverted (switch the two) and the x value is the overall width of the box. For all other alignments the x and y coordinates are for the right most corner of the box.

native TextDrawAlignment(Text:text, alignment);
Use: Aligns the text in the draw area.
Notes: Alignments... left = 0 or 1 (perhaps one of these is justified), centre = 2 and right = 3.

native TextDrawColor(Text:text, color);
Use: Defines the text colour.
Notes: Color is in hexidecimal format.

native TextDrawUseBox(Text:text, use);
Use: Adds or removes a box (shadow area) behind the text.
Notes: Show a box with 'use' set to 1, or hide a box (if previously set) with 'use' set to 0.

native TextDrawBoxColor(Text:text, color);
Use: Adjusts the text box colour (only used if TextDrawUseBox 'use' parameter is 1).
Notes: The color opacity is set by the alpha intensity of colour (eg. color 0x000000FF has a solid black box opacity, whereas 0x000000AA has a semi-transparent black box opacity).

native TextDrawSetShadow(Text:text, size);
Use: Adds a black shadow to the lower right side of the text.
Notes: The shadow font matches the text font. The shadow can be cut by the box area if the size is set too big for the area.

native TextDrawSetOutline(Text:text, size);
Use: Adds a black outline to the text.
Notes: The size parameter defines the thickness of the outline. The outline colour cannot be changed unless TextDrawBackgroundColor is used.

native TextDrawBackgroundColor(Text:text, color);
Use: Adjusts the text draw area background colour.
Notes: If TextDrawSetOutline is used with size > 0, the outline colour will match the color used in TextDrawBackgroundColor. Changing the value of color seems to alter the color used in TextDrawColor.

native TextDrawFont(Text:text, font);
Use: Changes the text font.
Notes: There four font styles as shown below. A font value greater than 3 does not display, and anything greater then 16 crashes the client.

native TextDrawSetProportional(Text:text, set);
Use: Seems to scale the text spacing to a proportional ratio.
Notes: Useful when using TextDrawLetterSize to ensure the text has even character spacing.

native TextDrawShowForPlayer(playerid, Text:text);
Use: Shows a text draw for a specific player.
Notes: Text will remain on the players screen until TextDrawHideForPlayer, TextDrawHideForAll or TextDrawDestroy is used or if the gamemode is changed.

native TextDrawHideForPlayer(playerid, Text:text);
Use: Hides a text draw for a given player.
Notes: None.

native TextDrawShowForAll(Text:text);
Use: Shows a text draw for all players.
Notes: Text will remain on all players screens until TextDrawHideForPlayer, TextDrawHideForAll or TextDrawDestroy is used or if the gamemode is changed.

native TextDrawHideForAll(Text:text);
Use: Hides a text draw for all players.
Notes: None.

TextDrawSetString(Text:text, string[]);