XcmsStoreColor(3)

✨ XcmsStoreColor — like, the whole manual page bestie ✨

okay so this is XcmsStoreColor(3) from the XLIB FUNCTIONS fam, and we're about to get into it. setting colors, storing colors, the whole vibe. buckle up 🎀

---

🌸 NAME 🌸

XcmsStoreColor, XcmsStoreColors — set colors. that's literally it. setting colors. iconic behavior tbh.

---

✨ SYNTAX ✨

Status XcmsStoreColor(Display *display, Colormap colormap, XcmsColor
       *color);

Status XcmsStoreColors(Display *display, Colormap colormap, XcmsColor
       *colors, unsigned ncolors, Bool *compression_flags_return);

---

💖 ARGUMENTS 💖

• display — specifies the connection to the X server. your link to the mothership, basically 🛸
• color — specifies the color cell and the color to store in it. and listen, the values you put into this XcmsColor structure stay unchanged when the function returns. no cap, it leaves your struct alone.
• colors — specifies the color specification array of XcmsColor structures, each one specifying a color cell and the color to store there. and again, the values in the array remain unchanged upon return. she respects your data 💅
• colormap — specifies the colormap. the map. of colors. you get it.
• compression_flags_return — returns an array of Boolean values showing compression status. if you hand her a non-NULL pointer, each element gets set to True if the corresponding color was compressed and False if it wasn't. and if compression status isn't useful to you? just pass NULL. she won't be offended 🫶
• ncolors — specifies how many XcmsColor structures live in the color-specification array. just a count. a cute little number.

---

🦋 DESCRIPTION 🦋

💜 XcmsStoreColor (the singular one)

so XcmsStoreColor takes the color you specified in the XcmsColor structure and converts it into RGB values. then it takes that RGB specification, drops it into an XColor structure (with all three flags — DoRed, DoGreen, and DoBlue — set, as they must be), and hands it to XStoreColor to change the color cell specified by the pixel member of the XcmsColor structure.

now here's the catch, bestie, and it's giving important:

• that pixel value must be a valid index for the specified colormap, and the color cell it points to must be a read/write cell.
• if the pixel value is not a valid index → BadValue error. periodt.
• if the color cell is unallocated or is allocated read-only → BadAccess error. 😭
• if the colormap is an installed map for its screen, the changes are visible immediately. instant gratification, we love to see it.

⚠️ okay so real talk: XStoreColor has no return value. none. so if XcmsStoreColor hands you back XcmsSuccess, all that actually means is that the conversion to RGB succeeded and the call to XStoreColor was made. that's it. to get the actual color that got stored, use XcmsQueryColor. and because of the screen's hardware limitations or gamut compression, the color that ends up in the colormap may not be identical to the color you specified. she tries her best but hardware is hardware 💀

XcmsStoreColor can generate BadAccess, BadColor, and BadValue errors.

🌈 XcmsStoreColors (the plural one, yes there are two)

XcmsStoreColors takes the colors in that array of XcmsColor structures, converts them all to RGB values, and then uses those RGB specifications in XColor structures (three flags — DoRed, DoGreen, and DoBlue — set, obviously) in a call to XStoreColors to change the color cells specified by the pixel member of the corresponding XcmsColor structure.

the rules, again, because repetition is how we learn:

• each pixel value must be a valid index for the specified colormap, and the color cell each one points to must be a read/write cell.
• if a pixel value is not a valid index → BadValue error.
• if a color cell is unallocated or is allocated read-only → BadAccess error.
• if more than one pixel is in error? the one that gets reported is arbitrary. yeah, she picks. no promises on which one. 🙈
• if the colormap is an installed map for its screen, the changes are visible immediately.

⚠️ same deal as before: XStoreColors has no return value. so an XcmsSuccess from XcmsStoreColors just means the conversions to RGB succeeded and the call to XStoreColors was made. to obtain the actual colors stored, use XcmsQueryColors. and again — hardware limitations or gamut compression means the colors stored in the colormap may not be identical to the ones you specified. it's giving "close enough" energy, and honestly? same.

XcmsStoreColors can generate BadAccess, BadColor, and BadValue errors.

---

🎀 DIAGNOSTICS 🎀

• BadAccess — a client attempted to free a color map entry that it did not already allocate. rude. not yours, don't touch. 💅
• BadAccess — a client attempted to store into a read-only color map entry. read-only means read-only bestie, it's right there in the name 😭
• BadColor — a value for a Colormap argument does not name a defined Colormap. that colormap? doesn't exist. she's not in the system. ghosted.
• BadValue — some numeric value falls outside the range of values accepted by the request. and unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. also, any argument defined as a set of alternatives can generate this error. basically: check your numbers, babe 🔥

---

👑 SEE ALSO 👑

• XcmsAllocColor(3)
• XcmsQueryColor(3)
• Xlib - C Language X Interface

like, go read those too, they're literally part of the lore 💖

---

okay that's the whole page and honestly? she ate. 🍓

sign-off time: this gorgeous little manual is from X Version 11, libX11 1.8.14, and it's dated as such — so if you're out here storing colors with some other version, check yourself before you wreck yourself. mwah 💋