[REL] Text Utilities

Franc[e]sco · April 30, 2011

Text Utilities 1.0

I recently re-started messing around with lua and made this little library with handy text functions. I didn't upload this to the resource center because it's not a resource and it can't be used as a resource because it gets too messy with callback functions and other stuff. You have to put the source file into your resource.

I am currently accepting suggestions on more useful functions, so please post all your ideas!

--> Download <--

What is it?

Text Utilities is a library that simplifies MTA Text functions for the most common tasks.

How do I use it?

- Download it

- Put text_utilities.lua in your resource zip file

- Add this to meta.xml

<script src="text_utilities.lua" />

Things you must know before using it:

- The arguments between square brackets [ ] are OPTIONAL and you can omit them when calling the function. When omitted, optional arguments will assume their default value

- The functions outputTimedText and outputCountdown use named arguments because I like them with functions that have lots of arguments. Basically, to call a function you can just do function{arg1=value, anotherargument=anothervalue} and the argument order doesn't matter.

- This library is server-sided! You can only call its functions from the server-side (unless you use triggerServerEvent)

Function List:

outputTimedText

display, textitem outputTimedText{ player, timeout, text, [x=0.5, y=0.5, priority="high", r=255, g=255, b=255, a=255, size=3.0, alignX="center", alignY="center", shadow_alpha=100, callback=nil] }

Displays a text for a set amount of time for a player

Required Arguments:

- player: The player who will see the text

- timeout: Duration (in milliseconds) of the text. Must be over 50 ms

- text: Text string that will be displayed

Optional Arguments:

- x: A floating point number between 0.0 and 1.0 indicating how far across the screen the text should be shown, as a percentage of the width, from the left hand side.

- y: A floating point number between 0.0 and 1.0 indicating how far down the screen the text should be shown, as a percentage of the height, from the top.

- priority: How important it is that this text should be up to date on client's screens. Valid values are: "low", "medium", "high".

- r, g, b: Values between 0 and 255 indicating how red/green/blue the text should be.

- a: A value between 0 and 255 indicating how transparent the text should be, with 0 being fully transparent, and 255 being opaque.

- size: A floating point value indicating the scale of the text. The default is 1.0, which is around 12pt.

- alignX: A string representing the X-alignment of the text. ("left", "center", "right")

- alignY: A string representing the Y-alignment of the text. ("top", "center", "bottom")

- shadow_alpha: A value between 0 and 255 indicating how dark the drop shadow should be.

- callback: The function that will be called once the text runs out

Return Values:

- The text display

- The text item

Examples:

-- Example 1 
-- Command that lets the player display some text on his screen 
-- format: /showtext text timeout 
addCommandHandler("showtext", 
    function(source, cmdname, txt, delay) 
        outputTimedText{ 
            player = source, 
            text = txt, 
            timeout = tonumber(delay) 
        } 
    end 
) 
  
-- Example 2 
-- Using the callback function to freeze the player only until the text runs out 
-- Format: /freezeme milliseconds 
addCommandHandler("freezeme", 
    function(source, cmdname, delay) 
        setPedFrozen(source, true) 
        outputTimedText{ 
            player = source, 
            text = "You are frozen for " .. delay .. " milliseconds", 
            timeout = tonumber(delay), 
            callback = function () 
                setPedFrozen(source, false) 
            end 
        } 
    end 
)

destroyPlayerTimedText

destroyPlayerTimedText(player)

Makes a text disappear if it hasn't already ran out.

Required Arguments:

- player: the player who owns the text

Example:

-- Example 3 
-- Using destroyPlayerTimedText to avoid multiple overlapped text elements 
addCommandHandler("spam", 
    function(source) 
        local spamcount = 0 
        setTimer( 
            function () 
                destroyPlayerTimedText(source) 
                local display, text = outputTimedText{ 
                    player = source, 
                    timeout = 5000, 
                    text = "Spam" .. spamcount, 
                    g=0, b=0, 
                    y=0.2, 
                } 
                spamcount = spamcount+1 
            end  
        , 1000, 10) 
        -- We're spamming at 1000ms with a timeout of 5000ms. 
        -- Thanks to our destroyPlayerTimedText functions we can avoid 
        -- overlapped text even though the timeout is higher than the spam delay 
    end 
)

getPlayerCurrentText

getPlayerCurrentText(player)

Gets the text item of the text the specified player is seeing. If no text is displaying for the player, it returns nil

Required Arguments:

- player: the player who owns the text item

Return Value:

- The text item

getPlayerCurrentDisplay

getPlayerCurrentDisplay(player)

Gets the display of the text the specified player is seeing. If no text is displaying for the player, it returns nil

Required Arguments:

- player: the player who owns the text item

Return Value:

- The display

outputCountdown

outputCountdown{ player, [start_value=3, delay=1000, go_text="Go!", x=0.5, y=0.5, priority="high", r=255, g=255, b=255, a=255, size=3, alignX="center", alignY="center", shadow_alpha=100, callback=nil, freeze=true] }

Displays a countdown for the specified player.

Required Arguments:

- player: The player who will see the countdown.

Optional Arguments:

- start_value: The number from where it will start counting down. Must be over 1.

- delay: the delay (in milliseconds) at which it will count down

- go_text: The text that will be displayed once the countdown reaches zero