1 /*******************************************************************************

     2  * Copyright (c) 2000, 2004 IBM Corporation and others.

     3  * All rights reserved. This program and the accompanying materials

     4  * are made available under the terms of the Eclipse Public License v1.0

     5  * which accompanies this distribution, and is available at

     6  * http://www.eclipse.org/legal/epl-v10.html

     7  *

     8  * Contributors:

     9  *     IBM Corporation - initial API and implementation

    10  *     Lynne Kues (IBM Corp) - modified to reflect eSWT API subset

    11  *     Nokia Corporation - S60 implementation

    12  *******************************************************************************/

    13 package org.eclipse.swt.graphics;

    14 

    15 import org.eclipse.swt.*;

    16 import org.eclipse.swt.internal.symbian.*;

    17 

    18 /**

    19  * Instances of this class manage the operating system resources that

    20  * implement SWT's RGB color model. To create a color you can either

    21  * specify the individual color components as integers in the range

    22  * 0 to 255 or provide an instance of an <code>RGB</code>.

    23  * <p>

    24  * Application code must explicitly invoke the <code>Color.dispose()</code>

    25  * method to release the operating system resources managed by each instance

    26  * when those instances are no longer required.

    27  * </p>

    28  *

    29  * @see RGB

    30  * @see Device#getSystemColor

    31  */

    32 

    33 public final class Color

    34 {

    35 

    36     /**

    37      * the handle to the OS color resource

    38      * (Warning: This field is platform dependent)

    39      */

    40     public int handle;

    41 

    42     /**

    43      * the device where this color was created

    44      */

    45     Device device;

    46 

    47     /**

    48      * Prevents uninitialized instances from being created outside the package.

    49      */

    50     Color()

    51     {

    52     }

    53 

    54     /**

    55      * Constructs a new instance of this class given a device and the

    56      * desired red, green and blue values expressed as ints in the range

    57      * 0 to 255 (where 0 is black and 255 is full brightness). On limited

    58      * color devices, the color instance created by this call may not have

    59      * the same RGB values as the ones specified by the arguments. The

    60      * RGB values on the returned instance will be the color values of

    61      * the operating system color.

    62      * <p>

    63      * You must dispose the color when it is no longer required.

    64      * </p>

    65      *

    66      * @param device the device on which to allocate the color

    67      * @param red the amount of red in the color

    68      * @param green the amount of green in the color

    69      * @param blue the amount of blue in the color

    70      *

    71      * @exception IllegalArgumentException <ul>

    72      *    <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li>

    73      *    <li>ERROR_INVALID_ARGUMENT - if the red, green or blue argument is not between 0 and 255</li>

    74      * </ul>

    75      *

    76      * @see #dispose

    77      */

    78     public Color(Device device, int red, int green, int blue)

    79     {

    80         if (device == null) device = Device.getDevice();

    81         if (device == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);

    82         init(device, red, green, blue);

    83     }

    84 

    85     /**

    86      * Constructs a new instance of this class given a device and an

    87      * <code>RGB</code> describing the desired red, green and blue values.

    88      * On limited color devices, the color instance created by this call

    89      * may not have the same RGB values as the ones specified by the

    90      * argument. The RGB values on the returned instance will be the color

    91      * values of the operating system color.

    92      * <p>

    93      * You must dispose the color when it is no longer required.

    94      * </p>

    95      *

    96      * @param device the device on which to allocate the color

    97      * @param rgb the RGB values of the desired color

    98      *

    99      * @exception IllegalArgumentException <ul>

   100      *    <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li>

   101      *    <li>ERROR_NULL_ARGUMENT - if the rgb argument is null</li>

   102      *    <li>ERROR_INVALID_ARGUMENT - if the red, green or blue components of the argument are not between 0 and 255</li>

   103      * </ul>

   104      *

   105      * @see #dispose

   106      */

   107     public Color(Device device, RGB rgb)

   108     {

   109         if (device == null) device = Device.getDevice();

   110         if (device == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);

   111         if (rgb == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);

   112         init(device, rgb.red, rgb.green, rgb.blue);

   113     }

   114 

   115     /**

   116      * Disposes of the operating system resources associated with

   117      * the color. Applications must dispose of all colors which

   118      * they allocate.

   119      */

   120     public void dispose()

   121     {

   122         if (handle == 0) return;

   123         if (device.isDisposed()) return;

   124         OS.Color_Dispose(this.device.handle, handle);

   125         handle = 0;

   126         if (device.tracking) device.dispose_Object(this);

   127         device = null;

   128     }

   129 

   130     /**

   131      * Compares the argument to the receiver, and returns true

   132      * if they represent the <em>same</em> object using a class

   133      * specific comparison.

   134      *

   135      * @param object the object to compare with this object

   136      * @return <code>true</code> if the object is the same as this object and <code>false</code> otherwise

   137      *

   138      * @see #hashCode

   139      */

   140     public boolean equals(Object object)

   141     {

   142         if (object == this) return true;

   143         if (!(object instanceof Color)) return false;

   144         Color color = (Color) object;

   145         return (device == color.device) && ((getRgbValue() & 0xFFFFFF) == (color.getRgbValue() & 0xFFFFFF));

   146     }

   147 

   148     /**

   149      * Returns the amount of blue in the color, from 0 to 255.

   150      *

   151      * @return the blue component of the color

   152      *

   153      * @exception SWTException <ul>

   154      *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>

   155      * </ul>

   156      */

   157     public int getBlue()

   158     {

   159         if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);

   160         return (getRgbValue() & 0xFF0000) >> 16;

   161     }

   162 

   163     /**

   164      * Returns the amount of green in the color, from 0 to 255.

   165      *

   166      * @return the green component of the color

   167      *

   168      * @exception SWTException <ul>

   169      *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>

   170      * </ul>

   171      */

   172     public int getGreen()

   173     {

   174         if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);

   175         return (getRgbValue() & 0xFF00) >> 8 ;

   176     }

   177 

   178     /**

   179      * Returns the amount of red in the color, from 0 to 255.

   180      *

   181      * @return the red component of the color

   182      *

   183      * @exception SWTException <ul>

   184      *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>

   185      * </ul>

   186      */

   187     public int getRed()

   188     {

   189         if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);

   190         return getRgbValue() & 0xFF;

   191     }

   192 

   193     /**

   194      * Returns an <code>RGB</code> representing the receiver.

   195      *

   196      * @return the RGB for the color

   197      *

   198      * @exception SWTException <ul>

   199      *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>

   200      * </ul>

   201      */

   202     public RGB getRGB()

   203     {

   204         if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);

   205         int val = getRgbValue();

   206         return new RGB(val & 0xFF, (val & 0xFF00) >> 8, (val & 0xFF0000) >> 16);

   207     }

   208 

   209     /**

   210      * Returns an integer hash code for the receiver. Any two

   211      * objects which return <code>true</code> when passed to

   212      * <code>equals</code> must return the same value for this

   213      * method.

   214      *

   215      * @return the receiver's hash

   216      *

   217      * @see #equals

   218      */

   219     public int hashCode()

   220     {

   221         return getRgbValue();

   222     }

   223 

   224     /**

   225      * Allocates the operating system resources associated

   226      * with the receiver.

   227      *

   228      * @param device the device on which to allocate the color

   229      * @param red the amount of red in the color

   230      * @param green the amount of green in the color

   231      * @param blue the amount of blue in the color

   232      *

   233      * @exception IllegalArgumentException <ul>

   234      *    <li>ERROR_INVALID_ARGUMENT - if the red, green or blue argument is not between 0 and 255</li>

   235      * </ul>

   236      *

   237      * @see #dispose

   238      */

   239     void init(Device device, int red, int green, int blue)

   240     {

   241         if (red > 255 || red < 0 || green > 255 || green < 0 || blue > 255 || blue < 0)

   242         {

   243             SWT.error(SWT.ERROR_INVALID_ARGUMENT);

   244         }

   245         this.device = device;

   246         handle = OS.Color_New(this.device.handle, red, green, blue);

   247         try

   248         {

   249             if (device.tracking) device.new_Object(this);

   250         }

   251         catch (Error e)

   252         {

   253             OS.Color_Dispose(this.device.handle, handle);

   254             throw e;

   255         }

   256     }

   257 

   258     /**

   259      * Returns <code>true</code> if the color has been disposed,

   260      * and <code>false</code> otherwise.

   261      * <p>

   262      * This method gets the dispose state for the color.

   263      * When a color has been disposed, it is an error to

   264      * invoke any other method using the color.

   265      *

   266      * @return <code>true</code> when the color is disposed and <code>false</code> otherwise

   267      */

   268     public boolean isDisposed()

   269     {

   270         return handle == 0;

   271     }

   272 

   273     /**

   274      * Returns a string containing a concise, human-readable

   275      * description of the receiver.

   276      *

   277      * @return a string representation of the receiver

   278      */

   279     public String toString()

   280     {

   281         if (isDisposed()) return "Color {*DISPOSED*}"; //$NON-NLS-1$

   282         return "Color {" + getRed() + ", " + getGreen() + ", " + getBlue() + "}"; //$NON-NLS-1$//$NON-NLS-2$ //$NON-NLS-3$ //$NON-NLS-4$

   283     }

   284 

   285     private int getRgbValue()

   286     {

   287         return OS.Color_RgbValue(device.handle, handle);

   288     }

   289 

   290 

   291 

   292     /**

   293      * Invokes platform specific functionality to allocate a new Color.

   294      * <p>

   295      * <b>IMPORTANT:</b> This method is <em>not</em> part of the public

   296      * API for <code>Color</code>. It is marked public only so that it

   297      * can be shared within the packages provided by SWT. It is not

   298      * available on all platforms, and should never be called from

   299      * application code.

   300      * </p>

   301      *

   302      * @param device the device on which to allocate the color

   303      * @param handle the handle for the font

   304      * @return a new font object containing the specified device and handle

   305      */

   306     public static Color internal_new(Device device, int handle)

   307     {

   308         if (device == null) device = Device.getDevice();

   309         Color color = new Color();

   310         color.handle = handle;

   311         color.device = device;

   312         return color;

   313     }

   314 

   315 

   316 }