/*
* Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of "Eclipse Public License v1.0"
* which accompanies this distribution, and is available
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description:  This class is a placeholder of utility methods.
*
*/



package com.nokia.mid.ui;

import javax.microedition.lcdui.Graphics;
import javax.microedition.lcdui.Image;
import javax.microedition.lcdui.Font;

/**
 *  This class is a placeholder of utility methods. It contains
 *  methods for converting standard lcdui classes to Nokia UI classes
 *  and vice versa, and method for creating Image out of ARGB pixel
 *  array, creating empty transparent or specific
 *  background colored images, creating mutable image from encoded
 *  image byte array.
 *
 *  @see javax.microedition.lcdui.Graphics
 *  @see com.nokia.mid.ui.DirectGraphics
 *  @see javax.microedition.lcdui.Canvas
 *  @see com.nokia.mid.ui.DirectCanvas
 *  @version 0.11
 *  @since 1.0
 */
public class DirectUtils
{

    private DirectUtils()
    {
    }

    /**
    * Converts standard javax.microedition.lcdui.Graphics to DirectGraphics. The
    * returned Graphics context is the same, e.g. calling draw operations
    * via original Graphics reference affect the DirectGraphics context
    * and vice versa. Note that eventhough the graphics context is the same
    * the returned object reference may or may not be the same as passed.
    * This means that purely casting Graphics (g) passed in paint of lcdui
    * Canvas to DirectGraphics may not work ok. The safe way is to always
    * do the conversion with this method.
    *
    * @return the DirectGraphics object based on Graphics
    * @param g Graphics object for which DirectGraphics should be returned
    * @since 1.0
    */

    public static DirectGraphics getDirectGraphics(Graphics aG)
    {
        return com.nokia.mid.ui.DirectGraphicsInvoker.getDirectGraphics(aG);
    }

    /**
     *  Creates a mutable image which is decoded from the data stored
     *  in the specified byte array at the specified offset and length.
     *  The data must be in a self-identifying image file format
     *  supported by the implementation, such as PNG.
     *  <p>
     *  Note that the semantics of this method are exactly the same
     *  as
     *  {@link javax.microedition.lcdui.Image#createImage(byte[],int,int)}
     *  except that the returned image is mutable.
     *
     *  @param imageData the array of image data in a supported image format
     *  @param imageOffset the offset of the start of the data in the array
     *  @param imageLength the length of the data in the array
     *  @return the created mutable image
     *  @throws ArrayIndexOutOfBoundsException if imageOffset and
     *  imageLength specify an invalid range
     *  @throws NullPointerException if imageData is null
     *  @throws IllegalArgumentException if imageData is incorrectly
     *  formatted or otherwise cannot be decoded
     *  @see javax.microedition.lcdui.Image#createImage(byte[],int,int)
     *  @since 1.0
     */
    public static Image createImage(byte[] aImageData, int aImageOffset,
                                    int aImageLength)
    {
        Image source = Image.createImage(aImageData, aImageOffset, aImageLength);
        Image copy = Image.createImage(source.getWidth(), source.getHeight());
        DirectGraphics dg = getDirectGraphics(copy.getGraphics());
        DirectGraphicsInvoker.setColorValues(dg, 0x00FFFFFF, copy);
        dg.drawImage(source, 0, 0, 0, 0);
        return copy;
    }

    /**
     * <p>
     * The method will return a newly created mutable Image with specified
     * dimension with all pixels of an image of defined ARGB color. The color
     * can contain alpha channel transparency information.
     * </p>
     *
     * @param width the width of the new image, in pixels
     * @param height the height of the new image, in pixels
     * @return the created image
     * @throws IllegalArgumentException if either width or height is
     * zero or less
     * @since 1.0
     */
    public static Image createImage(int aWidth, int aHeight, int aColor)
    {
        Image result = Image.createImage(aWidth, aHeight);
        DirectGraphics dg = getDirectGraphics(result.getGraphics());
        DirectGraphicsInvoker.setColorValues(dg, aColor, result);
        return result;
    }

    /**
     * <p>
     * The method returns new instance of {@link javax.microedition.lcdui.Font}
     * with custom font height. System provides a font that matches
     * the requested attributes as closely as possible.
     * </p>
     * <p>
     * Font created in this way can be used only for Graphics instance
     * (Canvas, CustomItem, Image). This font is not supported
     * for high-level UI components (ChoiceGroup, StringItem and List).
     * If font with custom height is set to some high-level component, it's
     * replaced by default font.
     * </p>
     * <p>
     * Actual font height could be affected by system limitations, there may be
     * a maximum height defined by the system.
     * </p>
     *
     * @param face one of FACE_SYSTEM, FACE_MONOSPACE, or FACE_PROPORTIONAL
     * @param style STYLE_PLAIN, or a combination of STYLE_BOLD, STYLE_ITALIC,
     * and STYLE_UNDERLINED
     * @param height font height in pixels
     * @return new instance of Font
     * @throws IllegalArgumentException if height is negative, if face or style
     * are not legal values
     * @since 1.2
     */
    public static Font getFont(int face, int style, int height)
    {
        return com.nokia.mid.ui.FreeSizeFontInvoker.getFont(face, style, height);
    }
}