include/pwlib/palette.h

   1 /*
   2  * palette.h
   3  *
   4  * Colour palette.
   5  *
   6  * Portable Windows Library
   7  *
   8  * Copyright (c) 1993-1998 Equivalence Pty. Ltd.
   9  *
  10  * The contents of this file are subject to the Mozilla Public License
  11  * Version 1.0 (the "License"); you may not use this file except in
  12  * compliance with the License. You may obtain a copy of the License at
  13  * http://www.mozilla.org/MPL/
  14  *
  15  * Software distributed under the License is distributed on an "AS IS"
  16  * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
  17  * the License for the specific language governing rights and limitations
  18  * under the License.
  19  *
  20  * The Original Code is Portable Windows Library.
  21  *
  22  * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
  23  *
  24  * Portions are Copyright (C) 1993 Free Software Foundation, Inc.
  25  * All Rights Reserved.
  26  *
  27  * Contributor(s): ______________________________________.
  28  *
  29  * $Log$
  30  * Revision 1.15  2001/05/22 12:49:33  robertj
  31  * Did some seriously wierd rewrite of platform headers to eliminate the
  32  *   stupid GNU compiler warning about braces not matching.
  33  *
  34  * Revision 1.14  1999/03/10 03:49:52  robertj
  35  * More documentation adjustments.
  36  *
  37  * Revision 1.13  1999/03/09 08:01:49  robertj
  38  * Changed comments for doc++ support (more to come).
  39  *
  40  * Revision 1.12  1998/09/23 06:24:33  robertj
  41  * Added open source copyright license.
  42  *
  43  * Revision 1.11  1995/03/14 12:41:56  robertj
  44  * Updated documentation to use HTML codes.
  45  *
  46  * Revision 1.10  1995/01/06  10:31:04  robertj
  47  * Documentation.
  48  *
  49  * Revision 1.9  1994/08/23  11:32:52  robertj
  50  * Oops
  51  *
  52  * Revision 1.8  1994/08/22  00:46:48  robertj
  53  * Added pragma fro GNU C++ compiler.
  54  *
  55  * Revision 1.7  1994/04/03  08:34:18  robertj
  56  * Added help and focus functionality.
  57  *
  58  * Revision 1.6  1994/01/03  04:42:23  robertj
  59  * Mass changes to common container classes and interactors etc etc etc.
  60  *
  61  * Revision 1.5  1993/12/31  06:45:38  robertj
  62  * Made inlines optional for debugging purposes.
  63  *
  64  * Revision 1.4  1993/08/27  18:17:47  robertj
  65  * CFront compatibility.
  66  *
  67  * Revision 1.3  1993/08/21  01:50:33  robertj
  68  * Made Clone() function optional, default will assert if called.
  69  *
  70  * Revision 1.2  1993/07/14  12:49:16  robertj
  71  * Fixed RCS keywords.
  72  *
  73  */
  74
  75
  76 #define _PPALETTE
  77
  78 #ifdef __GNUC__
  79 #pragma interface
  80 #endif
  81
  82
  83 /**A class representing a logical palette of colours.
  84
  85    A palette is a look up table for converting an index into a full RGB colour
  86    specification. A palette typically has a small number of colours eg 16 or
  87    256.
  88  */
  89 class PPalette : public PContainer
  90 {
  91   PCONTAINERINFO(PPalette, PContainer);
  92
  93   public:
  94     /** Create a new empty palette. */
  95     PPalette();
  96
  97
  98   /**@name Overrides from class PObject */
  99    /**Compare two palette objects for equality. The two instances must
 100        reference the same actual palette. Thay cannot be two palettes that
 101        happen to have the same colours in them.
 102
 103        @return
 104        #EqualTo# if the two objects reference to the same palette,
 105        otherwise #GreaterThan#.
 106      */
 107     virtual Comparison Compare(
 108       const PObject & obj   /// Another palette object to compare against.
 109     ) const;
 110
 111
 112   /**@name Overrides from class PContainer */
 113    /**Get the current size of the palette, ie the total number of colours
 114        added to this logical palette.
 115
 116        @return
 117        number of colours in palette.
 118      */
 119     virtual PINDEX GetSize() const;
 120
 121    /**Set the new size of the palette. If the size was increased, all colours
 122        created between the old last colour and the new will be set to black.
 123
 124        @return
 125        TRUE if the size was successfully changed. The value FALSE usually
 126        indicates failure due to insufficient memory.
 127      */
 128     virtual BOOL SetSize(
 129       PINDEX newSize    /// New size of the palette
 130     );
 131
 132
 133   /**@name New functions for class */
 134    /**Add a colour specification into the palette, if the colour already
 135        exists in the palette, no new entry is added. Otherwise a new entry is
 136        appended.
 137
 138        @return
 139        index for the colour added to the palette.
 140      */
 141     PINDEX AddColour(
 142       const PColour & colour    /// New colour to add to the palette.
 143     );
 144
 145    /**Remove from the palette the colour at the specified index or of the
 146        exact RGB value specified.
 147
 148        Note when a colour is removed any indexes to colours after the remove
 149        one will correspond to a different colour that before, ie all colours
 150        are moved up one entry in the palettes "array" of colours.
 151
 152        @return
 153        TRUE if the colour was in the palette and was removed.
 154      */
 155     BOOL RemoveColour(
 156       const PColour & colour    /// Colour to remove from the palette.
 157     );
 158     BOOL RemoveColour(
 159       PINDEX idx    /// Palette index to remove.
 160     );
 161
 162    /**Determine if the palette contains an exact match for the colour
 163
 164        @return
 165        TRUE if colour is in palette.
 166      */
 167     BOOL HasColour(
 168       const PColour & colour    /// Colour to search for in palette.
 169     ) const;
 170
 171    /**Locate the index in the palette of the nearest match to the specified
 172        colour that is in the palette.
 173
 174        Note that of there is more than one colour that is identical to the
 175        one being searched for, the particular matching index that is returned
 176        is not defined, it could be any one of them.
 177
 178        @return
 179        index of nearest colour in palette.
 180      */
 181     PINDEX GetIndex(
 182       const PColour & colour    /// Colour to serarch for in palette.
 183     ) const;
 184
 185    /**Get the colour specification for the specified index value.
 186
 187        @return
 188        colour at index in palette.
 189      */
 190     PColour GetColour(
 191       PINDEX indx   /// Index of colour in palette.
 192     ) const;
 193
 194    /**Set a colour specification into the palette at the specified index. If
 195        this is beyond the end of the palette the palette is expanded to
 196        accommodate the new index. All colours created between the old last
 197        colour and the new will be set to black.
 198
 199        @return
 200        TRUE if colour was successfully added to palette.
 201      */
 202     BOOL SetColour(
 203       PINDEX idx,             /// Index of colour in palette.
 204       const PColour & colour  /// New colour to set at index in palette.
 205     );
 206
 207
 208
 209
 210 // Include platform dependent part of class
 211 #include <pwlib/palette.h>
 212 };
 213
 214
 215 // End Of File ///////////////////////////////////////////////////////////////