The library is for creating and managing HUDs. I see two problems with HUDs/screen objects:
1. Screen objects are awkward to use. There are a lot of details that are hard to manage and its often hard to code things in such a way that it's organized and easy to work with.
2. HUD libraries tend to just do things for you. They're fine if that's exactly what you want to do, but generally aren't very customizable.
You might use screen objects to create a health meter but that's not something a library should do for you. There are tons of ways you might want a health meter to work. Instead of making a health meter for you, a library can provide easier ways to manage screen objects so that you can more easily create the type of health meter you need.
For example, here's a slightly simplified version of a demo from this library:
parent_type = /HudGroup
icon = 'health-bar-demo.dmi'
// add eight objects to this group
for(var/i = 1 to 8)
// the objects are placed in a row, 16 pixels apart, starting at 0,0
var/px = i * 16 - 16
var/py = 0
add(px, py, "health")
// updates the eight screen objects in the group to represent the new health value
for(var/i = 1 to 8)
// the objects list is the list of screen objects in this group
var/HudObject/h = objects[i]
if(i <= value)
h.icon_state = "health"
h.icon_state = "empty"
// all you have to do to use it:
player.health_meter = new(player)
The library provides you with the HudGroup object which has procs for creating screen objects (the add() proc), setting the position of all objects in the group, hiding/showing the group. The add() proc returns an instance of /HudObject, which is derived from /atom/movable so it *is* the actual screen object, but it also has some procs I added. The HudObject also has a proc to set its position.
The main focus here is eliminating annoying details. You don't have to compute, parse, or set screen_loc values. You don't have to set vars like icon, icon_state, and layer - most of those vars are inherited from the HudGroup. You don't have to add or remove objects from the client.screen list.
The library comes with three demos: a health bar, an action menu, and a flyout menu. These demonstrate most of the library's capabilities.
These demos are all much more complex than I like demos to be. Unfortunately, this can't really be avoided. The HUD needs to be controlled by you. If the library had more features that would simplify the health meter code example, the library would be implementing the health meter for you. There's just that much logic that goes into making a health meter that you have to write yourself.
Things I'd Like to Add
I'll add support for more events, currently it only supports the Click() proc. I didn't add support for other events because they weren't needed for the examples.
I'd like to be able to nest HudGroup objects. Currently you can only nest HudObjects inside of a HudGroup. Being able to group groups would let you manage more complex HUDs. For example, a player's health meter and mana meter might be separate groups, but are both placed inside the same parent group so they can both be managed easile.
I'd also like to add support for drawing text on the screen. My guess is that it'll be a single proc on the HudGroup object that creates a single screen object with text attached to it. I'm not sure how this will be handled internally. I don't know what's possible or what they best way is. I could use one screen object per letter of text, or I could make each letter an overlay.
I'd appreciate it if you'd let me know what you'd like to see in the library. I designed it based on how I'd want to implement the kinds of things I do need to implement, but I'm not sure what other people would use it for. If you have ideas, suggesting additional features or demos would be very much appreciated.