Text

Overview

This guide provides an overview of text entities and some of their associated commands. Text entities are used to display strings on screen.

How do I create text?

The command CreateText allows you to set up a text entity. Here are the available options:

CreateText ( id, string )
id = CreateText ( string )

void CreateText ( UINT id, uString string );
UINT CreateText ( uString string );

A text entity can be created by either assigning an ID number manually or having it provided to you automatically. The next step is to provide the initial string for your text entity. This could be a blank string or something like "hello". Please note that ID numbers are unique for a command set. Therefore it's feasible to have a text entity with an ID number of 1 and a sprite with an ID of 1.

Here's one approach to creating a text entity. The command CreateText is called, an ID number of 1 is specified and the initial text is set to "hello agk":

CreateText ( 1, "hello agk" )

agk::CreateText ( 1, "hello agk" );

This alternative method demonstrates how a text entity can be created with automatically assigned ID numbers:

text = CreateText ( "hello agk" )

text = agk::CreateText ( "hello agk" );

How can I position text on screen?

The main command for setting a sprite is called SetTextPosition. This command takes 3 parameters:

• ID
• X position
• Y position

The ID number refers to the ID of the text entity you want to position, while the X and Y positions will either refer to percentages or screen coordinates. If you have specified a virtual resolution then these parameters refer to screen coordinates. If no virtual resolution has been set these parameters are percentages.

This line of code positions the text entity at either 50 pixels on the X axis and 75 pixels on the Y axis, or 50% along the X axis and 75% along the Y axis:

CreateText ( 1, "hello agk" )
SetTextPosition ( 1, 50, 75 )

agk::CreateText ( 1, "hello agk" );
agk::SetTextPosition ( 1, 50, 75 );

How do I set the string of a text entity?

Call the command SetTextString. This command takes 2 parameters:

• ID
• string

The ID number refers to the ID of the text entity. The string parameter allows you to specify a new string for the text entity. This example shows the creation of a text entity, followed by an update to its string:

CreateText ( 1, "hello agk" )
SetTextString ( 1, "a brand new string" )

agk::CreateText ( 1, "hello agk" );
agk::SetTextString ( 1, "a brand new string" );

How do I set the size of text?

Use the command SetTextSize to alter the size of text. This command takes 2 parameters:

• ID
• size

The ID number refers to the ID of the text entity. The size parameter controls the final size of your text. By default this is set to 4. A smaller value will decrease the size of your text, while a larger value will increase it. In this example a text entity is created and then its size is set to a value of 10:

CreateText ( 1, "hello agk" )
SetTextSize ( 1, 10 )

agk::CreateText ( 1, "hello agk" );
agk::SetTextSize ( 1, 10 );

How do I set the color of text?

The command SetTextColor is used to control the color of text entities. Variations on this function also exist, they allow you to set the individual color, which may be useful in cases where it's only necessary to alter one component e.g. the alpha channel. Here's the available options:

• SetTextColor ( id, red, green, blue, alpha )
• SetTextColorRed ( id, red )
• SetTextColorGreen ( id, green )
• SetTextColorBlue ( id, blue )
• SetTextColorAlpha ( id, alpha )

The ID number refers to the ID of the text entity. The remaining parameters control the level of each color. Acceptable values are between 0 to 255. A value of 0 means no color in that channel, while 255 is full color. This example shows the creation of a text entity followed by its color being set to pure red:

CreateText ( 1, "hello agk" )
SetTextColor ( 1, 255, 0, 0, 255 )

agk::CreateText ( 1, "hello agk" );
agk::SetTextColor ( 1, 255, 0, 0, 255 );

How do I delete a text entity?

It may be necessary to delete previously loaded text entities and free up available memory. To delete a text entity call the command DeleteText:

DeleteText ( id )

void DeleteText ( UINT id );

This function only requires the ID number of the text you want to delete.

Here's an example of creating a text entity and then deleting it:

CreateText ( 1, "hello agk" )
DeleteText ( 1 )

agk::CreateText ( 1, "hello agk" );
agk::DeleteText ( 1 );