// $Id: Orientation.java,v 1.6 2004/02/08 12:44:56 mvw Exp $
// Copyright (c) 2003 The Regents of the University of California. All
// Rights Reserved. Permission to use, copy, modify, and distribute this
// software and its documentation without fee, and without a written
// agreement is hereby granted, provided that the above copyright notice
// and this paragraph appear in all copies.  This software program and
// documentation are copyrighted by The Regents of the University of
// California. The software program and documentation are supplied "AS
// IS", without any accompanying services from The Regents. The Regents
// does not warrant that the operation of the program will be
// uninterrupted or error-free. The end-user understands that the program
// was developed for research purposes and is advised not to rely
// exclusively on the program for any reason.  IN NO EVENT SHALL THE
// UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT,
// SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS,
// ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF
// THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF
// SUCH DAMAGE. THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY
// WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
// MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE
// PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF
// CALIFORNIA HAS NO OBLIGATIONS TO PROVIDE MAINTENANCE, SUPPORT,
// UPDATES, ENHANCEMENTS, OR MODIFICATIONS.

/*
 * Orientation.java
 */
package org.argouml.swingext;

import java.awt.*;
import java.awt.event.*;

/**
 * Various utilities to aid components that are aware of their
 * horizontal/vertical orientation.  The Singleton pattern is used to
 * ensure that only one instance of a horizontal and one instance of a
 * vertical Orientation exist.

 *
 * Operations performed using length or breadth are transposed to
 * width and height depending on whether this is a vertical or
 * horizontal orientation.

 *
 * Horizontal treats length as width, breadth as height, position as x
 * and offset as y.

 *
 * Vertical treats length as height, breadth as width, position as y
 * and offset as x.

 *
 *
 *    HORIZONTAL                                          VERTICAL
 *
 *                                                    A
 *                                                    |
 *                                                 position = y
 *                                                    |
 *                                                    V
 *                +-------------+   A                 +-------------+   A
 *                |             |   |                 |             |   |
 * <--position--> |             | breadth = height    |             | length =
 *    = x         |             |   |                 |             |   |height
 *                +-------------+   V                 +-------------+   V
 *                 <-- length-->                       <--breadth-->
 *                    = width                             = width
 *
 *
 * @author Bob Tarling
 */
public abstract class Orientation {

    /**
     * Get an instance of an Orientation perpendicular to
     * this instance.

     *
     * If called on a horizontal instance then a vertical instance is
     * returned.

     *
     * If called on a vertical instance then a horizontal instance is
     * returned.

     * 
     *
     * @return A vertical or horizontal orientation.
     */
    public abstract Orientation getPerpendicular();

    /**
     * Get the length of a Dimension.
     *
     * @param dim The Dimension of which to determine
     * the length
     * @return The length of the Dimension.
     */
    public abstract int getLength(Dimension dim);

    /**
     * Get the length of a Component.
     *
     * @param comp The Component of which to
     * determine the length
     * @return The length of the Component.
     */
    public abstract int getLength(Component comp);
    
    /**
     * Get the usable length of a Container minus its
     * insets.
     *
     * @param cont The Container of which to
     * determine the length
     * @return The length of the Component.
     */
    public abstract int getLengthMinusInsets(Container cont);

    /**
     * Get the breadth of a Dimension.
     *
     * @param dim The Dimension of which to determine
     * the breadth
     * @return The breadth of the Dimension.
     */
    public abstract int getBreadth(Dimension dim);

    /**
     * Get the breadth of a Component.
     *
     * @param comp The Component of which to
     * determine the breadth
     * @return The breadth of the Component.
     */
    public abstract int getBreadth(Component comp);

    /**
     * Get the position of a Point.
     *
     * @param point The Point of which to determine
     * the position
     * @return The position of the Point.
     */
    public abstract int getPosition(Point point);

    /**
     * Get the offset of a Point.
     *
     * @param point The Point of which to determine the offset
     * @return The offset of the Point.
     */
    public abstract int getOffset(Point point);

    /**
     * Determines the last usable position in a
     * Container. This takes into account the
     * Insets of the Container.
     *
     * @param cont the Container from which to
     * determine the last usable position.
     * @return The offset of the Container.
     */
    public abstract int getLastUsablePosition(Container cont);

    /**
     * Determines the first usable offset in a
     * Container. This takes into account the
     * Insets of the Container.
     *
     * @param cont the Container from which to
     * determine the first usable position.
     * @return The offset of the Container.
     */
    public abstract int getFirstUsableOffset(Container cont);

    /**
     * Generate a new Point object from position and offset values.
     *
     * @param position the required position of the new Point.
     * @param offset the required offset of the new Point.
     * @return The newly created Point object.
     */
    public abstract Point newPoint(int position, int offset);
    
    /**
     * Get the position of a Component.
     *
     * @param comp The Component of which to
     * determine the position
     * @return The position of the Component.
     */
    public abstract int getPosition(Component comp);

    /**
     * Get the position of a MouseEvent.
     *
     * @param me The MouseEvent of which to determine
     * the position
     * @return The position of the MouseEvent.
     */
    public abstract int getPosition(MouseEvent me);

    /**
     * Create a new Dimension from an existing
     * Dimension with its length increased by a given
     * value.
     *
     * @param original The Dimension to be added to.
     * @param add The amount to add to the Dimension.
     * @return The resulting Dimension.
     */
    public abstract Dimension addLength(Dimension original, int add);

    /**
     * Create a new Dimension from an existing
     * Dimension with its length increased by the length
     * of another Dimension.
     *
     * @param original The Dimension to be added to.
     * @param add The Dimension whose length is to be
     * taken as the added value.
     * @return The resulting Dimension.
     */
    public Dimension addLength(Dimension original, Dimension add) {
        return addLength(original, getLength(add));
    }

    /**
     * Create a new Dimension from an existing
     * Dimension with its length increased by the length
     * of a Component.
     *
     * @param original The Dimension to be added to.
     * @param add The Component whose length is to be
     * taken as the added value.
     * @return The resulting Dimension.
     */
    public Dimension addLength(Dimension original, Component add) {
        return addLength(original, getLength(add.getSize()));
    }

    /**
     * Create a new Dimension from an existing
     * Dimension with its length decreased by a given
     * value.
     *
     * @param original The Dimension to be subtracted from.
     * @param subtract The amount to subtract from the
     * Dimension.
     * @return The resulting Dimension.
     */
    public Dimension subtractLength(Dimension original, int subtract) {
        return addLength(original, -subtract);
    }

    /**
     * Create a new Dimension from an existing
     * Dimension with its length decreased by the length
     * of another Dimension.
     *
     * @param original The Dimension to be subtracted from.
     * @param subtract The Dimension whose length is
     * to be taken as the subtracted value.
     * @return The resulting Dimension.
     */
    public Dimension subtractLength(Dimension original, Dimension subtract) {
        return subtractLength(original, getLength(subtract));
    }

    /**
     * Create a new Dimension from an existing
     * Dimension with its length decreased by the length
     * of a Component.
     *
     * @param original The Dimension to be subtracted from.
     * @param subtract The Component whose length is
     * to be taken as the subtracted value.
     * @return The resulting Dimension.
     */
    public Dimension subtractLength(Dimension original, Component subtract) {
        return subtractLength(original, getLength(subtract.getSize()));
    }

    /**
     * Create a new Point from an existing
     * Point with its position increased by a given
     * value.
     *
     * @param original The Point to be added to.
     * @param add The amount to add to the Point.
     * @return The resulting Point.
     */
    public abstract Point addToPosition(Point original, int add);

    /**
     * Create a new Point from an existing
     * Point with its length increased by the length of a
     * Dimension.
     *
     * @param original The Point to be added to.
     * @param add The Dimension whose length is to be
     * taken as the added value.
     * @return The resulting Point.
     */
    public Point addToPosition(Point original, Dimension add) {
        return addToPosition(original, getLength(add));
    }

    /**
     * Create a new Point from an existing
     * Point with its length increased by the length of a
     * Component.
     *
     * @param original The Point to be added to.
     * @param add The Dimension whose length is to be
     * taken as the added value.
     * @return The resulting Point.
     */
    public Point addToPosition(Point original, Component add) {
        return addToPosition(original, getLength(add.getSize()));
    }

    /**
     * Create a new Point from an existing
     * Point with its position decreased by a given
     * value.
     *
     * @param original The Point to be added to.
     * @param subtract The amount to subtract to the Point.
     * @return The resulting Point.
     */
    public Point subtractFromPosition(Point original, int subtract) {
        return addToPosition(original, -subtract);
    }

    /**
     * Create a new Point from an existing
     * Point with its length decreased by the length of a
     * Dimension.
     *
     * @param original The Point to be added to.
     * @param subtract The Dimension whose length is
     * to be taken as the subtracted value.
     * @return The resulting Point.
     */
    public Point subtractFromPosition(Point original, Dimension subtract) {
        return addToPosition(original, -getLength(subtract));
    }

    /**
     * Create a new Point from an existing
     * Point with its length decreased by the length of a
     * Component.
     *
     * @param original The Point to be added to.
     * @param subtract The Component whose length is
     * to be taken as the subtracted value.
     * @return The resulting Point.
     */
    public Point subtractFromPosition(Point original, Component subtract) {
        return addToPosition(original, -getLength(subtract.getSize()));
    }

    /**
     * Create a new Dimension from an existing
     * Dimension with its length changed to a given
     * value.
     *
     * @param original The Dimension to be added to.
     * @param length The length to assign to the new
     * Dimension.
     * @return             The resulting Dimension.
     */
    public abstract Dimension setLength(Dimension original, int length);

    /**
     * Create a new Dimension from an existing
     * Dimension with its length changed to the length of
     * another given Dimension.
     *
     * @param original The Dimension whose length is
     * to be modified.
     * @param length   The value to assign as the new length.
     * @return             The resulting Dimension.
     */
    public abstract Dimension setLength(Dimension original, Dimension length);

    /**
     * Create a new Point from an existing
     * Point with its position changed to a given value.
     *
     * @param original The Point whose position is to
     * be modified.
     * @param position The value to assign as the new position.
     * @return             The resulting Point.
     */
    public abstract Point setPosition(Point original, int position);

    /**
     * Create a new Dimension from an existing
     * Dimension with its breadth changed to a given
     * value.
     *
     * @param original The Dimension to be added to.
     * @param breadth The breadth to assign to the new
     * Dimension.
     * @return             The resulting Dimension.
     */
    public abstract Dimension setBreadth(Dimension original, int breadth);

    /**
     * Create a new Dimension from an existing
     * Dimension with its breadth changed to the breadth
     * of another given Dimension.
     *
     * @param original The Dimension to be added to.
     * @param breadth The Dimension whose breadth is
     * to be assigned to the new Dimension.
     * @return             The resulting Dimension.
     */
    public abstract Dimension setBreadth(Dimension original, Dimension breadth);
    
    /**
     * Get a cursor object pointing in the same direction as the orientation.
     *
     * @return The resulting Cursor.
     */
    public abstract Cursor getCursor();
    
    /**
     * Get an arrow button pointing to the start of the orientation.
     *
     * @return The resulting ArrowButton.
     */
    public abstract ArrowButton getStartArrowButton();
    
    /**
     * Get an arrow button pointing to the end of the orientation.
     *
     * @return The resulting ArrowButton.
     */
    public abstract ArrowButton getEndArrowButton();
    
}