Add text element API

Implements an API specifically for the purpose of manipulating text elements.

doc/Text.md

@@ -0,0 +1,28 @@
+# Text Elements
+The API for text HUD elements is based off of the main API, however, it makes things even easier when it comes to manipulating the text HUDs. The main reason why this sub-API makes things easier, is that it presents a table for each text element, suited with several functions to manipulate it without requiring that the identification of the element be provided each time you make a change.
+
+#### `list_text`
+__Usage:__ `hudlib.list_text(<player (userdata or string)>)`
+
+Lists all text elements attached to a player.
+
+#### `get_text`
+__Usage:__ `hudlib.get_text(<player (userdata or string)>, <hud name (string)>)`
+
+Returns a table containing all of the helpers which allow manipulation of the text element. Helpers can be called in this method: `hudlib.get_image(...).remove()` (see below for all available helpers).
+
+__Helpers:__
+- `remove()` - removes the text HUD element
+- `hide()` - hides the text
+- `show()` - shows the text (if it is hidden)
+- `set_pos(x, y)` - sets the position of the text
+- `set_scale(x, y)` - sets the scale of the text
+- `set_text(name)` - changes the text
+- `set_alignment(x, y)` - aligns text
+- `set_offset(x, y)` - sets positional offset of the text
+- `set_colour(colour)` or `set_color(color)` - sets the colour of the text (`colour` or `color` is "An integer containing the RGB value of the color used to draw the text. Specify 0xFFFFFF for white text, 0xFF0000 for red, and so on.")
+
+#### `add_text`
+__Usage:__ `hudlib.add_text(<player (userdata or string)>, <hud name (string)>, <definition (table)>)`
+
+Adds a text HUD element and returns the helper table described in the `get_text` documentation above. Automatically sets the type of the element. The text colour may be specified with either the `colour` or `color` attributes rather than the `number` attribute. See documentation for `add` in `HUD.md` for information on other custom attributes.

init.lua

@@ -37,3 +37,5 @@ dofile(modpath.."/hud.lua")
 
 -- Load Image API
 dofile(modpath.."/image.lua")
+-- Load Text API
+dofile(modpath.."/text.lua")

text.lua

@@ -0,0 +1,67 @@
+-- hudlib/text.lua
+
+-- [local function] Generate methods
+local function gen(name, hud_name)
+  local hud = {
+    remove = function()
+      hudlib.remove(name, hud_name)
+    end,
+    hide = function()
+      hudlib.hide(name, hud_name)
+    end,
+    show = function()
+      hudlib.show(name, hud_name)
+    end,
+    set_pos = function(x, y)
+      hudlib.change(name, hud_name, "position", {x = x, y = y})
+    end,
+    set_scale = function(x, y)
+      hudlib.change(name, hud_name, "scale", {x = x, y = y})
+    end,
+    set_text = function(str)
+      hudlib.change(name, hud_name, "text", str)
+    end,
+    set_alignment = function(x, y)
+      hudlib.change(name, hud_name, "alignment", {x = x or 0, y = y or 0})
+    end,
+    set_offset = function(x, y)
+      hudlib.change(name, hud_name, "offset", {x = x, y = y})
+    end,
+    set_colour = function(colour)
+      hudlib.change(name, hud_name, "number", colour)
+    end,
+  }
+
+  hud.set_color = hud.set_colour
+
+  return hud
+end
+
+-- [function] List text elements
+function hudlib.list_text(name)
+  local huds  = hudlib.list(name)
+  local elems = {}
+
+  for _, hud in pairs(huds) do
+    if hud.def.hud_elem_type == "text" then
+      elems[#elems + 1] = _
+    end
+  end
+
+  return elems
+end
+
+-- [function] Get text element
+function hudlib.get_text(name, hud_name)
+  return gen(name, hud_name)
+end
+
+-- [function] Add text element
+function hudlib.add_text(name, hud_name, def)
+  def.type   = "text"
+  def.number = def.colour or def.color or def.number
+
+  if hudlib.add(name, hud_name, def) then
+    return gen(name, hud_name)
+  end
+end