bundles/org.eclipse.rap.draw2d/src/org/eclipse/draw2d/FigureUtilities.java

/*******************************************************************************
 * Copyright (c) 2000, 2010 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
 *******************************************************************************/
package org.eclipse.draw2d;

import java.util.ArrayList;

import org.eclipse.draw2d.geometry.Dimension;
import org.eclipse.draw2d.geometry.Rectangle;
import org.eclipse.draw2d.rap.swt.graphics.ColorUtil;
import org.eclipse.rap.rwt.SingletonUtil;
import org.eclipse.swt.graphics.Color;
import org.eclipse.swt.graphics.Font;
import org.eclipse.swt.graphics.FontMetrics;
import org.eclipse.swt.graphics.GC;
import org.eclipse.swt.widgets.Shell;

/**
 * Provides miscellaneous Figure operations.
 */
public class FigureUtilities {

	private static final float RGB_VALUE_MULTIPLIER = 0.6f;
	//[RAP AM] remove static usage
	private GC gc;
    private Font appliedFont;
    private FontMetrics metrics;
	//private static Color ghostFillColor = new Color(null, 31, 31, 31);
	private static Color ghostFillColor() {
	   return ColorUtil.getColor( 31, 31, 31 );
    }
	
	private static FigureUtilities instance() {
	  return SingletonUtil.getSessionInstance( FigureUtilities.class );
	}
	
	/**
	 * Returns a new Color the same as the passed color in a darker hue.
	 * 
	 * @param color
	 *            the color to darken
	 * @return the darkened color
	 * @since 2.0
	 */
	public static Color darker(Color color) {
		return new Color(null, (int) (color.getRed() * RGB_VALUE_MULTIPLIER),
				(int) (color.getGreen() * RGB_VALUE_MULTIPLIER),
				(int) (color.getBlue() * RGB_VALUE_MULTIPLIER));
	}

	/**
	 * Returns the FontMetrics associated with the passed Font.
	 * 
	 * @param f
	 *            the font
	 * @return the FontMetrics for the given font
	 * @see GC#getFontMetrics()
	 * @since 2.0
	 */
	public static FontMetrics getFontMetrics(Font f) {
		setFont(f);
		FigureUtilities fu = instance();
		if (fu.metrics == null)
			fu.metrics = getGC().getFontMetrics();
		return fu.metrics;
	}

	/**
	 * Returns the GC used for various utilities. Advanced graphics must not be
	 * switched on by clients using this GC.
	 * 
	 * @deprecated do not mess with this GC
	 * @return the GC
	 */
	protected static GC getGC() {
	    FigureUtilities fu = instance();
		if (fu.gc == null) {
			fu.gc = new GC(new Shell());
			fu.appliedFont = fu.gc.getFont();
		}
		return fu.gc;
	}

	/**
	 * Returns the dimensions of the String <i>s</i> using the font <i>f</i>.
	 * Tab expansion and carriage return processing are performed.
	 * 
	 * @param s
	 *            the string
	 * @param f
	 *            the font
	 * @return the text's dimensions
	 * @see GC#textExtent(String)
	 */
	protected static org.eclipse.swt.graphics.Point getTextDimension(String s,
			Font f) {
		setFont(f);
		return getGC().textExtent(s);
	}

	/**
	 * Returns the highest ancestor for the given figure
	 * 
	 * @since 3.0
	 * @param figure
	 *            a figure
	 * @return the root ancestor
	 */
	public static IFigure getRoot(IFigure figure) {
		while (figure.getParent() != null)
			figure = figure.getParent();
		return figure;
	}

	/**
	 * Returns the dimensions of the String <i>s</i> using the font <i>f</i>. No
	 * tab expansion or carriage return processing will be performed.
	 * 
	 * @param s
	 *            the string
	 * @param f
	 *            the font
	 * @return the string's dimensions
	 * @see GC#stringExtent(java.lang.String)
	 */
	protected static org.eclipse.swt.graphics.Point getStringDimension(
			String s, Font f) {
		setFont(f);
		return getGC().stringExtent(s);
	}

	/**
	 * Returns the Dimensions of the given text, converting newlines and tabs
	 * appropriately.
	 * 
	 * @param text
	 *            the text
	 * @param f
	 *            the font
	 * @return the dimensions of the given text
	 * @since 2.0
	 */
	public static Dimension getTextExtents(String text, Font f) {
		return new Dimension(getTextDimension(text, f));
	}

	/**
	 * Returns the Dimensions of <i>s</i> in Font <i>f</i>.
	 * 
	 * @param s
	 *            the string
	 * @param f
	 *            the font
	 * @return the dimensions of the given string
	 * @since 2.0
	 */
	public static Dimension getStringExtents(String s, Font f) {
		return new Dimension(getStringDimension(s, f));
	}

	/**
	 * Returns the Dimensions of the given text, converting newlines and tabs
	 * appropriately.
	 * 
	 * @param s
	 *            the string
	 * @param f
	 *            the font
	 * @param result
	 *            the Dimension that will contain the result of this calculation
	 * @since 2.0
	 */
	public static void getTextExtents(String s, Font f, Dimension result) {
		org.eclipse.swt.graphics.Point pt = getTextDimension(s, f);
		result.width = pt.x;
		result.height = pt.y;
	}

	/**
	 * Returns the width of <i>s</i> in Font <i>f</i>.
	 * 
	 * @param s
	 *            the string
	 * @param f
	 *            the font
	 * @return the width
	 * @since 2.0
	 */
	public static int getTextWidth(String s, Font f) {
		return getTextDimension(s, f).x;
	}

	/**
	 * Returns a Color the same as the passed color in a lighter hue.
	 * 
	 * @param rgb
	 *            the color
	 * @return the lighter color
	 * @since 2.0
	 */
	public static Color lighter(Color rgb) {
		int r = rgb.getRed(), g = rgb.getGreen(), b = rgb.getBlue();

		return new Color(null, Math.max(2,
				Math.min((int) (r / RGB_VALUE_MULTIPLIER), 255)), Math.max(2,
				Math.min((int) (g / RGB_VALUE_MULTIPLIER), 255)), Math.max(2,
				Math.min((int) (b / RGB_VALUE_MULTIPLIER), 255)));
	}

	/**
	 * Produces a ghosting effect on the shape <i>s</i>.
	 * 
	 * @param s
	 *            the shape
	 * @return the ghosted shape
	 * @since 2.0
	 */
	public static Shape makeGhostShape(Shape s) {
		s.setBackgroundColor(ghostFillColor());
		s.setFillXOR(true);
		s.setOutlineXOR(true);
		return s;
	}

	/**
	 * Mixes the passed Colors and returns the resulting Color.
	 * 
	 * @param c1
	 *            the first color
	 * @param c2
	 *            the second color
	 * @param weight
	 *            the first color's weight from 0-1
	 * @return the new color
	 * @since 2.0
	 */
	public static Color mixColors(Color c1, Color c2, double weight) {
		return new Color(null, (int) (c1.getRed() * weight + c2.getRed()
				* (1 - weight)), (int) (c1.getGreen() * weight + c2.getGreen()
				* (1 - weight)), (int) (c1.getBlue() * weight + c2.getBlue()
				* (1 - weight)));
	}

	/**
	 * Mixes the passed Colors and returns the resulting Color.
	 * 
	 * @param c1
	 *            the first color
	 * @param c2
	 *            the second color
	 * @return the new color
	 * @since 2.0
	 */
	public static Color mixColors(Color c1, Color c2) {
		return new Color(null, (c1.getRed() + c2.getRed()) / 2,
				(c1.getGreen() + c2.getGreen()) / 2,
				(c1.getBlue() + c2.getBlue()) / 2);
	}

	/**
	 * Paints a border with an etching effect, having a shadow of Color
	 * <i>shadow</i> and highlight of Color <i>highlight</i>.
	 * 
	 * @param g
	 *            the graphics object
	 * @param r
	 *            the bounds of the border
	 * @param shadow
	 *            the shadow color
	 * @param highlight
	 *            the highlight color
	 * @since 2.0
	 */
	public static void paintEtchedBorder(Graphics g, Rectangle r, Color shadow,
			Color highlight) {
		int x = r.x, y = r.y, w = r.width, h = r.height;

		g.setLineStyle(Graphics.LINE_SOLID);
		g.setLineWidth(1);
		g.setXORMode(false);

		w -= 2;
		h -= 2;

		g.setForegroundColor(shadow);
		g.drawRectangle(x, y, w, h);

		x++;
		y++;
		g.setForegroundColor(highlight);
		g.drawRectangle(x, y, w, h);
	}

	/**
	 * Helper method to paint a grid. Painting is optimized as it is restricted
	 * to the Graphics' clip.
	 * 
	 * @param g
	 *            The Graphics object to be used for painting
	 * @param f
	 *            The figure in which the grid is to be painted
	 * @param origin
	 *            Any point where the grid lines are expected to intersect
	 * @param distanceX
	 *            Distance between vertical grid lines; if 0 or less, vertical
	 *            grid lines will not be drawn
	 * @param distanceY
	 *            Distance between horizontal grid lines; if 0 or less,
	 *            horizontal grid lines will not be drawn
	 * 
	 * @since 3.0
	 */
	public static void paintGrid(Graphics g, IFigure f,
			org.eclipse.draw2d.geometry.Point origin, int distanceX,
			int distanceY) {
		Rectangle clip = g.getClip(Rectangle.getSINGLETON());

		if (distanceX > 0) {
			if (origin.x >= clip.x)
				while (origin.x - distanceX >= clip.x)
					origin.x -= distanceX;
			else
				while (origin.x < clip.x)
					origin.x += distanceX;
			for (int i = origin.x; i < clip.x + clip.width; i += distanceX)
				g.drawLine(i, clip.y, i, clip.y + clip.height);
		}

		if (distanceY > 0) {
			if (origin.y >= clip.y)
				while (origin.y - distanceY >= clip.y)
					origin.y -= distanceY;
			else
				while (origin.y < clip.y)
					origin.y += distanceY;
			for (int i = origin.y; i < clip.y + clip.height; i += distanceY)
				g.drawLine(clip.x, i, clip.x + clip.width, i);
		}
	}

	/**
	 * Paints a border with an etching effect, having a shadow of a darker
	 * version of g's background color, and a highlight a lighter version of g's
	 * background color.
	 * 
	 * @param g
	 *            the graphics object
	 * @param r
	 *            the bounds of the border
	 * @since 2.0
	 */
	public static void paintEtchedBorder(Graphics g, Rectangle r) {
		Color rgb = g.getBackgroundColor(), shadow = darker(rgb), highlight = lighter(rgb);
		paintEtchedBorder(g, r, shadow, highlight);
	}

	/**
	 * Sets Font to passed value.
	 * 
	 * @param f
	 *            the new font
	 * @since 2.0
	 */
	protected static void setFont(Font f) {
	    FigureUtilities fu = instance();
		if (fu.appliedFont == f || (f != null && f.equals(fu.appliedFont)))
			return;
		getGC().setFont(f);
		fu.appliedFont = f;
		fu.metrics = null;
	}

	/**
	 * Returns the figure which is the nearest common ancestor of both figures,
	 * or <code>null</code> if there is no common ancestor. A figure is an
	 * ancestor if it is the parent of another figure, or if it is the ancestor
	 * of that figure's parent. If one figure is the ancestor of the other, it
	 * is returned as the common ancestor.
	 * 
	 * @since 3.1
	 * @param l
	 *            left
	 * @param r
	 *            right
	 * @return the common ancestor, if it exists, or <code>null</code>.
	 */
	public static IFigure findCommonAncestor(IFigure l, IFigure r) {
		if (l == r)
			return l;
		ArrayList left = new ArrayList();
		ArrayList right = new ArrayList();
		while (l != null) {
			left.add(l);
			l = l.getParent();
		}
		while (r != null) {
			right.add(r);
			r = r.getParent();
		}
		if (left.isEmpty() || right.isEmpty())
			return null;

		for (int i = 0; i < left.size(); i++) {
			if (right.contains(left.get(i)))
				return (IFigure) left.get(i);
		}
		return null;
	}

	/**
	 * Returns <code>true</code> if the ancestor contains the descendant, or is
	 * the ancestor of the descendant's parent.
	 * 
	 * @param ancestor
	 *            the ancestor
	 * @param descendant
	 *            the descendant
	 * @return <code>true</code> if ancestor
	 * @since 3.2
	 */
	public static boolean isAncestor(final IFigure ancestor, IFigure descendant) {
		while (descendant != null) {
			descendant = descendant.getParent();
			if (descendant == ancestor)
				return true;
		}
		return false;
	}

	/**
	 * Determines whether the given figure is showing and not (completely)
	 * clipped.
	 * 
	 * @param figure
	 *            The figure to test
	 * @return <code>true</code> if the given figure is showing and not
	 *         completely clipped, <code>false</code> otherwise.
	 * @since 3.7
	 */
	public static boolean isNotFullyClipped(IFigure figure) {
		if (figure == null || !figure.isShowing()) {
			return false;
		}
		// check if figure is clipped
		// TODO: IClippingStrategy has to be taken into consideration as well.
		Rectangle figBounds = figure.getBounds().getCopy();
		IFigure walker = figure.getParent();
		while (!figBounds.isEmpty() && walker != null) {
			walker.translateToParent(figBounds);
			figBounds.intersect(walker.getBounds());
			walker = walker.getParent();
		}
		return !figBounds.isEmpty();
	}

}