home *** CD-ROM | disk | FTP | other *** search
/ Chip 1998 November / Chip_1998-11_cd.bin / tema / Cafe / jfc.bin / View.java < prev    next >
Text File  |  1998-02-26  |  16KB  |  493 lines
  1. /*
  2.  * @(#)View.java    1.20 98/01/13
  3.  * 
  4.  * Copyright (c) 1997 Sun Microsystems, Inc. All Rights Reserved.
  5.  * 
  6.  * This software is the confidential and proprietary information of Sun
  7.  * Microsystems, Inc. ("Confidential Information").  You shall not
  8.  * disclose such Confidential Information and shall use it only in
  9.  * accordance with the terms of the license agreement you entered into
  10.  * with Sun.
  11.  * 
  12.  * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THE
  13.  * SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  14.  * IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
  15.  * PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR ANY DAMAGES
  16.  * SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING
  17.  * THIS SOFTWARE OR ITS DERIVATIVES.
  18.  * 
  19.  */
  20. package com.sun.java.swing.text;
  21.  
  22. import java.awt.Container;
  23. import java.awt.Graphics;
  24. import java.awt.Shape;
  25. import java.awt.Rectangle;
  26. import java.awt.Point;
  27. import com.sun.java.swing.event.*;
  28.  
  29. /**
  30.  * A view of some portion of document model.  Provides
  31.  * a mapping to model coordinates from view coordinates
  32.  * and a mapping to view coordinates from model coordinates.
  33.  * A view also provides rendering and layout services.
  34.  *
  35.  * @author  Timothy Prinzing
  36.  * @version 1.20 01/13/98
  37.  */
  38. public abstract class View {
  39.  
  40.     /**
  41.      * Creates a new JView object.
  42.      *
  43.      * @param elem the element to represent
  44.      */
  45.     public View(Element elem) {
  46.     this.elem = elem;
  47.     }
  48.  
  49.     /**
  50.      * Returns the parent of the view.
  51.      *
  52.      * @return the parent
  53.      */
  54.     protected final View getParent() {
  55.     return parent;
  56.     }
  57.  
  58.     /**
  59.      * Determines the preferred span for this view along an
  60.      * axis.
  61.      *
  62.      * @param axis may be either X_AXIS or Y_AXIS
  63.      * @returns  the span the view would like to be rendered into.
  64.      *           Typically the view is told to render into the span
  65.      *           that is returned, although there is no guarantee.  
  66.      *           The parent may choose to resize or break the view.
  67.      * @see View#getPreferredSpan
  68.      */
  69.     public abstract float getPreferredSpan(int axis);
  70.  
  71.     /**
  72.      * Child views can call this on the parent to indicate that
  73.      * the preference has changed and should be reconsidered
  74.      * for layout.  By default this just propagates upward to 
  75.      * the next parent.  The root view will call 
  76.      * <code>revalidate</code> on the associated text component.
  77.      *
  78.      * @param child the child view
  79.      * @param width true if the width preference has changed
  80.      * @param height true if the height preference has changed
  81.      * @see com.sun.java.swing.JComponent#revalidate
  82.      */
  83.     public void preferenceChanged(View child, boolean width, boolean height) {
  84.     getParent().preferenceChanged(child, width, height);
  85.     }
  86.  
  87.     /**
  88.      * Determines the desired alignment for this view along an
  89.      * axis.  By default this is simply centered.
  90.      *
  91.      * @param axis may be either X_AXIS or Y_AXIS
  92.      * @returns The desired alignment.  This should be a value
  93.      *   between 0.0 and 1.0 where 0 indicates alignment at the
  94.      *   origin and 1.0 indicates alignment to the full span
  95.      *   away from the origin.  An alignment of 0.5 would be the
  96.      *   center of the view.
  97.      */
  98.     public float getAlignment(int axis) {
  99.     return 0.5f;
  100.     }
  101.  
  102.     /**
  103.      * Renders using the given rendering surface and area on that
  104.      * surface.  The view may need to do layout and create child
  105.      * views to enable itself to render into the given allocation.
  106.      *
  107.      * @param g the rendering surface to use
  108.      * @param allocation the allocated region to render into
  109.      * @see View#paint
  110.      */
  111.     public abstract void paint(Graphics g, Shape allocation);
  112.  
  113.     /**
  114.      * Establishes the parent view for this view.  This is
  115.      * guaranteed to be called before any other methods if the
  116.      * parent view is functioning properly.  This is also
  117.      * the last method called, since it is called to indicate
  118.      * the view has been removed from the hierarchy as 
  119.      * well.  If this is reimplemented, 
  120.      * <code>super.setParent()</code> should be called.
  121.      *
  122.      * @param parent the new parent, or null if the view is
  123.      *  being removed from a parent it was previously added
  124.      *  to
  125.      */
  126.     public void setParent(View parent) {
  127.     this.parent = parent;
  128.     }
  129.  
  130.     /** 
  131.      * Returns the number of views in this view.  Since
  132.      * the default is to not be a composite view this
  133.      * returns 0.
  134.      *
  135.      * @return the number of views
  136.      * @see View#getViewCount
  137.      */
  138.     public int getViewCount() {
  139.     return 0;
  140.     }
  141.  
  142.     /** 
  143.      * Gets the nth child view.  Since there are no
  144.      * children by default, this returns null.
  145.      *
  146.      * @param n the number of the view to get
  147.      * @return the view
  148.      */
  149.     public View getView(int n) {
  150.     return null;
  151.     }
  152.  
  153.     /**
  154.      * Fetches the allocation for the given child view. 
  155.      * This enables finding out where various views
  156.      * are located, without assuming the views store
  157.      * their location.  This returns null since the
  158.      * default is to not have any child views.
  159.      *
  160.      * @param index the index of the child
  161.      * @param a  the allocation to this view.
  162.      * @return the allocation to the child
  163.      */
  164.     public Shape getChildAllocation(int index, Shape a) {
  165.     return null;
  166.     }
  167.  
  168.     /**
  169.      * Provides a mapping from the document model coordinate space
  170.      * to the coordinate space of the view mapped to it.
  171.      *
  172.      * @param pos the position to convert
  173.      * @param a the allocated region to render into
  174.      * @return the bounding box of the given position is returned
  175.      * @exception BadLocationException  if the given position does not represent a
  176.      *   valid location in the associated document
  177.      * @see View#modelToView
  178.      */
  179.     public abstract Shape modelToView(int pos, Shape a) throws BadLocationException;
  180.  
  181.     /**
  182.      * Provides a mapping from the view coordinate space to the logical
  183.      * coordinate space of the model.
  184.      *
  185.      * @param x the X coordinate
  186.      * @param y the Y coordinate
  187.      * @param a the allocated region to render into
  188.      * @return the location within the model that best represents the
  189.      *  given point in the view
  190.      * @see View#viewToModel
  191.      */
  192.     public abstract int viewToModel(float x, float y, Shape a);
  193.  
  194.     /**
  195.      * Gives notification that something was inserted into the document 
  196.      * in a location that this view is responsible for.
  197.      *
  198.      * @param e the change information from the associated document
  199.      * @param a the current allocation of the view
  200.      * @param f the factory to use to rebuild if the view has children
  201.      * @see View#insertUpdate
  202.      */
  203.     public void insertUpdate(DocumentEvent e, Shape a, ViewFactory f) {
  204.     }
  205.  
  206.     /**
  207.      * Gives notification from the document that attributes were removed 
  208.      * in a location that this view is responsible for.
  209.      *
  210.      * @param e the change information from the associated document
  211.      * @param a the current allocation of the view
  212.      * @param f the factory to use to rebuild if the view has children
  213.      * @see View#removeUpdate
  214.      */
  215.     public void removeUpdate(DocumentEvent e, Shape a, ViewFactory f) {
  216.     }
  217.  
  218.     /**
  219.      * Gives notification from the document that attributes were changed
  220.      * in a location that this view is responsible for.
  221.      *
  222.      * @param e the change information from the associated document
  223.      * @param a the current allocation of the view
  224.      * @param f the factory to use to rebuild if the view has children
  225.      * @see View#changedUpdate
  226.      */
  227.     public void changedUpdate(DocumentEvent e, Shape a, ViewFactory f) {
  228.     }
  229.  
  230.     /**
  231.      * Fetches the model associated with the view.
  232.      *
  233.      * @return the view model
  234.      * @see View#getDocument
  235.      */
  236.     public Document getDocument() {
  237.     return elem.getDocument();
  238.     }
  239.  
  240.     /**
  241.      * Fetches the portion of the model that this view is
  242.      * responsible for.
  243.      *
  244.      * @return the starting offset into the model
  245.      * @see View#getStartOffset
  246.      */
  247.     public int getStartOffset() {
  248.     return elem.getStartOffset();
  249.     }
  250.  
  251.     /**
  252.      * Fetches the portion of the model that this view is
  253.      * responsible for.
  254.      *
  255.      * @return the ending offset into the model
  256.      * @see View#getEndOffset
  257.      */
  258.     public int getEndOffset() {
  259.     return elem.getEndOffset();
  260.     }
  261.  
  262.     /**
  263.      * Fetches the structural portion of the subject that this
  264.      * view is mapped to.  The view may not be responsible for the
  265.      * entire portion of the element.
  266.      *
  267.      * @return the subject
  268.      * @see View#getElement
  269.      */
  270.     public Element getElement() {
  271.     return elem;
  272.     }
  273.  
  274.     /**
  275.      * Try to break this view on the given axis.  This is
  276.      * called by views that try to do formatting of their
  277.      * children.  For example, a view of a paragraph will
  278.      * typically try to place it's children into row and 
  279.      * views representing chucks of text can sometimes be 
  280.      * broken down into smaller pieces.
  281.      * <p>
  282.      * This is implemented to return the view itself, which
  283.      * represents the default behavior on not being
  284.      * breakable.  If the view does support breaking, the
  285.      * starting offset of the view returned should be the
  286.      * given offset, and the end offset should be less than
  287.      * or equal to the end offset of the view being broken.
  288.      *
  289.      * @param axis may be either X_AXIS or Y_AXIS
  290.      * @param offset the location in the document model
  291.      *   that a broken fragment would occupy.  This
  292.      *   would be the starting offset of the fragment
  293.      *   returned.
  294.      * @param pos the position along the axis that the
  295.      *  broken view would occupy.  This may be useful for
  296.      *  things like tab calculations.
  297.      * @param len specifies the distance along the axis
  298.      *  where a potential break is desired.  
  299.      * @param a the current allocation of the view
  300.      * @return the fragment of the view that represents the
  301.      *  given span, if the view can be broken.  If the view
  302.      *  doesn't support breaking behavior, the view itself is
  303.      *  returned.
  304.      * @see ParagraphView
  305.      */
  306.     public View breakView(int axis, int offset, float pos, float len) {
  307.     return this;
  308.     }
  309.  
  310.     /**
  311.      * Create a view that represents a portion of the element.
  312.      * This is potentially useful during formatting operations
  313.      * for taking measurements of fragments of the view.  If 
  314.      * the view doesn't support fragmenting (the default), it 
  315.      * should return itself.  
  316.      *
  317.      * @param p0 the starting offset.  This should be a value
  318.      *   greater or equal to the element starting offset and
  319.      *   less than the element ending offset.
  320.      * @param p1 the ending offset.  This should be a value
  321.      *   less than or equal to the elements end offset and
  322.      *   greater than the elements starting offset.
  323.      * @returns the view fragment, or itself if the view doesn't
  324.      *   support breaking into fragments.
  325.      * @see LabelView
  326.      */
  327.     public View createFragment(int p0, int p1) {
  328.     return this;
  329.     }
  330.  
  331.     /**
  332.      * Determines how attractive a break opportunity in 
  333.      * this view is.  This can be used for determining which
  334.      * view is the most attractive to call <code>breakView</code>
  335.      * on in the process of formatting.  A view that represents
  336.      * text that has whitespace in it might be more attractive
  337.      * than a view that has no whitespace for example.  The
  338.      * higher the weight, the more attractive the break.  A
  339.      * value equal to or lower than <code>BadBreakWeight</code>
  340.      * should not be considered for a break.  A value greater
  341.      * than or equal to <code>ForcedBreakWeight</code> should
  342.      * be broken.
  343.      * <p>
  344.      * This is implemented to provide the default behavior
  345.      * of returning <code>BadBreakWeight</code> unless the length
  346.      * is greater than the length of the view in which case the 
  347.      * entire view represents the fragment.  Unless a view has
  348.      * been written to support breaking behavior, it is not
  349.      * attractive to try and break the view.  An example of
  350.      * a view that does support breaking is <code>LabelView</code>.
  351.      * An example of a view that uses break weight is 
  352.      * <code>ParagraphView</code>.
  353.      *
  354.      * @param axis may be either X_AXIS or Y_AXIS
  355.      * @param pos the potential location of the start of the 
  356.      *   broken view.  This may be useful for calculating tab
  357.      *   positions.
  358.      * @param len specifies the relative length from <em>pos</em>
  359.      *   where a potential break is desired.
  360.      * @return the weight, which should be a value between
  361.      *   ForcedBreakWeight and BadBreakWeight.
  362.      * @see LabelView
  363.      * @see ParagraphView
  364.      * @see BadBreakWeight
  365.      * @see GoodBreakWeight
  366.      * @see ExcellentBreakWeight
  367.      * @see ForcedBreakWeight
  368.      */
  369.     public int getBreakWeight(int axis, float pos, float len) {
  370.     if (len > getPreferredSpan(axis)) {
  371.         return GoodBreakWeight;
  372.     }
  373.     return BadBreakWeight;
  374.     }
  375.  
  376.     /**
  377.      * Determines the resizability of the view along the
  378.      * given axis.  A value of 0 or less is not resizable.
  379.      *
  380.      * @param axis X_AXIS or Y_AXIS
  381.      * @return the weight
  382.      */
  383.     public int getResizeWeight(int axis) {
  384.     return 0;
  385.     }
  386.  
  387.     /**
  388.      * Sets the size of the view.  This should cause 
  389.      * layout of the view, if it has any layout duties.
  390.      * The default is to do nothing.
  391.      *
  392.      * @param width the width
  393.      * @param height the height
  394.      */
  395.     public void setSize(float width, float height) {
  396.     }
  397.  
  398.     /**
  399.      * Fetches the container hosting the view.  This is useful for
  400.      * things like scheduling a repaint, finding out the host 
  401.      * components font, etc.  The default implementation
  402.      * of this is to forward the query to the parent view.
  403.      *
  404.      * @return the container
  405.      */
  406.     public Container getContainer() {
  407.     View v = getParent();
  408.     return (v != null) ? v.getContainer() : null;
  409.     }
  410.  
  411.     /**
  412.      * Fetches the ViewFactory implementation that is feeding
  413.      * the view hierarchy.  Normally the views are given this
  414.      * as an argument to updates from the model when they
  415.      * are most likely to need the factory, but this
  416.      * method serves to provide it at other times.
  417.      *
  418.      * @return the factory
  419.      */
  420.     public ViewFactory getViewFactory() {
  421.     View v = getParent();
  422.     return (v != null) ? v.getViewFactory() : null;
  423.     }
  424.  
  425.     /**
  426.      * The weight to indicate a view is a bad break
  427.      * opportunity for the purpose of formatting.  This
  428.      * value indicates that no attempt should be made to
  429.      * break the view into fragments as the view has 
  430.      * not been written to support fragmenting.
  431.      * @see #getBreakWeight
  432.      * @see GoodBreakWeight
  433.      * @see ExcellentBreakWeight
  434.      * @see ForcedBreakWeight
  435.      */
  436.     public static final int BadBreakWeight = 0;
  437.  
  438.     /**
  439.      * The weight to indicate a view supports breaking,
  440.      * but better opportunities probably exist.
  441.      * 
  442.      * @see #getBreakWeight
  443.      * @see BadBreakWeight
  444.      * @see GoodBreakWeight
  445.      * @see ExcellentBreakWeight
  446.      * @see ForcedBreakWeight
  447.      */
  448.     public static final int GoodBreakWeight = 1000;
  449.  
  450.     /**
  451.      * The weight to indicate a view supports breaking,
  452.      * and this represents a very attractive place to
  453.      * break.
  454.      *
  455.      * @see #getBreakWeight
  456.      * @see BadBreakWeight
  457.      * @see GoodBreakWeight
  458.      * @see ExcellentBreakWeight
  459.      * @see ForcedBreakWeight
  460.      */
  461.     public static final int ExcellentBreakWeight = 2000;
  462.  
  463.     /**
  464.      * The weight to indicate a view supports breaking,
  465.      * and must be broken to be represented properly 
  466.      * when placed in a view that formats it's children
  467.      * by breaking them.
  468.      *
  469.      * @see #getBreakWeight
  470.      * @see BadBreakWeight
  471.      * @see GoodBreakWeight
  472.      * @see ExcellentBreakWeight
  473.      * @see ForcedBreakWeight
  474.      */
  475.     public static final int ForcedBreakWeight = 3000;
  476.  
  477.     /**
  478.      * Axis for format/break operations.
  479.      */
  480.     public static final int X_AXIS = 0;
  481.  
  482.     /**
  483.      * Axis for format/break operations.
  484.      */
  485.     public static final int Y_AXIS = 1;
  486.  
  487.  
  488.     private View parent;
  489.     private Element elem;
  490.  
  491. };
  492.  
  493.