Provided by: xcolorsel_1.1a-23build2_amd64 bug

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:

       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

       /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

       X(1), xcolormap(1), xfontsel(1), editres(1)

                                        27th December 1993                           Xcolorsel(1)