/*

 * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

package javax.swing.text;

import java.awt.*;

import javax.swing.SwingConstants;

import javax.swing.event.*;

/**

 * <p>

 * A very important part of the text package is the <code>View</code> class.

 * As the name suggests it represents a view of the text model,

 * or a piece of the text model.

 * It is this class that is responsible for the look of the text component.

 * The view is not intended to be some completely new thing that one must

 * learn, but rather is much like a lightweight component.

 * <p>

By default, a view is very light.  It contains a reference to the parent

view from which it can fetch many things without holding state, and it

contains a reference to a portion of the model (<code>Element</code>).

A view does not

have to exactly represent an element in the model, that is simply a typical

and therefore convenient mapping.  A view can alternatively maintain a couple

of Position objects to maintain its location in the model (i.e. represent

a fragment of an element).  This is typically the result of formatting where

views have been broken down into pieces.  The convenience of a substantial

relationship to the element makes it easier to build factories to produce the

views, and makes it easier  to keep track of the view pieces as the model is

changed and the view must be changed to reflect the model.  Simple views

therefore represent an Element directly and complex views do not.

<p>

A view has the following responsibilities:

  <dl>

    <dt><b>Participate in layout.</b>

    <dd>

    <p>The view has a <code>setSize</code> method which is like

    <code>doLayout</code> and <code>setSize</code> in <code>Component</code> combined.

    The view has a <code>preferenceChanged</code> method which is

    like <code>invalidate</code> in <code>Component</code> except that one can

    invalidate just one axis

    and the child requesting the change is identified.

    <p>A View expresses the size that it would like to be in terms of three

    values, a minimum, a preferred, and a maximum span.  Layout in a view is

    can be done independently upon each axis.  For a properly functioning View

    implementation, the minimum span will be <= the preferred span which in turn

    will be <= the maximum span.

    </p>

    <p style="text-align:center"><img src="doc-files/View-flexibility.jpg"

                     alt="The above text describes this graphic.">

    <p>The minimum set of methods for layout are:

    <ul>

    <li>{@link #getMinimumSpan(int) getMinimumSpan}

    <li>{@link #getPreferredSpan(int) getPreferredSpan}

    <li>{@link #getMaximumSpan(int) getMaximumSpan}

    <li>{@link #getAlignment(int) getAlignment}

    <li>{@link #preferenceChanged(javax.swing.text.View, boolean, boolean) preferenceChanged}

    <li>{@link #setSize(float, float) setSize}

    </ul>

  <p>The <code>setSize</code> method should be prepared to be called a number of times

    (i.e. It may be called even if the size didn't change).

    The <code>setSize</code> method

    is generally called to make sure the View layout is complete prior to trying

    to perform an operation on it that requires an up-to-date layout.  A view's

    size should <em>always</em> be set to a value within the minimum and maximum

    span specified by that view.  Additionally, the view must always call the

    <code>preferenceChanged</code> method on the parent if it has changed the

    values for the

    layout it would like, and expects the parent to honor.  The parent View is

    not required to recognize a change until the <code>preferenceChanged</code>

    has been sent.

    This allows parent View implementations to cache the child requirements if

    desired.  The calling sequence looks something like the following:

    </p>

    <p style="text-align:center">

      <img src="doc-files/View-layout.jpg"

       alt="Sample calling sequence between parent view and child view:

       setSize, getMinimum, getPreferred, getMaximum, getAlignment, setSize">

    <p>The exact calling sequence is up to the layout functionality of

    the parent view (if the view has any children).  The view may collect

    the preferences of the children prior to determining what it will give

    each child, or it might iteratively update the children one at a time.

    </p>

    <dt><b>Render a portion of the model.</b>

    <dd>

    <p>This is done in the paint method, which is pretty much like a component

    paint method.  Views are expected to potentially populate a fairly large

    tree.  A <code>View</code> has the following semantics for rendering:

    </p>

    <ul>

    <li>The view gets its allocation from the parent at paint time, so it

    must be prepared to redo layout if the allocated area is different from

    what it is prepared to deal with.

    <li>The coordinate system is the same as the hosting <code>Component</code>

    (i.e. the <code>Component</code> returned by the

    {@link #getContainer getContainer} method).

    This means a child view lives in the same coordinate system as the parent

    view unless the parent has explicitly changed the coordinate system.

    To schedule itself to be repainted a view can call repaint on the hosting

    <code>Component</code>.

    <li>The default is to <em>not clip</em> the children.  It is more efficient

    to allow a view to clip only if it really feels it needs clipping.

    <li>The <code>Graphics</code> object given is not initialized in any way.

    A view should set any settings needed.

    <li>A <code>View</code> is inherently transparent.  While a view may render into its

    entire allocation, typically a view does not.  Rendering is performed by

    traversing down the tree of <code>View</code> implementations.

    Each <code>View</code> is responsible

    for rendering its children.  This behavior is depended upon for thread

    safety.  While view implementations do not necessarily have to be implemented

    with thread safety in mind, other view implementations that do make use of

    concurrency can depend upon a tree traversal to guarantee thread safety.

    <li>The order of views relative to the model is up to the implementation.

    Although child views will typically be arranged in the same order that they

    occur in the model, they may be visually arranged in an entirely different

    order.  View implementations may have Z-Order associated with them if the

    children are overlapping.

    </ul>

    <p>The methods for rendering are:

    <ul>

    <li>{@link #paint(java.awt.Graphics, java.awt.Shape) paint}

    </ul>

    <dt><b>Translate between the model and view coordinate systems.</b>

    <dd>

    <p>Because the view objects are produced from a factory and therefore cannot

    necessarily be counted upon to be in a particular pattern, one must be able

    to perform translation to properly locate spatial representation of the model.

    The methods for doing this are:

    <ul>

    <li>{@link #modelToView(int, javax.swing.text.Position.Bias, int, javax.swing.text.Position.Bias, java.awt.Shape) modelToView}

    <li>{@link #viewToModel(float, float, java.awt.Shape, javax.swing.text.Position.Bias[]) viewToModel}

    <li>{@link #getDocument() getDocument}

    <li>{@link #getElement() getElement}

    <li>{@link #getStartOffset() getStartOffset}

    <li>{@link #getEndOffset() getEndOffset}

    </ul>

    <p>The layout must be valid prior to attempting to make the translation.

    The translation is not valid, and must not be attempted while changes

    are being broadcasted from the model via a <code>DocumentEvent</code>.

    </p>

    <dt><b>Respond to changes from the model.</b>

    <dd>

    <p>If the overall view is represented by many pieces (which is the best situation

    if one want to be able to change the view and write the least amount of new code),

    it would be impractical to have a huge number of <code>DocumentListener</code>s.

    If each

    view listened to the model, only a few would actually be interested in the

    changes broadcasted at any given time.   Since the model has no knowledge of

    views, it has no way to filter the broadcast of change information.  The view

    hierarchy itself is instead responsible for propagating the change information.

    At any level in the view hierarchy, that view knows enough about its children to

    best distribute the change information further.   Changes are therefore broadcasted

    starting from the root of the view hierarchy.

    The methods for doing this are:

    <ul>

    <li>{@link #insertUpdate insertUpdate}

    <li>{@link #removeUpdate removeUpdate}

    <li>{@link #changedUpdate changedUpdate}

    </ul>

</dl>

 *

 * @author  Timothy Prinzing

 */

public abstract class View implements SwingConstants {

    /**

     * Creates a new <code>View</code> object.

     *

     * @param elem the <code>Element</code> to represent

     */

    public View(Element elem) {

        this.elem = elem;

    }

    /**

     * Returns the parent of the view.

     *

     * @return the parent, or <code>null</code> if none exists

     */

    public View getParent() {

        return parent;

    }

    /**

     *  Returns a boolean that indicates whether

     *  the view is visible or not.  By default

     *  all views are visible.

     *

     *  @return always returns true

     */

    public boolean isVisible() {

        return true;

    }

    /**

     * Determines the preferred span for this view along an

     * axis.

     *

     * @param axis may be either <code>View.X_AXIS</code> or

     *          <code>View.Y_AXIS</code>

     * @return   the span the view would like to be rendered into.

     *           Typically the view is told to render into the span

     *           that is returned, although there is no guarantee.

     *           The parent may choose to resize or break the view

     * @see View#getPreferredSpan

     */

    public abstract float getPreferredSpan(int axis);

    /**

     * Determines the minimum span for this view along an

     * axis.

     *

     * @param axis may be either <code>View.X_AXIS</code> or

     *          <code>View.Y_AXIS</code>

     * @return  the minimum span the view can be rendered into

     * @see View#getPreferredSpan

     */

    public float getMinimumSpan(int axis) {

        int w = getResizeWeight(axis);

        if (w == 0) {

            // can't resize

            return getPreferredSpan(axis);

        }

        return 0;

    }

    /**

     * Determines the maximum span for this view along an

     * axis.

     *

     * @param axis may be either <code>View.X_AXIS</code> or

     *          <code>View.Y_AXIS</code>

     * @return  the maximum span the view can be rendered into

     * @see View#getPreferredSpan

     */

    public float getMaximumSpan(int axis) {

        int w = getResizeWeight(axis);

        if (w == 0) {

            // can't resize

            return getPreferredSpan(axis);

        }

        return Integer.MAX_VALUE;

    }

    /**

     * Child views can call this on the parent to indicate that

     * the preference has changed and should be reconsidered

     * for layout.  By default this just propagates upward to

     * the next parent.  The root view will call

     * <code>revalidate</code> on the associated text component.

     *

     * @param child the child view

     * @param width true if the width preference has changed

     * @param height true if the height preference has changed

     * @see javax.swing.JComponent#revalidate

     */

    public void preferenceChanged(View child, boolean width, boolean height) {

        View parent = getParent();

        if (parent != null) {

            parent.preferenceChanged(this, width, height);

        }

    }

    /**

     * Determines the desired alignment for this view along an

     * axis.  The desired alignment is returned.  This should be

     * a value >= 0.0 and <= 1.0, where 0 indicates alignment at

     * the origin and 1.0 indicates alignment to the full span

     * away from the origin.  An alignment of 0.5 would be the

     * center of the view.

     *

     * @param axis may be either <code>View.X_AXIS</code> or

     *          <code>View.Y_AXIS</code>

     * @return the value 0.5

     */

    public float getAlignment(int axis) {

        return 0.5f;

    }

    /**

     * Renders using the given rendering surface and area on that

     * surface.  The view may need to do layout and create child

     * views to enable itself to render into the given allocation.

     *

     * @param g the rendering surface to use

     * @param allocation the allocated region to render into

     */

    public abstract void paint(Graphics g, Shape allocation);

    /**

     * Establishes the parent view for this view.  This is

     * guaranteed to be called before any other methods if the

     * parent view is functioning properly.  This is also

     * the last method called, since it is called to indicate

     * the view has been removed from the hierarchy as

     * well. When this method is called to set the parent to

     * null, this method does the same for each of its children,

     * propagating the notification that they have been

     * disconnected from the view tree. If this is

     * reimplemented, <code>super.setParent()</code> should

     * be called.

     *

     * @param parent the new parent, or <code>null</code> if the view is

     *          being removed from a parent

     */

    public void setParent(View parent) {

        // if the parent is null then propogate down the view tree

        if (parent == null) {

            for (int i = 0; i < getViewCount(); i++) {

                if (getView(i).getParent() == this) {

                    // in FlowView.java view might be referenced

                    // from two super-views as a child. see logicalView

                    getView(i).setParent(null);

                }

            }

        }

        this.parent = parent;

    }

    /**

     * Returns the number of views in this view.  Since

     * the default is to not be a composite view this

     * returns 0.

     *

     * @return the number of views >= 0

     * @see View#getViewCount

     */

    public int getViewCount() {

        return 0;

    }

    /**

     * Gets the <i>n</i>th child view.  Since there are no

     * children by default, this returns <code>null</code>.

     *

     * @param n the number of the view to get, >= 0 && < getViewCount()

     * @return the view

     */

    public View getView(int n) {

        return null;

    }

    /**

     * Removes all of the children.  This is a convenience

     * call to <code>replace</code>.

     *

     * @since 1.3

     */

    public void removeAll() {

        replace(0, getViewCount(), null);

    }

    /**

     * Removes one of the children at the given position.

     * This is a convenience call to <code>replace</code>.

     * @since 1.3

     */

    public void remove(int i) {

        replace(i, 1, null);

    }

    /**

     * Inserts a single child view.  This is a convenience

     * call to <code>replace</code>.

     *

     * @param offs the offset of the view to insert before >= 0

     * @param v the view

     * @see #replace

     * @since 1.3

     */

    public void insert(int offs, View v) {

        View[] one = new View[1];

        one[0] = v;

        replace(offs, 0, one);

    }

    /**

     * Appends a single child view.  This is a convenience

     * call to <code>replace</code>.

     *

     * @param v the view

     * @see #replace

     * @since 1.3

     */

    public void append(View v) {

        View[] one = new View[1];

        one[0] = v;

        replace(getViewCount(), 0, one);

    }

    /**

     * Replaces child views.  If there are no views to remove

     * this acts as an insert.  If there are no views to

     * add this acts as a remove.  Views being removed will

     * have the parent set to <code>null</code>, and the internal reference

     * to them removed so that they can be garbage collected.

     * This is implemented to do nothing, because by default

     * a view has no children.

     *

     * @param offset the starting index into the child views to insert

     *   the new views.  This should be a value >= 0 and <= getViewCount

     * @param length the number of existing child views to remove

     *   This should be a value >= 0 and <= (getViewCount() - offset).

     * @param views the child views to add.  This value can be

     *   <code>null</code> to indicate no children are being added

     *   (useful to remove).

     * @since 1.3

     */

    public void replace(int offset, int length, View[] views) {

    }

    /**

     * Returns the child view index representing the given position in

     * the model.  By default a view has no children so this is implemented

     * to return -1 to indicate there is no valid child index for any

     * position.

     *

     * @param pos the position >= 0

     * @return  index of the view representing the given position, or

     *   -1 if no view represents that position

     * @since 1.3

     */

    public int getViewIndex(int pos, Position.Bias b) {

        return -1;

    }

    /**

     * Fetches the allocation for the given child view.

     * This enables finding out where various views

     * are located, without assuming how the views store

     * their location.  This returns <code>null</code> since the

     * default is to not have any child views.

     *

     * @param index the index of the child, >= 0 && <

     *          <code>getViewCount()</code>

     * @param a  the allocation to this view

     * @return the allocation to the child

     */

    public Shape getChildAllocation(int index, Shape a) {

        return null;

    }

    /**

     * Provides a way to determine the next visually represented model

     * location at which one might place a caret.

     * Some views may not be visible,

     * they might not be in the same order found in the model, or they just

     * might not allow access to some of the locations in the model.

     * This method enables specifying a position to convert

     * within the range of >=0.  If the value is -1, a position

     * will be calculated automatically.  If the value < -1,

     * the {@code BadLocationException} will be thrown.

     *

     * @param pos the position to convert

     * @param a the allocated region in which to render

     * @param direction the direction from the current position that can

     *  be thought of as the arrow keys typically found on a keyboard.

     *  This will be one of the following values:

     * <ul>

     * <li>SwingConstants.WEST

     * <li>SwingConstants.EAST

     * <li>SwingConstants.NORTH

     * <li>SwingConstants.SOUTH

     * </ul>

     * @return the location within the model that best represents the next

     *  location visual position

     * @exception BadLocationException the given position is not a valid

     *                                 position within the document

     * @exception IllegalArgumentException if <code>direction</code>

     *          doesn't have one of the legal values above

     */

    public int getNextVisualPositionFrom(int pos, Position.Bias b, Shape a,

                                         int direction, Position.Bias[] biasRet)

      throws BadLocationException {

        if (pos < -1) {

            // -1 is a reserved value, see the code below

            throw new BadLocationException("Invalid position", pos);

        }

        biasRet[0] = Position.Bias.Forward;

        switch (direction) {

        case NORTH:

        case SOUTH:

        {

            if (pos == -1) {

                pos = (direction == NORTH) ? Math.max(0, getEndOffset() - 1) :

                    getStartOffset();

                break;

            }

            JTextComponent target = (JTextComponent) getContainer();

            Caret c = (target != null) ? target.getCaret() : null;

            // YECK! Ideally, the x location from the magic caret position

            // would be passed in.

            Point mcp;