Ubuntu Manpage: xcolorsel - display contents of rgb.txt files together with color probes.

Provided by: xcolorsel_1.1a-23build2_amd64

NAME

       xcolorsel - display contents of rgb.txt files together with color probes.

SYNOPSIS

       xcolorsel [options] [RgbTxtFile]

DESCRIPTION

       This  utility displays the contents of the rgb.txt file (usually found as /usr/lib/X11/rgb.txt) or a file
       with this format specified as the optional [RgbTxtFile] parameter. Each line of this file consists  of  3
       integers  (usually  0-255) representing the RGB values and a nickname for this color separated by spaces.
       The RGB values can be displayed in every color representation X11R5/6 supports. Also it  is  possible  to
       show the values in either resource definition or C-style.  An additional option to display the RGB values
       the  current  server would be able to actually display is also implemented. The main feature of Xcolorsel
       is that a small example tile of each color is also shown.  I will  describe  each  button/X11-control  in
       Xcolorsel's window in the next section.

       This  version has now also support for servers with read only colormaps (That is StaticColor, StaticGray,
       TrueColor). Actually I did not realize that this would be needed before 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.

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 action operate on colors selected in the display area and commands perform general
tasks.

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

Depending from 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 be the same, s.t. 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 a Dismiss button can be seen. Press this
button to dismiss the help window. If the window is to 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
see the Athena Widget Reference Manual. If the help window is dismissed the About me button is
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 given all these values.

The 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 yielding to a lower number of different colors on the server than
different colors are given in the input file where RGB values are usually 8 bit each.

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 are 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 pressed the left button the color 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 percentage of equality of the best match are given (if any). (Exception: If 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, s.t. 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 is 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 making it impossible to read
anything in the RgbText Widget.

Quit quits Xcolorsel and closes all its windows.

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 left button down over 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 given in the input file (see also comment in Grab color.

Note that conversion to TekHVC is slow for not trivially short input files.

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 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 next sub section.

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

Show real server values is again a toggle control. If enabled the server is queried which RGB values for
each color it is actually able to display. Then these values are displayed instead of the theoretic
values calculated by Xcolorsel and Xlib itself.

Note the 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 of 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, s.t. scrollbars, <Ctrl>-S
(searching) and selection work as usual. There is only one exception:

Double clicking with the left button does not select words separated by white space but here senseful
subparts. That is 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 would not 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.

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 is not 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

As a standard Xaw application Xcolorsel accepts all standard toolkit options (see X(1)).

Additional options for Xcolorsel that can also be set via Xresources (mentioned in parentheses) in the
application default file (or with general resource manager facilities) are:

-breakpercentage n (*.breakPercentage: n) sets the break percentage to n/100 (n integer). Colors with
equivalence equal to or above this value are found and displayed when grabbing colors. (see Grab
color above). This option defaults to 9500.

-busycursor cursor (*.busyCursor: cursor) allows you to specify the cursor shown while calculating color
conversions.

-color (*.customization: -color) sets the customization resource to force use of the Xcolorsel-color
application default file. If no application resource file can be found at all, the compiled in
Xcolorsel-color defaults are used.

-columns n (*.columns: n) sets the number of character columns initially displayed. This option usually
defaults to 30.

-cstyle (*.comma: True) lets Xcolorsel startup with C-Style selected.

-file filename (*.file: filename) sets the file to be read in and displayed. Default is usually
/usr/lib/X11/rgb.txt. You can specify the filename as command parameter without the prefixing
-file.

-grabcursor cursor (*.grabCursor: cursor) allows you to specify the cursor shown while grabbing colors.

-helpfile filename (*.helpfile: filename ) sets the path to the helpfile. (can also be done at compile
time in config.h). If set to the empty string ("", the default). Xcolorsel tries to locate the
file with 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 startup displaying in the specified color format. The default and
value chosen if set to an undefined string value is input.

-internal (*.realized: False) lets Xcolorsel startup showing the internal theoretic color values. This is
the default.

-maxred n (*.maxRed: n)

-maxgreen n (*.maxGreen: n)

-maxblue n (*.maxBlue: n) 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 in 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 file with more
(or less) than 8 bit for each RGB value. This options default to 0 but note the next option:

-maxintensity n (*.maxIntensity: n) is comparable to the last three options but is incorporated into each
of the color components. This value usually defaults to 255.

-maxrows n (*.maxRows: n) sets the maximum number of rows to be displayed at the same time. This
restriction is needed because this many color cells have to be allocated at the Xserver and the
number of colorcells is usually limited (usually to 256). If Xcolorsel can't allocate this much
colorcells a lower number is chosen and the user is informed via stderr. Only if not a single
color can be allocated Xcolorsel gives up. Xcolorsel instructs the window manager not to allow
resizes yielding to more lines getting 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, actually you have to use " to specify this in
resource files.

-realized (*.realized: True) lets Xcolorsel startup showing color values how they are displayed on the
server.

-resourcestyle (*.comma: False) lets Xcolorsel startup with C-Style deselected. This is the default.

-rows n (*.rows: n) sets the number of character rows initially displayed. This option usually defaults
to 10.

-tilewidth n (*.tilewidth: n) sets the width of the example color tiles measured in spaces. This option
usually defaults to 3.

HISTORY

       Xcolorsel  was  named  xpalette when I wrote it. However there were so many xpalettes that I was asked to
       change its name. Since xpalette is somehow comparable to xfontsel, that is it  shows  you  the  available
       colors and lets you select one, I call it xcolorsel now and hope that there will be no more confusion. So
       when  you  see  a xpalette.tgz, or xpalette-1.0.tar.gz, or xpalette-1.0a.tar.gz it is 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, resp. 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 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 of 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 grab of colors is slow. This is because the
Athena Widgets intercept ENTER/LEAVE notifications send to Xcolorsel during a pointer grab. As a
work around 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 is no need to, that is 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 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 Grab color 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 a like 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 to 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

This work and much more would not have been possible without the Linux project initiated by Linus
Torvalds (and of course all other people contributing their work to this project). This project together
with the GNU project made it possible for capable computer users of my generation to choose a free,
reliable and state of the art operating system and to get rid of the arbitrariness of commercial software
vendors and business people squeezing just money out of people that have to rely on them instead of
supplying working and useful software.

I have much experience with different home computer OS's and workstation UNIX implementations. You can
trust me. 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 go also to Nils Rennebarth who convinced me I should implement the colormap install feature during
color grabbing and made me develop a way to accomplish this 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 (but changed two of his patches that disabled grabbing of colors by accident ;-)
and Chris Olson (chris@Sterling.COM) for pointing me 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 me detailed debug sessions from their machines that approved the detected bug. Thanks to all
these as well.

Maybe I should have announced xcolorsel louder when it still was called xpalette. This 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 I strongly believe 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.

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:

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

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