Xcolorsel(1)

💖 Xcolorsel 💖

okay so bestie, welcome to the Xcolorsel User's Guide, section 1 of the manual. sit down, grab a strawberry 🍓, and let's get into it because this little utility is genuinely iconic and i need you to understand it.

---

✨ NAME ✨

xcolorsel — it shows you the contents of rgb.txt files, and it does it together with color probes. yes, the whole point is you get to see the actual color. no cap. 👑

---

🌈 SYNOPSIS 🌈

xcolorsel [options] [RgbTxtFile]

---

🦋 DESCRIPTION 🦋

so this utility right here? it displays the contents of the rgb.txt file — which you'll usually find sitting at /usr/lib/X11/rgb.txt — or honestly any file with this format that you pass in as the optional [RgbTxtFile] parameter. 💅

every single line of that file is made up of 3 integers (usually ranging from 0 to 255, that's the vibe) representing the RGB values, plus a nickname for the color, all separated by spaces. periodt.

the RGB values can be displayed in every color representation that X11R5/6 supports. and on top of that, you can also show the values in either resource definition or C-style. there's also an extra option to display the RGB values that the current server would actually be able to display. 🫶

but the main character feature of Xcolorsel? it's that a small example tile of each color is also shown. like, you SEE the color. that's the whole moment. and i'm gonna describe each button / X11-control in Xcolorsel's window in the next section.

this version also has support for servers with read only colormaps now — that's StaticColor, StaticGray, and TrueColor for you taking notes 📝. fr, i didn't even realize this would be needed until i got a TrueColor server myself. however 😭, since colors have to be allocated one by one in these modes, the startup time of xcolorsel has reduced dramatically. it's giving speed.

---

🌸 USAGE 🌸

Xcolorsel's window is divided into four main parts:

• (usually) two rows of command buttons.
• the RgbText Widget displaying the input file and (if needed) vertical and/or horizontal scrollbars.
• a message line displaying help messages, comments, or results of commands or actions.
• (usually) one row of action buttons. the main (or better, intended) difference between commands and actions is that actions operate on colors selected in the display area, and commands perform general tasks. iykyk.

the title bar of Xcolorsel's window should (if it's supported by the window manager) show the name of the current displayed file.

depending on the window size, the actual layout may differ. also the names of the buttons may differ (if, for example, a german application default file is used). however the position and order of the buttons and other elements should stay the same, so that you may rely on the order in which the controls are described in this file. 💯

---

🎀 Command Buttons (first row) 🎀

• About me — opens a new window displaying an ASCII-Version of this manual page. when this window is open, the About me is inactive. in the lower left edge of this window you'll see a Dismiss button — press it to dismiss the help window. if the window is too small to display the whole file, vertical and/or horizontal scrollbars are provided. the text is displayed in a standard Xaw AsciiText Widget. text selection and <Ctrl>-S (search) work as usual. for a full description of the capabilities of this Widget, go see the Athena Widget Reference Manual. if the help window is dismissed, the About me button gets reactivated. ✨
• Fileinfo — displays the number of entries in the input file. also the number of different RGB triples is displayed. furthermore the Xserver is queried to see how many different colors the current server will show if it's given all these values.

that last value will differ depending on the color depth of the colormaps on the server. Xfree86 Servers usually use 6 bit for each RGB value, which yields a lower number of different colors on the server than the number of different colors given in the input file — because in the input file, RGB values are usually 8 bit each. lowkey a glow-down, but that's just the math. 🙈

• Grab color. when you press this button, the cursor changes into a magnification glass with a transparent hole at its hot spot. move this hole over any colored pixel in any window you're interested in and press the left button. while the cursor is a magnifying glass, Xcolorsel takes over the whole mouse. Xcolorsel itself ensures that each window the cursor is in is displayed with its correct colormap. 💅

after you press the left button, the color you selected is searched in the input file. the color definition in the current display format is given in the message line. also the number of acceptable colors, exact matches, and the percentage of equality of the best match are given (if any).

Exception: if the display format is values from input file, each of the 16 bit RGB values is given like with 16 bit scaled rgb, but in decimal.

also, the line containing the best match found is selected in the RgbText Widget, and the text is scrolled so that the line can be seen. the Best match, Previous, and Next actions are appropriately activated.

the algorithm to compare colors is (too!) simple. two colors R1 G1 B1 and R2 G2 B2 are compared by calculating (R1-R2)*(R1-R2) + (G1-G2)*(G1-G2) + (B1-B2)*(B1-B2). the result is scaled to 0-100%, where 100% means equivalence and 0% is the difference between black and white (aka between (0,0,0) and (255,255,255)). it's ensured that even almost equal colors compare only up to 99.99%. 100% is only possible for exact equivalence. the value above which colors are acceptable equal can be changed and defaults to 95%. 🔥

grabbed colors are compared against the color values as they can be realized on the current server, not the theoretic values from the input file.

• Reverse — exchanges the text fore- and background color in the RgbText Widget. 🔄
• Default colors — returns the text fore- and background color in the RgbText Widget to the values at the start of Xcolorsel. this is (together with Reverse) useful to return to readable text after you changed to colors with the Set foreground and Set background actions to values that make it impossible to read anything in the RgbText Widget. 😭 we've all been there.
• Quit — quits Xcolorsel and closes all its windows. bye bestie 👋

---

🧚 Command Buttons (second row) 🧚

• Display format — displays a submenu that allows you to define the format in which color RGB values are displayed. (press and hold the left button down over the Display format button, and release the button over the desired format.)

the possible color values are the color formats that X11R5/6 supports. Values from input file displays the RGB values like they're given in the input file (see also the comment in Grab color).

note that conversion to TekHVC is slow for not-trivially-short input files. like, be patient bestie. 🐌

while the color conversion calculation takes place, the cursor in the xcolorsel windows (except scrollbars) is changed to a busy cursor, and all controls are inactive.

note the difference between scaled and truncated rgb formats: Scaled scales the internal 16 bit RGB integer values to 4/8/12 bits, whereas truncated means the most significant 4/8/12 bits. truncated RGB values are only supported for compatibility. their use in new programs is discouraged. 💀

• C-Style — this is a toggle control switching C support on/off. with C support, RGB values are separated with , instead of the / used in X-Windows resource definitions. also Hex-Numbers are given in the format that is needed in C source codes. together with the selection capabilities of the RgbText widget, this allows inclusion of color definitions in programs or Application Default Files. see the next sub section. 👀

this option is meaningless with the Values from input file display format.

• Show real server values — again a toggle control. if enabled, the server is queried for which RGB values for each color it's actually able to display. then these values are displayed instead of the theoretic values calculated by Xcolorsel and Xlib itself.

note that when searching/grabbing colors, Xcolorsel always compares with the color values like they would be used by the server, because the searched color is also only known by its actually realized values.

this option is meaningless with the Values from input file display format.

---

🍓 The RgbText Widget Display area 🍓

in this box, (part of) the input file is displayed. depending on the length and width of the displayed information, scrollbars are provided. each line consists of an example tile of the color, the defining color values in the selected output format, and the nickname of the color. 🌈

the RgbText Widget inherits all capabilities of the AsciiText Widget, so scrollbars, <Ctrl>-S (searching) and selection work as usual. there's only one exception:

• double clicking with the left button does not select words separated by white space, but here it selects senseful subparts. that means double clicking in the nickname selects the whole nickname, regardless of included whitespace. double clicking on the color definitions selects the whole color definition. if C-Style is selected, the color format prefix is not selected, because it wouldn't be useful to paste this into a C-source file. 💅

this is done to make cutting and pasting color definitions into source codes or Application Default Files as convenient as possible. it's giving convenience, it's giving thoughtfulness. 🫶

---

💜 The message line 💜

this line contains one-line messages informing you about the state and results of Xcolorsel's actions.

---

👑 Action buttons 👑

• Best match — selects and scrolls the display to the best match found during the last Grab color, if one was found and isn't currently selected.
• Previous — selects and scrolls the display to the previous (next better) match, if there is one.
• Next — selects and scrolls the display to the next (next worse) match, if there is one.
• Set foreground — sets the text foreground color in the display window to the color currently selected in it (actually the color defined in the line where the first selected character resides).
• Set background — sets the text background color in the display window to the color currently selected in it (actually the color defined in the line where the first selected character resides).

✨ OPTIONS ✨

okay so first things first: Xcolorsel is a standard Xaw application, which means it accepts all the standard toolkit options — just like it says in X(1). 💅

But wait, there's more! You can also set these extra Xcolorsel options via Xresources (we'll put the resource names in parentheses) in the application default file, or with general resource manager facilities. Here's the tea: ☕

• -breakpercentage n (*.breakPercentage: n) — sets the break percentage to n/100 (where n is an integer). Colors with equivalence equal to or above this value get found and displayed when you're grabbing colors (see the Grab color section above). This one defaults to 9500. 💯
• -busycursor cursor (*.busyCursor: cursor) — lets you pick the cursor that shows up while Xcolorsel is busy calculating color conversions. ⏳
• -color (*.customization: -color) — sets the customization resource to force use of the Xcolorsel-color application default file. And if no application resource file can be found at all, then the compiled-in Xcolorsel-color defaults are used instead. 🌈
• -columns n (*.columns: n) — sets how many character columns are displayed at startup. Usually defaults to 30. 📏
• -cstyle (*.comma: True) — lets Xcolorsel start up with C-Style already selected. ✨
• -file filename (*.file: filename) — sets the file to be read in and displayed. Default is usually /usr/lib/X11/rgb.txt. You can also just give the filename as a command parameter without the -file prefix. 📁
• -grabcursor cursor (*.grabCursor: cursor) — lets you specify the cursor shown while grabbing colors. 🎯
• -helpfile filename (*.helpfile: filename) — sets the path to the helpfile. (You can also do this at compile time in config.h.) If you set it to the empty string ("", which is the default), Xcolorsel tries to locate the file using standard X techniques. This usually leads to filenames like /usr/lib/X11/Xcolorsel.help or /usr/lib/X11/app-defaults/Xcolorsel.help. Just trust the make install created by imake — it should know where to put the file. However, people (read: vendor-specific X11 releases) had problems with this, so /usr/lib/X11/xcolorsel/Xcolorsel.help is now hardcoded in the Imakefile. 🙃
• -input, -rgb4, -rgb8, -rgb12, -rgb16, -rgbi, -ciexyz, -cieuvy, -ciexyy, -cielab, -cieluv, -tekhvc, -#4, -#8, -#12, and -#16 (*.displayFormat: format, where format is one of input, rgb4, rgb8 , rgb12, rgb16, rgbi , ciexyz, cieuvy, ciexyy , cielab, cieluv, tekhvc , #rgb, #rrggbb, #rrrgggbbb , or #rrrrggggbbbb) — lets Xcolorsel start up displaying in the specified color format. The default, and the value chosen if set to an undefined string value, is input. 🎨
• -internal (*.realized: False) — lets Xcolorsel start up showing the internal theoretic color values. This is the default. 🧠
• -maxred n (*.maxRed: n) — see the shared description below. 🔴
• -maxgreen n (*.maxGreen: n) — see the shared description below. 🟢
• -maxblue n (*.maxBlue: n) — see the shared description below. 🔵

So for those three: when reading in the input file, Xcolorsel calculates the maximum of each of the input RGB values and uses this as the maximum (white) value for this component. Each of these option values is incorporated into this calculation for the appropriate color component as if such a color would have been read from the input file. This is implemented to allow input files with more (or less) than 8 bits for each RGB value. These options default to 0 — but note the next option: 👀

• -maxintensity n (*.maxIntensity: n) — comparable to the last three options, but this one is incorporated into each of the color components. This value usually defaults to 255. 💡
• -maxrows n (*.maxRows: n) — sets the maximum number of rows displayed at the same time. This restriction exists because that many color cells have to be allocated on the Xserver, and the number of colorcells is usually limited (usually to 256). If Xcolorsel can't allocate that many colorcells, a lower number is chosen and the user is informed via stderr. Only if not a single color can be allocated does Xcolorsel give up. Xcolorsel instructs the window manager not to allow resizes that would yield more lines being displayed. If more lines are displayed in the display RgbText Widget area, the displayed color examples will be wrong. This option usually defaults to 30. 🚫
• -nocolor (*.customization: '') — sets the customization resource to force use of the non-color Xcolorsel application default file. If no application resource file can be found at all, the compiled-in non-color Xcolorsel defaults are used. BTW, you actually have to use " to specify this in resource files. 😅
• -realized (*.realized: True) — lets Xcolorsel start up showing color values how they are displayed on the server. 🖥️
• -resourcestyle (*.comma: False) — lets Xcolorsel start up with C-Style deselected. This is the default. 🚫
• -rows n (*.rows: n) — sets the number of character rows initially displayed. Usually defaults to 10. 📐
• -tilewidth n (*.tilewidth: n) — sets the width of the example color tiles, measured in spaces. Usually defaults to 3. 🎨

---

📜 HISTORY 📜

So back in the day, Xcolorsel was actually named xpalette when I wrote it. But there were so many xpalettes out there that I got asked to change the name. And since xpalette is somehow comparable to xfontsel — you know, it shows you the available colors and lets you select one — I call it xcolorsel now and hope there won't be any more confusion. So if you ever see a xpalette.tgz, or xpalette-1.0.tar.gz, or xpalette-1.0a.tar.gz, it's probably a previous version of xcolorsel. 💅

---

🧠 INTERNALS 🧠

Most of the functionality of Xcolorsel is defined in an RgbText Widget. This is a child of a TextWidget linking an RgbSrc and RgbSink Widget together, which are children of AsciiSrc and AsciiSink, respectively. Feel free to use these Widgets in your own programs. Most of Xcolorsel's resources are resources of these Widgets. Interested programmers should be able to find all the needed information about the programming interface of these Widgets in the corresponding .h files (RgbSink.h, RgbSinkP.h, RgbSrc.h, RgbSrcP.h, RgbText.h, RgbTextP.h). 📚

Anyway, I would love to hear if anyone finds a general purpose for any of those widgets. (I can't think of any ;-) ). 😭

If you want to know about the internal structure and names of the Widget tree, use editres(1), which is part of X11R5/6 and shows this information in a more convenient way than I could ever put in the manual page. 🌳

---

🚧 RESTRICTIONS/MISFEATURES 🚧

• Installing the colormaps of windows the cursor is in during a grab of colors is slow. This is because the Athena Widgets intercept ENTER/LEAVE notifications sent to Xcolorsel during a pointer grab. As a workaround, Xcolorsel asks for notification of all cursor motions during a pointer grab and explicitly queries the X-Window the pointer is in, thus causing ex(t/p)ensive server/client communication. 🐢
• Color conversion calculations are even performed when there's no need to — like when just the C-Style is toggled. This is really annoying when using the TekHVC display format. 😤
• When Display format, C-Style, or Show real server values are changed, the current selection is unselected and the display scrolls up to the first line. 🎢
• The Best match, Previous, and Next action buttons are not appropriately (de-)activated when the selection is either changed manually in the display with the mouse or automatically (see the above misfeature). 🤖
• The icons and cursors (especially the bigger magnifying glass) are extremely ugly. Suggestions for nice bitmaps are welcome. 🔍😭
• The color application default is even more ugly. It is an example of what not to do with Xcolorsel. Actually the intention was to classify operations with colors: negative commands like Quit in red, positive commands like Default colors in bright or not-that-bright (About me) green. Commands requiring user intervention bright yellow. Other commands in standard yellow. And the remaining toggles and actions in orange. However, the result just makes me puke. Suggestions for nice colors are also welcome. 🤢
• If the help window is displayed, About me should not be inactive but instead allow one to raise the window. 🪟
• The color compare formula (see the Grab color section above) is (at least) not very sophisticated. 🤷
• When showing the busy cursor during color conversions, the standard cursor is still shown when over scrollbars. This is because I didn't find a way to change the cursor over Athena scrollbars. Later I saw that one can of course hide all windows under an invisible input-only window that changes the cursor when it enters it. (I got this from Mumail, where unfortunately only part of the window is hidden under the invisible window.) 🖱️
• You will notice that my programming style changed while coding Xcolorsel, thus the look-alike of the sources is not as consistent as it should be. 🎨

---

🐛 BUGS 🐛

Under AIX (IBM RS/6000), at least when using 16 color monochrom monitors and the Motif window manager, searching the window tree sometimes finds windows with invalid colormaps and that are not drawable. There is a flag to not try to install colormaps during color grabbing. However, if you click on a window border Xcolorsel will crash. I assume that this is caused by mwm placing an invisible input-only window over the borders it draws. I did not find a way to make Xcolorsel smart enough to not fall in this trap. Even if Xcolorsel would see that this is an input-only window, there is no way to get the data it actually needs (colormap and pixelvalue at the location you are clicking on). Just do not click on Mwm borders. Or better, do not use Mwm at all. Motif is no free software. Boycott it! Fvwm is much better anyway. 💅

---

👑 AUTHOR 👑

Michael Weller Heiderhoefen 116b D 46049 Oberhausen Germany

reachable by means of Email as one of:

eowmob@exp-math.uni-essen.de eowmob@pollux.exp-math.uni-essen.de mat42b@aixrs1.hrz.uni-essen.de

Please note that I did this as an exercise to improve my understanding of the Athena Widgets and X. I consider this project as (almost) finished. The priority of this project is as low as possible for me. No further extensions are planned so far. However I will put in patches to support other systems (please make them controllable with #define's either out of config.h or provided by your imake) and bug fixes and redistribute them to ensure that only one consistent version floats through the net. 🫶

💖 ACKNOWLEDGEMENTS 💖

okay so bestie, none of this — literally none of it — would exist without the Linux project that Linus Torvalds started, plus obviously every single other human who threw their work into that pot. 🌈 That project, teaming up with the GNU project, is the whole reason a capable computer user of the author's generation could pick a free, reliable, state-of-the-art operating system and finally ditch the arbitrariness of commercial software vendors and business people who were just squeezing money out of people who had no choice but to rely on them, instead of actually shipping working, useful software. 💀 fr.

He's got much experience with different home computer OS's and workstation UNIX implementations, so trust him, okay? Just use linux and get rid of all your problems. (What a pity it runs only on PCs and not on higher performance workstations 😭)

Thanx also go to Nils Rennebarth, who convinced him he should implement the colormap install feature during color grabbing, and who made him develop a way to actually accomplish that in a fruitful discussion. 🫶

Even more thanx to R.K.Lloyd@csc.liv.ac.uk (no RL name known) for his patches that are needed to allow compilation under HP-UX — though two of his patches got changed because they disabled grabbing of colors by accident ;-) — and to Chris Olson (chris@Sterling.COM) for pointing him at the compilation problems on SUN's (but who would use a Sun? >;-> ).

Thanks and greetings go to Chris Rouch (chris@wg.estec.esa.nl). He was the first person that could provide a patch to make xcolorsel run on a Sun. Actually the patch had a bug as well, however it did show where to look at, so the problem could be solved in seconds. Many other people (far too many to list here) sent detailed debug sessions from their machines that approved the detected bug. Thanks to all these as well. 🙏

Maybe he should have announced xcolorsel louder back when it was still called xpalette. That way the long existing segmentation fault problem would have been found earlier. Many people searching for a bug on several machines are obviously more successful than a single one. ✨

Thus once again the power of the Internet community was shown. 👑

---

📜 COPYRIGHTS 📜

As he strongly believes in the usefulness of free software, this program is released under the GNU general public license:

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published be the Free Software Foundation; either version 2 of the License, or (at your opinion) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANBILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

(yeah the license text has a couple of iconic little typos in it — we are keeping them exactly as they are, no cap, do not touch 💅)

Part of the files are derived from the Template Widget of the Athena Widgets as published by the Massachusetts Institute of Technology. Actually these files do not contain any code by the M.I.T, but only variable declarations. Nevertheless these parts of these files are still distributed under the terms of the M.I.T copyright, which are here repeated:

Copyright Massachusetts Institute of Technology 1987, 1988 Permission to use, copy, modify, distribute, and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of M.I.T. not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. M.I.T. makes no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty. M.I.T. DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL M.I.T. BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

---

🗂️ FILES 🗂️

the little homes where everything lives, bestie:

• /usr/lib/X11/rgb.txt
• /usr/lib/X11/xcolorsel/Xcolorsel.help
• /usr/lib/X11/app-defaults/Xcolorsel
• /usr/lib/X11/app-defaults/Xcolorsel-color

---

👀 SEE ALSO 👀

go read these next, they're the friend group:

• X(1)
• xcolormap(1)
• xfontsel(1)
• editres(1)

---

and that's the whole page, babe! 🌸 this is Xcolorsel(1), dated 27th December 1993 — a certified vintage icon from the man page source, and honestly? it ate. 💅✨ go grab some colors, you've got this. 🦋💖