/*******************************************************************************

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

 * All rights reserved. This program and the accompanying materials

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

 * which accompanies this distribution, and is available at

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

 *

 * Contributors:

 *     IBM Corporation - initial API and implementation

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

 *     Nokia Corporation - S60 implementation

 *******************************************************************************/

package org.eclipse.swt.graphics;

import org.eclipse.swt.*;

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

/**

 * Instances of this class manage the operating system resources that

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

 * specify the individual color components as integers in the range

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

 * <p>

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

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

 * when those instances are no longer required.

 * </p>

 *

 * @see RGB

 * @see Device#getSystemColor

 */

public final class Color

{

    /**

     * the handle to the OS color resource

     * (Warning: This field is platform dependent)

     */

    public int handle;

    /**

     * the device where this color was created

     */

    Device device;

    /**

     * Prevents uninitialized instances from being created outside the package.

     */

    Color()

    {

    }

    /**

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

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

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

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

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

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

     * the operating system color.

     * <p>

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

     * </p>

     *

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

     * @param red the amount of red in the color

     * @param green the amount of green in the color

     * @param blue the amount of blue in the color

     *

     * @exception IllegalArgumentException <ul>

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

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

     * </ul>

     *

     * @see #dispose

     */

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

    {

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

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

        init(device, red, green, blue);

    }

    /**

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

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

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

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

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

     * values of the operating system color.

     * <p>

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

     * </p>

     *

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

     * @param rgb the RGB values of the desired color

     *

     * @exception IllegalArgumentException <ul>

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

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

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

     * </ul>

     *

     * @see #dispose

     */

    public Color(Device device, RGB rgb)

    {

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

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

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

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

    }

    /**

     * Disposes of the operating system resources associated with

     * the color. Applications must dispose of all colors which

     * they allocate.

     */

    public void dispose()

    {

        if (handle == 0) return;

        if (device.isDisposed()) return;

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

        handle = 0;

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

        device = null;

    }

    /**

     * Compares the argument to the receiver, and returns true

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

     * specific comparison.

     *

     * @param object the object to compare with this object

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

     *

     * @see #hashCode

     */

    public boolean equals(Object object)

    {

        if (object == this) return true;

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

        Color color = (Color) object;

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

    }

    /**

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

     *

     * @return the blue component of the color

     *

     * @exception SWTException <ul>

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

     * </ul>

     */

    public int getBlue()

    {

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

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

    }

    /**

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

     *

     * @return the green component of the color

     *

     * @exception SWTException <ul>

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

     * </ul>

     */

    public int getGreen()

    {

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

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

    }

    /**

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

     *

     * @return the red component of the color

     *

     * @exception SWTException <ul>

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

     * </ul>

     */

    public int getRed()

    {

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

        return getRgbValue() & 0xFF;

    }

    /**

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

     *

     * @return the RGB for the color

     *

     * @exception SWTException <ul>

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

     * </ul>

     */

    public RGB getRGB()

    {

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

        int val = getRgbValue();

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

    }

    /**

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

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

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

     * method.

     *

     * @return the receiver's hash

     *

     * @see #equals

     */

    public int hashCode()

    {

        return getRgbValue();

    }

    /**

     * Allocates the operating system resources associated

     * with the receiver.

     *

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

     * @param red the amount of red in the color

     * @param green the amount of green in the color

     * @param blue the amount of blue in the color

     *

     * @exception IllegalArgumentException <ul>

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

     * </ul>

     *

     * @see #dispose

     */

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

    {

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

        {

            SWT.error(SWT.ERROR_INVALID_ARGUMENT);

        }

        this.device = device;

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

        try

        {

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

        }

        catch (Error e)

        {

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

            throw e;

        }

    }

    /**

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

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

     * <p>

     * This method gets the dispose state for the color.

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

     * invoke any other method using the color.

     *

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

     */

    public boolean isDisposed()

    {

        return handle == 0;

    }

    /**

     * Returns a string containing a concise, human-readable

     * description of the receiver.

     *

     * @return a string representation of the receiver

     */

    public String toString()

    {

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

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

    }

    private int getRgbValue()

    {

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

    }

    /**

     * Invokes platform specific functionality to allocate a new Color.

     * <p>

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

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

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

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

     * application code.

     * </p>

     *

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

     */

    public static Color internal_new(Device device, int handle)

    {

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

        Color color = new Color();

        color.handle = handle;

        color.device = device;

        return color;

    }

}