[Betamaster]

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.

eg.

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:

#define INVALID_TEXT_DRAW (0xFFFF)

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:

#undef INVALID_TEXT_DRAW
#define INVALID_TEXT_DRAW  Text:0xFFFF

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[]);
Use: Changes the text displayed by the text draw.
Notes: None.