Name

---

      CATCOLORS

Purpose

---

      This object is similar to, and a replacement for, the COLORTOOL object. It is a
      fundamental object that can be associated with other objects in the Catalyst System
      that require a way to manage their colors. I wrote this object because I was unhappy
      with the way the COLORTOOL object worked in certain circumstances. This was mostly due,
      I think, to when the COLORTOOL object was written. At that time, we had to worry more
      about expressing colors correctly on 8-bit and 24-bit displays. This problem (except
      for PostScript output) has largely disappeared. This new CATCOLORS object is more in
      line with the way I do things now, although it does inherit much of the code written
      for COLORTOOL.

Author

---

      FANNING SOFTWARE CONSULTING BURRIDGE COMPUTING
      1645 Sheely Drive 18 The Green South
      Fort Collins, CO 80526 USA Warborough, Oxon, OX10 7DN England
      Phone: 970-221-0438 Phone: +44 (0) 1865 858 279
      E-mail: davidf@dfanning.com davidb@burridgecomputing.co.uk

Superclasses

---

      CATATOM
      CATCONTAINER
      IDL_CONTAINER

Syntax

---

      colorObject = Obj_New('CATCOLORS')

Arguments

---

Keywords

---

      BREWER: Set this keyword to load the Brewer color tables.
                    This program will look first in the $IDL_DIR/resource/colors directory for
                    the color table file, and failing to find it there will look for the file in
                    directories that are on the IDL path. (Necessarily, the directory which holds
                    the file will be required to have a .pro file in it.) Note that if you want
                    to use the BREWER color tables in a program written for the IDL Virtual Machine
                    or a runtime license, the BREWER color table file will have to be in the same
                    directory as the IDL save file or (better) in the $IDL_DIR/resource/colors directory.
                    http://www.dfanning.com/programs/fsc_brewer.tbl
      COLORFILE: The fully qualified file name of the file containing color tables. By default,
                    colorFile = Filepath(SubDirectory=['resource','colors'], 'colors1.tbl')
      COLORPALETTE: An 256-by-3 byte array containing a color palette to load into the object.
                    Loading a color palette does NOT send a COLORTOOL_TABLECHANGE message.
      INDEX: The index number of the color table to load. By default, 0.
      NCOLORS: The number of colors in the color palette that can be changed with the LOADCT
                    or XCOLORS methods. These colors are always loaded from the bottom of the color
                    palette and start at index 0. By default, 256.

Class Structure

---

    class = { CATCOLORS, $
              INHERITS CATATOM, $ ; Inherits the CATATOM object class.
              _brewer: 0B, $ ; Flag that indicates a brewer color table.
              _r: BytArr(256), $ ; The red color table vector.
              _g: BytArr(256), $ ; The green color table vector.
              _b: BytArr(256), $ ; The blue color table vector.
              _colornames: Ptr_New(), $ ; The names of "known" colors.
              _rvalue: Ptr_New(), $ ; The red color values associated with color names.
              _gvalue: Ptr_New(), $ ; The red color values associated with color names.
              _bvalue: Ptr_New(), $ ; The red color values associated with color names.
              _colorfile: "", $ ; The name of the color table file to read.
              _ncolors: 0L, $ ; The number of colors allowed to change in color table.
              _cindex: 0L, $ ; The current color table index.
              _xcTLB: Obj_New(), $ ; The XCOLORS tlb object.
              _xc_registerName: "", $ ; The name with which the XCOLORS dialog is registered.
              _r_old: BytArr(256), $ ; The old red color table vector.
              _g_old: BytArr(256), $ ; The old green color table vector.
              _b_old: BytArr(256) $ ; The old blue color table vector.
            }

Messages

---

      COLORTOOL_TABLECHANGE: A message with this title is sent when color table vectors are
                              changed in the object. In additon to the message, a DATA keyword is
                              used to pass an anonymous structure containing the current R, G, and
                              B color table vectors, along with the BOTTOM index for loading the vectors.
      COLORTOOL_SETPROPERTY: A message with this title is sent any time the SetProperty method is
                              called. No data is sent. Message recipients can call the GetPropery
                              method on the message SENDER to obtain appropriate information.

Modification History

---

      Written by: David W. Fanning, 17 October 2008, based on COLORTOOL.
      In looking for a Brewer color table file, I replaced all FILE_WHICH commands with
          FIND_RESOURCE_FILE commands. 28 April 2009. DWF.
      I added a check for a display connection before adding system colors to the colors
          the program knows about. This *should* make it possible to use the object in
          cron jobs. 6 October 2010. DWF.
        Completely removed references to "system" colors. Nothing but a pain in the
            backside! 17 October 2010. DWF.