/*******************************************************************************
 * Copyright (c) 2005 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.jface.layout;
import org.eclipse.swt.SWT;
import org.eclipse.swt.graphics.Point;
import org.eclipse.swt.layout.GridData;
import org.eclipse.swt.widgets.Control;

/**
 * This class provides a convienient shorthand for creating and initializing
 * GridData. This offers several benefits over creating GridData normal way:
 * 
 * <ul>
 * <li>The same factory can be used many times to create several GridData instances</li>
 * <li>The setters on GridDataFactory all return "this", allowing them to be chained</li> 
 * <li>GridDataFactory uses vector setters (it accepts Points), making it easy to
 *     set X and Y values together</li>
 * </ul>
 * 
 * <p>
 * GridDataFactory instances are created using one of the static methods on this class. 
 * </p>
 * 
 * <p>
 * Example usage:
 * </p>
 * <code>
 * 
 * ////////////////////////////////////////////////////////////
 * // Example 1: Typical grid data for a non-wrapping label
 * 
 *     // GridDataFactory version
 *     GridDataFactory.fillDefaults().applyTo(myLabel);
 * 
 *     // Equivalent SWT version
 *     GridData labelData = new GridData(GridData.HORIZONTAL_ALIGN_FILL | GridData.VERTICAL_ALIGN_FILL);
 *     myLabel.setLayoutData(labelData);
 * 
 * ///////////////////////////////////////////////////////////
 * // Example 2: Typical grid data for a wrapping label
 * 
 *     // GridDataFactory version
 *     GridDataFactory.fillDefaults()
 *          .align(SWT.FILL, SWT.CENTER)
 *    	    .hint(150, SWT.DEFAULT)
 *    	    .grab(true, false)
 *          .applyTo(wrappingLabel);
 *      
 *     // Equivalent SWT version
 *     GridData wrappingLabelData = new GridData(GridData.FILL_HORIZONTAL | GridData.VERTICAL_ALIGN_CENTER);
 *     wrappingLabelData.minimumWidth = 1;
 *     wrappingLabelData.widthHint = 150;
 *     wrappingLabel.setLayoutData(wrappingLabelData);
 * 
 * //////////////////////////////////////////////////////////////
 * // Example 3: Typical grid data for a scrollable control (a list box, tree, table, etc.)
 * 
 *     // GridDataFactory version
 *     GridDataFactory.fillDefaults().grab(true, true).hint(150, 150).applyTo(listBox);
 * 
 *     // Equivalent SWT version
 *     GridData listBoxData = new GridData(GridData.FILL_BOTH);
 *     listBoxData.widthHint = 150;
 *     listBoxData.heightHint = 150;
 *     listBoxData.minimumWidth = 1;
 *     listBoxData.minimumHeight = 1;
 *     listBox.setLayoutData(listBoxData);
 * 
 * /////////////////////////////////////////////////////////////
 * // Example 4: Typical grid data for a button
 *
 *     // GridDataFactory version
 *     Point preferredSize = button.computeSize(SWT.DEFAULT, SWT.DEFAULT, false);
 *     Point hint = Geometry.max(LayoutConstants.getMinButtonSize(), preferredSize);
 *     GridDataFactory.fillDefaults().align(SWT.FILL, SWT.CENTER).hint(hint).applyTo(button);
 *
 *     // Equivalent SWT version
 *     Point preferredSize = button.computeSize(SWT.DEFAULT, SWT.DEFAULT, false);
 *     Point hint = Geometry.max(LayoutConstants.getMinButtonSize(), preferredSize);
 *     GridData buttonData = new GridData(GridData.HORIZONTAL_ALIGN_FILL | GridData.VERTICAL_ALIGN_CENTER);
 *     buttonData.widthHint = hint.x;
 *     buttonData.heightHint = hint.y;
 *     button.setLayoutData(buttonData); 
 * </code>
 * 
 * <p>
 * IMPORTANT: WHEN ASSIGNING LAYOUT DATA TO A CONTROL, BE SURE TO USE
 * gridDataFactory.applyTo(control) AND NEVER
 * control.setLayoutData(gridDataFactory).
 * </p>
 * 
 */
public final class GridDataFactory {
    private GridData data;
    
    /**
     * Creates a GridDataFactory that creates copes of the given GridData. 
     * 
     * @param d template GridData to copy
     */
    private GridDataFactory(GridData d) {
        this.data = d;
    }
    
    /**
     * Creates a new GridDataFactory initialized with the SWT defaults.
     * This factory will generate GridData that is equivalent to 
     * "new GridData()".
     * 
     * <p>
     * Initial values are:
     * </p>
     * 
     * <ul>
     * <li>align(SWT.BEGINNING, SWT.CENTER)</li>
     * <li>exclude(false)</li>
     * <li>grab(false, false)</li>
     * <li>hint(SWT.DEFAULT, SWT.DEFAULT)</li>
     * <li>indent(0,0)</li>
     * <li>minSize(0,0)</li>
     * <li>span(1,1)</li>
     * </ul>
     * 
     * @return a new GridDataFactory instance
     * @see fillDefaults
     */
    public static GridDataFactory swtDefaults() {
    	return new GridDataFactory(new GridData());
    }
    
    /**
     * Creates a new GridDataFactory that creates copies of the given GridData
     * by default.
     * 
     * @param data GridData to copy
     * @return a new GridDataFactory that creates copies of the argument by default
     */
    public static GridDataFactory createFrom(GridData data) {
    	return new GridDataFactory(copyData(data));
    }
    
    /**
     * Creates a GridDataFactory initialized with defaults that will cause
     * the control to fill its cell.
     * 
     * <p>
     * Initial values are:
     * </p>
     * 
     * <ul>
     * <li>align(SWT.FILL, SWT.FILL)</li>
     * <li>exclude(false)</li>
     * <li>grab(false, false)</li>
     * <li>hint(SWT.DEFAULT, SWT.DEFAULT)</li>
     * <li>indent(0,0)</li>
     * <li>minSize(1,1)</li>
     * <li>span(1,1)</li>
     * </ul>
     *  
     * @return a GridDataFactory that makes controls fill their grid by default
     * 
     * @see swtDefaults
     */
    public static GridDataFactory fillDefaults() {
    	GridData data = new GridData();
        data.minimumWidth = 1;
        data.minimumHeight = 1;
        data.horizontalAlignment = SWT.FILL;
        data.verticalAlignment = SWT.FILL;
        
    	return new GridDataFactory(data);
    }

    /**
     * Sets the GridData span. The span controls how many cells
     * are filled by the control. 
     * 
     * @param hSpan number of columns spanned by the control
     * @param vSpan number of rows spanned by the control
     * @return this
     */
    public GridDataFactory span(int hSpan, int vSpan) {
        data.horizontalSpan = hSpan;
        data.verticalSpan = vSpan;
        return this;
    }

    /**
     * Sets the GridData span. The span controls how many cells
     * are filled by the control. 
     * 
     * @param span the new span. The x coordinate indicates the number of
     * columns spanned, and the y coordinate indicates the number of rows.
     * @return this
     */
    public GridDataFactory span(Point span) {
        data.horizontalSpan = span.x;
        data.verticalSpan = span.y;
        return this;
    }

    /**
     * Sets the width and height hints. The width and height hints override
     * the control's preferred size. If either hint is set to SWT.DEFAULT,
     * the control's preferred size is used. 
     * 
     * @param xHint horizontal hint (pixels), or SWT.DEFAULT to use the control's preferred size
     * @param yHint vertical hint (pixels), or SWT.DEFAULT to use the control's preferred size
     * @return this
     */
    public GridDataFactory hint(int xHint, int yHint) {
        data.widthHint = xHint;
        data.heightHint = yHint;
        return this;
    }

    /**
     * Sets the width and height hints. The width and height hints override
     * the control's preferred size. If either hint is set to SWT.DEFAULT,
     * the control's preferred size is used.
     * 
     * @param hint size (pixels) to be used instead of the control's preferred size. If
     * the x or y values are set to SWT.DEFAULT, the control's computeSize() method will
     * be used to obtain that dimension of the preferred size.
     * @return this
     */
    public GridDataFactory hint(Point hint) {
        data.widthHint = hint.x;
        data.heightHint = hint.y;
        return this;
    }

    /**
     * Sets the alignment of the control within its cell.
     * 
     * @param hAlign horizontal alignment. One of SWT.BEGINNING, SWT.CENTER, SWT.END, or SWT.FILL.
     * @param vAlign vertical alignment. One of SWT.BEGINNING, SWT.CENTER, SWT.END, or SWT.FILL.
     * @return this
     */
    public GridDataFactory align(int hAlign, int vAlign) {
        data.horizontalAlignment = hAlign;
        data.verticalAlignment = vAlign;
        return this;
    }

    /**
     * Sets the indent of the control within the cell. Moves the position of the control
     * by the given number of pixels. Positive values move toward the lower-right, negative
     * values move toward the upper-left.
     * 
     * @param hIndent distance to move to the right (negative values move left)
     * @param vIndent distance to move down (negative values move up)
     * @return this
     */
    public GridDataFactory indent(int hIndent, int vIndent) {
        data.horizontalIndent = hIndent;
        data.verticalIndent = vIndent;
        return this;
    }

    /**
     * Sets the indent of the control within the cell. Moves the position of the control
     * by the given number of pixels. Positive values move toward the lower-right, negative
     * values move toward the upper-left.
     * 
     * @param indent offset to move the control
     * @return this
     */
    public GridDataFactory indent(Point indent) {
        data.horizontalIndent = indent.x;
        data.verticalIndent = indent.y;
        return this;
    }

    /**
     * Determines whether extra horizontal or vertical space should be allocated to
     * this control's column when the layout resizes. If any control in the column
     * is set to grab horizontal then the whole column will grab horizontal space.
     * If any control in the row is set to grab vertical then the whole row will grab
     * vertical space.
     * 
     * @param horizontal true if the control's column should grow horizontally
     * @param vertical true if the control's row should grow vertically
     * @return this
     */
    public GridDataFactory grab(boolean horizontal, boolean vertical) {
        data.grabExcessHorizontalSpace = horizontal;
        data.grabExcessVerticalSpace = vertical;
        return this;
    }

    /**
     * Sets the minimum size for the control. The control will not be permitted
     * to shrink below this size. Note: GridLayout treats a minimum size of 0
     * as an undocumented special value, so the smallest possible minimum size 
     * is a size of 1. A minimum size of SWT.DEFAULT indicates that the result
     * of computeSize(int, int, boolean) should be used as the control's minimum
     * size.
     * 
     * 
     * @param minX minimum a value of 1 or more is a horizontal size of the control (pixels). 
     *        SWT.DEFAULT indicates that the control's preferred size should be used. A size
     *        of 0 has special semantics defined by GridLayout. 
     * @param minY minimum a value of 1 or more is a vertical size of the control (pixels). SWT.DEFAULT
     *        indicates that the control's preferred size should be used. A size
     *        of 0 has special semantics defined by GridLayout.
     * @return this
     */
    public GridDataFactory minSize(int minX, int minY) {
        data.minimumWidth = minX;
        data.minimumHeight = minY;
        return this;
    }

    /**
     * Sets the minimum size for the control. The control will not be permitted
     * to shrink below this size. Note: GridLayout treats a minimum size of 0
     * as an undocumented special value, so the smallest possible minimum size 
     * is a size of 1. A minimum size of SWT.DEFAULT indicates that the result
     * of computeSize(int, int, boolean) should be used as the control's minimum
     * size.
     * 
     * @param min minimum size of the control
     * @return this
     */
    public GridDataFactory minSize(Point min) {
        data.minimumWidth = min.x;
        data.minimumHeight = min.y;
        return this;
    }

    /**
     * Instructs the GridLayout to ignore this control when performing layouts. 
     * 
     * @param shouldExclude true iff the control should be excluded from layouts
     * @return this
     */
    public GridDataFactory exclude(boolean shouldExclude) {
        data.exclude = shouldExclude;
        return this;
    }

    /**
     * Creates a new GridData instance. All attributes of the GridData instance
     * will be initialized by the factory.
     * 
     * @return a new GridData instance
     */
    public GridData create() {
        return copyData(data);
    }

    /**
     * Creates a copy of the reciever.
     * 
     * @return a copy of the reciever
     */
    public GridDataFactory copy() {
    	return new GridDataFactory(create());
    }
    
    /**
     * Returns a copy of the given GridData 
     * 
     * @param data GridData to copy
     * @return a copy of the argument
     */
    public static GridData copyData(GridData data) {
        GridData newData = new GridData(data.horizontalAlignment, data.verticalAlignment, data.grabExcessHorizontalSpace, data.grabExcessVerticalSpace, data.horizontalSpan,
                data.verticalSpan);
        newData.exclude = data.exclude;
        newData.heightHint = data.heightHint;
        newData.horizontalIndent = data.horizontalIndent;
        newData.minimumHeight = data.minimumHeight;
        newData.minimumWidth = data.minimumWidth;
        newData.verticalIndent = data.verticalIndent;
        newData.widthHint = data.widthHint;

        return newData;
    }

    /**
     * Sets the layout data on the given control. Creates a new GridData instance and
     * assigns it to the control by calling control.setLayoutData.
     *  
     * @param control control whose layout data will be initialized
     */
    public void applyTo(Control control) {
        control.setLayoutData(create());
    }

}