include/pwlib/colour.h

   1 /*
   2  * colour.h
   3  *
   4  * Colour description.
   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.16  2001/05/22 12:49:32  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.15  1999/03/10 03:49:51  robertj
  35  * More documentation adjustments.
  36  *
  37  * Revision 1.14  1999/03/09 08:01:47  robertj
  38  * Changed comments for doc++ support (more to come).
  39  *
  40  * Revision 1.13  1999/02/16 08:08:45  robertj
  41  * MSVC 6.0 compatibility changes.
  42  *
  43  * Revision 1.12  1998/09/23 06:23:07  robertj
  44  * Added open source copyright license.
  45  *
  46  * Revision 1.11  1995/03/14 12:41:09  robertj
  47  * Updated documentation to use HTML codes.
  48  *
  49  * Revision 1.10  1995/01/27  11:05:33  robertj
  50  * Added description string.
  51  *
  52  * Revision 1.9  1994/11/29  10:13:08  robertj
  53  * Documentation.
  54  *
  55  * Revision 1.8  1994/11/19  00:05:00  robertj
  56  * Added clear standard colour.
  57  *
  58  * Revision 1.7  1994/10/23  03:51:57  robertj
  59  * Changed colours to have 8 bit components.
  60  *
  61  * Revision 1.6  1994/08/23  11:32:52  robertj
  62  * Oops
  63  *
  64  * Revision 1.5  1994/08/22  00:46:48  robertj
  65  * Added pragma fro GNU C++ compiler.
  66  *
  67  * Revision 1.4  1994/01/03  04:42:23  robertj
  68  * Mass changes to common container classes and interactors etc etc etc.
  69  *
  70  * Revision 1.3  1993/08/24  00:27:59  robertj
  71  * Added Grey standard colour.
  72  *
  73  * Revision 1.2  1993/07/14  12:49:16  robertj
  74  * Fixed RCS keywords.
  75  *
  76  */
  77
  78
  79 #define _PCOLOUR
  80
  81 #ifdef __GNUC__
  82 #pragma interface
  83 #endif
  84
  85
  86 /**A class representing a colour specification. This class provides
  87    encapsulation for a 4 component colour. These are the amount of Red, Green,
  88    Blue and transparency (Alpha).
  89
  90    This class allows for the representation of an arbitrary colour which may
  91    not be able to be realised on the particular drawing canvas. A descendent
  92    from this class called a \Ref{PRealColour} always represents a colour that
  93    actually can be displayed. For example, for a typical printer canvas the
  94    only two colours possible are Black and White.
  95
  96    It is up the application and its colour needs to determine if simply using
  97    the PColour or translating it to a PRealColour first is required.
  98
  99    Note that for target drawing systems that do not support the opaqueness to
 100    transparency as a continuous value, zero indicates transparent and non-zero
 101    indicates full opaque, ie solid colour with no background.
 102  */
 103 class PColour : public PObject
 104 {
 105   PCLASSINFO(PColour, PObject);
 106
 107   public:
 108    /**Codes for specification of standard, most common colours. These are the
 109        primaries plus some greys and the {\it Clear} or transparent colour.
 110      */
 111     enum StandardColours {
 112       /// Red=0,   Green=0,   Blue=0,   Alpha=255
 113       Black,
 114       /// Red=255, Green=0,   Blue=0,   Alpha=255
 115       Red,
 116       /// Red=0,   Green=255, Blue=0,   Alpha=255
 117       Green,
 118       /// Red=255, Green=255, Blue=0,   Alpha=255
 119       Yellow,
 120       /// Red=0,   Green=0,   Blue=255, Alpha=255
 121       Blue,
 122       /// Red=255, Green=0,   Blue=255, Alpha=255
 123       Magenta,
 124       /// Red=0,   Green=255, Blue=255, Alpha=255
 125       Cyan,
 126       /// Red=255, Green=255, Blue=255, Alpha=255
 127       White,
 128       /// Red=64,  Green=64,  Blue=64,  Alpha=255
 129       LightGrey,
 130       /// Red=128, Green=128, Blue=128, Alpha=255
 131       Grey,
 132       /// Red=192, Green=192, Blue=192, Alpha=255
 133       DarkGrey,
 134       /// Red=0,   Green=0,   Blue=0,   Alpha=0
 135       Clear,
 136       NumStandardColours
 137     };
 138
 139    /**Create a standard colour specification.
 140      */
 141     PColour(
 142       StandardColours col = Black   /// Standard colour code
 143     );
 144
 145     /** Create a colour of the specified RGB values and alpha channel. */
 146     PColour(
 147       BYTE r,   /// Red component
 148       BYTE g,   /// Green component
 149       BYTE b,   /// Blue component
 150       BYTE a = 0xff /// Opaqueness, 0=fully transparent, 255=fully opaque
 151     );
 152
 153    /**Create a colour from a description string. The description string
 154        simply contains the four colour components separated by commas or
 155        spaces. The order of the components is red, green, blue and opacity.
 156      */
 157     PColour(
 158       const PString & description   /// Standard colour description string.
 159     );
 160
 161
 162     /**@name Overrides from class PObject */
 163    /**Create a copy of the colour. It is the callers responsibility to delete
 164        an object created using this funtion.
 165
 166        @return
 167        a new PColour object with the same value.
 168      */
 169     virtual PObject * Clone() const;
 170
 171    /**Determine if the two colours are the same, ie have the save values for
 172        all of the components.
 173
 174        @return
 175        #EqualTo# if all componets equal, #GreaterThan#
 176        otherwise.
 177      */
 178     virtual Comparison Compare(
 179       const PObject & obj   /// PColour object to compare against
 180     ) const;
 181
 182    /**Default hash function for putting colours into dictionaries.
 183
 184        @return
 185        number from 0 to 50 based on the following expression:
 186 \begin{verbatim}
 187               ((Red ^ 0x55) + (Green ^ 0xaa) + (Blue ^ 0xc3))%51
 188 \end{verbatim}
 189      */
 190     virtual PINDEX HashFunction() const;
 191
 192
 193   /**@name New functions for class */
 194    /**Get the colour description string. This string defines the colour as a
 195        string for use in configuration files etc.
 196
 197        @return
 198        description string for colour.
 199      */
 200     PString GetDescription() const;
 201
 202     /** Set the red component of the colour specification. */
 203     virtual void SetRed(
 204       BYTE r  /// New value for the red component
 205     );
 206
 207    /**Get the red component of the colour specification.
 208
 209        @return
 210        value from 0 to 255 for the red component.
 211      */
 212     BYTE GetRed() const;
 213
 214     /** Set the green component of the colour specification. */
 215     virtual void SetGreen(
 216       BYTE g  /// New value for the green component
 217     );
 218
 219    /**Get the greeen component of the colour specification.
 220
 221        @return
 222        value from 0 to 255 for the green component.
 223      */
 224     BYTE GetGreen() const;
 225
 226     /** Set the blue component of the colour specification. */
 227     virtual void SetBlue(
 228       BYTE b  /// New value for the blue component
 229     );
 230
 231    /**Get the blue component of the colour specification.
 232
 233        @return
 234        value from 0 to 255 for the blue component.
 235      */
 236     BYTE GetBlue() const;
 237
 238     /** Set the alpha (opacity) component of the colour specification. */
 239     virtual void SetAlpha(
 240       BYTE a  /// New value for the opaqueness component
 241     );
 242
 243    /**Get the opaqueness component of the colour specification.
 244
 245        @return
 246        value from 0 to 255 for the opaqueness component.
 247      */
 248     BYTE GetAlpha() const;
 249
 250
 251     /** Component indexes for \Ref{operator[]} access method. */
 252     enum {
 253       /// Red
 254       RedComponent,
 255       /// Green
 256       GreenComponent,
 257       /// Blue
 258       BlueComponent,
 259       /// Transparency
 260       AlphaComponent,
 261       NumComponents
 262     };
 263
 264    /**Get the component specified by the index. The index may be of the
 265        following values: 0 for Red, 1 for Green, 2 for Blue, 3 for Alpha.
 266
 267        @return
 268        value from 0 to 255 for the component specified.
 269      */
 270     BYTE operator[](
 271       PINDEX component  /// Component index.
 272     ) const;
 273
 274
 275    /**Calculate a distance metric between the two colours in RGB colour space.
 276
 277        @return
 278        distance metric between the colours.
 279      */
 280     long GetDistance(
 281       const PColour & other  /// Colour to measure distance from.
 282     ) const;
 283
 284
 285   protected:
 286     /** Components of the colour */
 287     BYTE component[NumComponents];
 288
 289
 290 // Include platform dependent part of class
 291 #include <pwlib/colour.h>
 292 };
 293
 294
 295 // End Of File ///////////////////////////////////////////////////////////////