TICKIT_PEN...OLOUR_ATTR(3)

✨ TICKIT_PEN_GET_COLOUR_ATTR, TICKIT_PEN_SET_COLOUR_ATTR, TICKIT_PEN_SET_COLOUR_ATTR_DESC ✨

okay so bestie, this is a page from the Library Functions Manual — it's the tickit colour-pen-attribute situation and honestly? it's giving very niche, very powerful 💅

🌸 NAME 🌸

tickit_pen_get_colour_attr, tickit_pen_set_colour_attr, tickit_pen_set_colour_attr_desc — manipulate a colour pen attribute 🎀

🦋 SYNOPSIS 🦋

#include <tickit.h>

int tickit_pen_get_colour_attr(TickitPen *pen, TickitPenAttr attr);
void tickit_pen_set_colour_attr(TickitPen *pen, TickitPenAttr attr, int val);
bool tickit_pen_set_colour_attr_desc(TickitPen *pen, TickitPenAttr attr,
    const char *desc);

Link with -ltickit.

don't forget that link line, bestie, or the linker will simply not know you 🫶

💖 DESCRIPTION 💖

reading the colour: tickit_pen_get_colour_attr()

tickit_pen_get_colour_attr() hands you back the current value of whatever colour attribute you asked for on that pen, expressed as a palette index. and if that attribute is literally not defined? you get -1. not sorry about it. 🙈

writing the colour: tickit_pen_set_colour_attr()

tickit_pen_set_colour_attr() gives the given colour attribute on the pen a brand new value, again as a palette index. but here's the tea: if the pen was previously holding a secondary RGB8 value for this same attribute, that gets cleared. gone. bye. 😭 and it will invoke the TICKIT_EV_CHANGE event on the pen instance — the pen is literally announcing its own glow-up ✨

writing it from a string: tickit_pen_set_colour_attr_desc()

tickit_pen_set_colour_attr_desc() sets a new value for that colour attribute, but you feed it a textual description string and it converts it into a colour index for you. so thoughtful. it also invokes the TICKIT_EV_CHANGE event on the pen instance 💫

what does it recognise, you ask? okay so:

• decimal integers 👑
• the names of the first eight VGA colours — black, red, green, yellow, blue, magenta, cyan and white, in that exact order, respectively 🌈
• the prefix "hi-" stuck in front of any of those eight VGA colour names, which means you want the high-brightness versions living at colour indexes 8 to 15 🔥

if it recognises your string it returns a true value, and if it doesn't, it returns false. simple as that.

the RGB8 sequel (yes, there's more)

additionally — and this is the part that ate 💅 — the string may be followed by an RGB8 specification, formed from a hash symbol and 6 hexadecimal characters. if that's present, the secondary RGB8 value gets set too. and any optional space characters hanging out between the base colour name and the hash symbol? ignored. they simply don't exist to it. 🧚

for example,

tickit_pen_set_colour_attr_desc(pen, TICKIT_PEN_FG, "red #FF1515");

is equivalent to setting the basic red colour along with the secondary RGB8 value of { .r = 0xFF, .g = 0x15, .b = 0x15}.

like. two vibes in one call. obsessed. 🍓

⭐ RETURN VALUE ⭐

• tickit_pen_get_colour_attr() returns an integer value.
• tickit_pen_set_colour_attr() returns no value.
• tickit_pen_set_colour_attr_desc() returns a boolean indicating success.

no value means no value, bestie — don't be out here assigning it to anything 💀

🌈 SEE ALSO 🌈

tickit_pen_new(3), tickit_pen_has_attr(3), tickit_pen_set_bool_attr(3), tickit_pen_set_int_attr(3), tickit_pen_clear_attr(3), tickit_pen(7), tickit(7)

okay that's the whole page, and yes it's literally titled TICKIT_PEN...OLOUR_ATTR(3) and it comes straight out of the Library Functions Manual — so if you need the deep tickit lore, that's where you'll find it 🎀✨💜