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

 * Copyright (c) 2008 Nokia Corporation and/or its subsidiary(-ies).

 * 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:

 *     Nokia Corporation - initial implementation 

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

package org.eclipse.swt.internal.qt.graphics;

/**

 * This is a helper class for getting font related information 

 * ouside GraphicsContext bind-release cycle, i.e. these utilities must be used for getting

 * font metrics when GraphicsContext does not have a target and it's methods cannot be used.

 * These utilities do not have any dependency to GraphicsContext or it's state.

 */

public final class FontUtils {

    /**

     * handle of native QFont

     */

    private int handle;

    /**

     * Constructs FontUtils with specified font handle

     * 

     * @param fontHandle Handle of native QFont

     * @throws IllegalArgumentException if given font handle is 0

     */

    public FontUtils(int fontHandle) {

    	checkState();

        setFont(fontHandle);

    }

    /**

     * Returns the ascent of the font. 

     * The ascent of a font is the distance from baseline to the highest position characters extent to.

     * 

     * @return The ascent for this font

     */

    public int getAscent() {

    	checkState();

        return OS.fontUtils_getAscent(handle);

    }

    /** 

     * Returns the bounding rectangle that is covered by given text if drawn at origo, 

     * i.e. coordinates (0,0). The vertical base point is based on the text baseline, i.e.

     * y-coordinate is always negative as text extends ascent number of pixel up from baseline.

     * Bounding rectangle height is based on font height not the actual height that the text would occupy.  

     * 

     * Note that the bounding rectangle might extent to left of (0,0), e.g. for italized fonts.

     * 

     * Values are stored in boundingBox array as follows: 

     * <ul>

     * <li>rect[GraphicsContect.RECT_X] - the x coordinate of rect</li>

     * <li>rect[GraphicsContect.RECT_Y] - the y coordinate of rect

     * <li>rect[GraphicsContect.RECT_WIDTH] - the width of rect

     * <li>rect[GraphicsContect.RECT_HEIGHT] - the height of rect

     * </ul>

     * 

     * @param boundingBox The array to where populate rect, size must not be < 4

     * @param str The text to measure

     * @return bounding rectangle coordinates x, y, width and height 

     * 

     * @throws IllegalArgumentException if size of <code>rect</code> is < 4

     * @throws NullPointerException if <code>rect</code>  or <code>str</code> is null

     * 

     */

    public void getBoundingRect(int[] boundingBox, String str) {

    	checkState();

        if(boundingBox == null || str == null) {

            throw new NullPointerException("boundingBox or str is null");

        }

        if(boundingBox.length < 4) {

            throw new IllegalArgumentException("boundingBox size is < 4");

        }

        if(str.length() == 0) {

            for(int i=0; i<4; i++)

            {

            	boundingBox[i]=0;

            }

            return;

        }

        OS.fontUtils_getBoundingRect(handle, boundingBox, str);

    }

    /**

     * Returns the descent of the font. 

     * The descent is of a font is the distance from baseline to the lowest position characters extent to.

     * 

     * @return The ascent for this font

     */

    public int getDescent() {

    	checkState();

        return OS.fontUtils_getDescent(handle);

    }

    /**

     * Sets new font to this instance. 

     * All subsequent measurements are based on the font set with this method.

     * 

     * @param fontHandle Handle of native QFont

     * @throws IllegalArgumentException if given font handle is 0

     */

    public void setFont(int fontHandle) {

    	checkState();

        if(fontHandle != 0) {

            handle = fontHandle;

        } else {

            throw new IllegalArgumentException("fontHandle is 0");

        }

    }

    /**

     * Gets the advance width of the specified string when using the currently set font.

     * The width specifies the distance where next character should ne drawn, note that 

     * the last character might partially be drawn beyond the right side of the returned width. 

     * 

     * @param str The characters to measure

     * @return The total advance width or 0 if size of str is 0

     * @throws NullPointerException if <code>str</code> is null

     */

    public int stringWidth(String str) {

    	checkState();

        if(str == null) {

            throw new NullPointerException("str is null");

        }

        if(str.length() == 0) {

            return 0;

        }

        return OS.fontUtils_getStringWidth(handle, str);

    }

    /**

     * private method for checking the state of this instance.

     */

    private void checkState() {

    	Utils.validateUiThread();

    }

}