[cp-patches] FYI: API for javax.swing.text classes

[Roman Kennke]

I added API comments to BasicTextUI and BasicEditorPaneUI.

2005-07-29  Roman Kennke  <address@hidden>

        * javax/swing/plaf/basic/BasicEditorPaneUI.java: Added API
        comments all over.
        * javax/swing/plaf/basic/BasicTextUI.java: Likewise.

/Roman

Index: javax/swing/plaf/basic/BasicEditorPaneUI.java
===================================================================
RCS file: 
/cvsroot/classpath/classpath/javax/swing/plaf/basic/BasicEditorPaneUI.java,v
retrieving revision 1.4
diff -u -r1.4 BasicEditorPaneUI.java
--- javax/swing/plaf/basic/BasicEditorPaneUI.java       29 Jul 2005 11:06:27 
-0000      1.4
+++ javax/swing/plaf/basic/BasicEditorPaneUI.java       29 Jul 2005 14:12:14 
-0000
@@ -47,23 +47,49 @@
 import javax.swing.text.PlainView;
 import javax.swing.text.View;
 
+/**
+ * The UI class for  address@hidden JEditorPane}s.
+ *
+ * @author original author unknown
+ * @author Roman Kennke (address@hidden)
+ */
 public class BasicEditorPaneUI extends BasicTextUI
 {
+  /**
+   * Creates an instance of <code>BasicEditorPaneUI</code> for the text
+   * component <code>comp</code>.
+   *
+   * @param comp the component for which to create an UI
+   *
+   * @return the UI for <code>comp</code>
+   */
   public static ComponentUI createUI(JComponent comp)
   {
     return new BasicEditorPaneUI();
   }
 
+  /**
+   * Creates a new <code>BasicEditorPaneUI</code>
+   */
   public BasicEditorPaneUI()
   {
     // Do nothing here.
   }
 
+  // FIXME: Should not be overridden here but instead be handled by the
+  // JEditorPane's EditorKit. However, as long as we don't have styles in
+  // place this doesn't make much sense.
   public View create(Element elem)
   {
     return new PlainView(elem);
   }
 
+  /**
+   * Returns the property prefix to be used by this UI class. This is
+   * <code>EditorPane</code> in this case.
+   *
+   * @return <code>EditorPane</code>
+   */
   protected String getPropertyPrefix()
   {
     return "EditorPane";
Index: javax/swing/plaf/basic/BasicTextUI.java
===================================================================
RCS file: /cvsroot/classpath/classpath/javax/swing/plaf/basic/BasicTextUI.java,v
retrieving revision 1.28
diff -u -r1.28 BasicTextUI.java
--- javax/swing/plaf/basic/BasicTextUI.java     29 Jul 2005 11:06:27 -0000      
1.28
+++ javax/swing/plaf/basic/BasicTextUI.java     29 Jul 2005 14:12:14 -0000
@@ -78,10 +78,20 @@
 import javax.swing.text.View;
 import javax.swing.text.ViewFactory;
 
-
+/**
+ * The abstract base class from which the UI classes for Swings text
+ * components are derived. This provides most of the functionality for
+ * the UI classes.
+ *
+ * @author original author unknown
+ * @author Roman Kennke (address@hidden)
+ */
 public abstract class BasicTextUI extends TextUI
   implements ViewFactory
 {
+  /**
+   * A address@hidden DefaultCaret} that implements address@hidden UIResource}.
+   */
   public static class BasicCaret extends DefaultCaret
     implements UIResource
   {
@@ -90,6 +100,9 @@
     }
   }
 
+  /**
+   * A address@hidden DefaultHighlighter} that implements address@hidden 
UIResource}.
+   */
   public static class BasicHighlighter extends DefaultHighlighter
     implements UIResource
   {
@@ -97,18 +110,35 @@
     {
     }
   }
-  
+
+  /**
+   * This view forms the root of the View hierarchy. However, it delegates
+   * most calls to another View which is the real root of the hierarchy.
+   * The purpose is to make sure that all Views in the hierarchy, including
+   * the (real) root have a well-defined parent to which they can delegate
+   * calls like address@hidden #preferenceChanged}, address@hidden 
#getViewFactory} and
+   * address@hidden #getContainer}.
+   */
   private class RootView extends View
   {
+    /** The real root view. */
     private View view;
-    
+
+    /**
+     * Creates a new RootView.
+     */
     public RootView()
     {
       super(null);
     }
 
-    // View methods.
-
+    /**
+     * Returns the ViewFactory for this RootView. If the current EditorKit
+     * provides a ViewFactory, this is used. Otherwise the TextUI itself
+     * is returned as a ViewFactory.
+     *
+     * @return the ViewFactory for this RootView
+     */
     public ViewFactory getViewFactory()
     {
       ViewFactory factory = null;
@@ -119,6 +149,11 @@
       return factory;
     }
 
+    /**
+     * Sets the real root view.
+     *
+     * @param v the root view to set
+     */
     public void setView(View v)
     {
       if (view != null)
@@ -130,11 +165,25 @@
       view = v;
     }
 
+    /**
+     * Returns the <code>Container</code> that contains this view. This
+     * normally will be the text component that is managed by this TextUI.
+     *
+     * @return the <code>Container</code> that contains this view
+     */
     public Container getContainer()
     {
       return textComponent;
     }
-    
+
+    /**
+     * Returns the preferred span along the specified <code>axis</code>.
+     * This is delegated to the real root view.
+     *
+     * @param axis the axis for which the preferred span is queried
+     *
+     * @return the preferred span along the axis
+     */
     public float getPreferredSpan(int axis)
     {
       if (view != null)
@@ -143,12 +192,40 @@
       return Integer.MAX_VALUE;
     }
 
+    /**
+     * Paints the view. This is delegated to the real root view.
+     *
+     * @param g the <code>Graphics</code> context to paint to
+     * @param s the allocation for the View
+     */
     public void paint(Graphics g, Shape s)
     {
       if (view != null)
        view.paint(g, s);
     }
 
+
+    /**
+     * Maps a position in the document into the coordinate space of the View.
+     * The output rectangle usually reflects the font height but has a width
+     * of zero.
+     *
+     * This is delegated to the real root view.
+     *
+     * @param pos the position of the character in the model
+     * @param a the area that is occupied by the view
+     * @param bias either address@hidden Position.Bias.Forward} or
+     *        address@hidden Position.Bias.Backward} depending on the preferred
+     *        direction bias. If <code>null</code> this defaults to
+     *        <code>Position.Bias.Forward</code>
+     *
+     * @return a rectangle that gives the location of the document position
+     *         inside the view coordinate space
+     *
+     * @throws BadLocationException if <code>pos</code> is invalid
+     * @throws IllegalArgumentException if b is not one of the above listed
+     *         valid values
+     */
     public Shape modelToView(int position, Shape a, Position.Bias bias)
       throws BadLocationException
     {
@@ -198,8 +275,16 @@
     }
   }
 
+  /**
+   * Receives notifications when properties of the text component change.
+   */
   class UpdateHandler implements PropertyChangeListener
   {
+    /**
+     * Notifies when a property of the text component changes.
+     *
+     * @param event the PropertyChangeEvent describing the change
+     */
     public void propertyChange(PropertyChangeEvent event)
     {
       if (event.getPropertyName().equals("document"))
@@ -261,34 +346,73 @@
     }
   }
 
+  /**
+   * The EditorKit used by this TextUI.
+   */
+  // FIXME: should probably be non-static.
   static EditorKit kit = new DefaultEditorKit();
 
+  /**
+   * The root view.
+   */
   RootView rootView = new RootView();
+
+  /**
+   * The text component that we handle.
+   */
   JTextComponent textComponent;
+
+  /**
+   * Receives notification when the model changes.
+   */
   UpdateHandler updateHandler = new UpdateHandler();
 
   /** The DocumentEvent handler. */
   DocumentHandler documentHandler = new DocumentHandler();
 
+  /**
+   * Creates a new <code>BasicTextUI</code> instance.
+   */
   public BasicTextUI()
   {
   }
 
+  /**
+   * Creates a address@hidden Caret} that should be installed into the text 
component.
+   *
+   * @return a caret that should be installed into the text component
+   */
   protected Caret createCaret()
   {
     return new BasicCaret();
   }
 
+  /**
+   * Creates a address@hidden Highlighter} that should be installed into the 
text
+   * component.
+   *
+   * @return a <code>Highlighter</code> for the text component
+   */
   protected Highlighter createHighlighter()
   {
     return new BasicHighlighter();
   }
-  
+
+  /**
+   * The text component that is managed by this UI.
+   *
+   * @return the text component that is managed by this UI
+   */
   protected final JTextComponent getComponent()
   {
     return textComponent;
   }
-  
+
+  /**
+   * Installs this UI on the text component.
+   *
+   * @param c the text component on which to install the UI
+   */
   public void installUI(final JComponent c)
   {
     super.installUI(c);
@@ -311,6 +435,9 @@
     installKeyboardActions();
   }
 
+  /**
+   * Installs UI defaults on the text components.
+   */
   protected void installDefaults()
   {
     Caret caret = textComponent.getCaret();
@@ -335,6 +462,9 @@
     caret.setBlinkRate(defaults.getInt(prefix + ".caretBlinkRate"));
   }
 
+  /**
+   * This FocusListener triggers repaints on focus shift.
+   */
   private FocusListener focuslistener = new FocusListener() {
       public void focusGained(FocusEvent e) 
       {
@@ -346,6 +476,9 @@
       }
     };
 
+  /**
+   * Install all listeners on the text component.
+   */
   protected void installListeners()
   {
     textComponent.addFocusListener(focuslistener);
@@ -379,6 +512,11 @@
     return className;
   }
 
+  /**
+   * Creates the address@hidden Keymap} that is installed on the text 
component.
+   *
+   * @return the address@hidden Keymap} that is installed on the text component
+   */
   protected Keymap createKeymap()
   {
     String prefix = getPropertyPrefix();
@@ -397,6 +535,9 @@
     return km;    
   }
 
+  /**
+   * Installs the keyboard actions on the text components.
+   */
   protected void installKeyboardActions()
   {    
     // load any bindings for the older Keymap interface
@@ -412,6 +553,13 @@
     SwingUtilities.replaceUIActionMap(textComponent, getActionMap());
   }
 
+  /**
+   * Gets the input map for the specified <code>condition</code>.
+   *
+   * @param condition the condition for the InputMap
+   *
+   * @return the InputMap for the specified condition
+   */
   InputMap getInputMap(int condition)
   {
     String prefix = getPropertyPrefix();
@@ -429,6 +577,13 @@
       }
   }
 
+  /**
+   * Returns the ActionMap to be installed on the text component.
+   *
+   * @return the ActionMap to be installed on the text component
+   */
+  // FIXME: The UIDefaults have no entries for .actionMap, so this should
+  // be handled somehow different.
   ActionMap getActionMap()
   {
     String prefix = getPropertyPrefix();
@@ -442,6 +597,11 @@
     return am;
   }
 
+  /**
+   * Creates an ActionMap to be installed on the text component.
+   *
+   * @return an ActionMap to be installed on the text component
+   */
   ActionMap createActionMap()
   {
     Action[] actions = textComponent.getActions();
@@ -455,6 +615,11 @@
     return am;
   }
 
+  /**
+   * Uninstalls this TextUI from the text component.
+   *
+   * @param component the text component to uninstall the UI from
+   */
   public void uninstallUI(final JComponent component)
   {
     super.uninstallUI(component);
@@ -469,23 +634,49 @@
     textComponent = null;
   }
 
+  /**
+   * Uninstalls all default properties that have previously been installed by
+   * this UI.
+   */
   protected void uninstallDefaults()
   {
     // Do nothing here.
   }
 
+  /**
+   * Uninstalls all listeners that have previously been installed by
+   * this UI.
+   */
   protected void uninstallListeners()
   {
     textComponent.removeFocusListener(focuslistener);
   }
 
+  /**
+   * Uninstalls all keyboard actions that have previously been installed by
+   * this UI.
+   */
   protected void uninstallKeyboardActions()
   {
-    // Do nothing here.
+    // FIXME: Uninstall keyboard actions here.
   }
-  
+
+  /**
+   * Returns the property prefix by which the text component's UIDefaults
+   * are looked up.
+   *
+   * @return the property prefix by which the text component's UIDefaults
+   *     are looked up
+   */
   protected abstract String getPropertyPrefix();
 
+  /**
+   * Returns the preferred size of the text component.
+   *
+   * @param c not used here
+   *
+   * @return the preferred size of the text component
+   */
   public Dimension getPreferredSize(JComponent c)
   {
     View v = getRootView(textComponent);
@@ -501,6 +692,8 @@
    *
    * This returns (Integer.MAX_VALUE, Integer.MAX_VALUE).
    *
+   * @param c not used here
+   *
    * @return the maximum size for text components that use this UI
    */
   public Dimension getMaximumSize(JComponent c)
@@ -509,11 +702,22 @@
     return new Dimension(Integer.MAX_VALUE, Integer.MAX_VALUE);
   }
 
+  /**
+   * Paints the text component.
+   *
+   * @param g the <code>Graphics</code> context to paint to
+   * @param c not used here
+   */
   public final void paint(Graphics g, JComponent c)
   {
     paintSafely(g);
   }
 
+  /**
+   * Actually performs the painting.
+   *
+   * @param g the <code>Graphics</code> context to paint to
+   */
   protected void paintSafely(Graphics g)
   {
     Caret caret = textComponent.getCaret();
@@ -532,74 +736,213 @@
       caret.paint(g);
   }
 
+  /**
+   * Paints the background of the text component.
+   *
+   * @param g the <code>Graphics</code> context to paint to
+   */
   protected void paintBackground(Graphics g)
   {
     g.setColor(textComponent.getBackground());
     g.fillRect(0, 0, textComponent.getWidth(), textComponent.getHeight());
   }
 
+  /**
+   * Marks the specified range inside the text component's model as
+   * damaged and queues a repaint request.
+   *
+   * @param t the text component
+   * @param p0 the start location inside the document model of the range that
+   *        is damaged
+   * @param p1 the end location inside the document model of the range that
+   *        is damaged
+   */
   public void damageRange(JTextComponent t, int p0, int p1)
   {
     damageRange(t, p0, p1, null, null);
   }
 
+  /**
+   * Marks the specified range inside the text component's model as
+   * damaged and queues a repaint request. This variant of this method
+   * allows a address@hidden Position.Bias} object to be specified for the 
start
+   * and end location of the range.
+   *
+   * @param t the text component
+   * @param p0 the start location inside the document model of the range that
+   *        is damaged
+   * @param p1 the end location inside the document model of the range that
+   *        is damaged
+   * @param firstBias the bias for the start location
+   * @param secondBias the bias for the end location
+   */
   public void damageRange(JTextComponent t, int p0, int p1,
                           Position.Bias firstBias, Position.Bias secondBias)
   {
+    // TODO: Implement me.
   }
 
+  /**
+   * Returns the address@hidden EditorKit} used for the text component that is 
managed
+   * by this UI.
+   *
+   * @param t the text component
+   *
+   * @return the address@hidden EditorKit} used for the text component that is 
managed
+   *         by this UI
+   */
   public EditorKit getEditorKit(JTextComponent t)
   {
     return kit;
   }
 
+  /**
+   * Gets the next position inside the document model that is visible on
+   * screen, starting from <code>pos</code>.
+   *
+   * @param t the text component
+   * @param pos the start positionn
+   * @param b the bias for pos
+   * @param direction the search direction
+   * @param biasRet filled by the method to indicate the bias of the return
+   *        value
+   *
+   * @return the next position inside the document model that is visible on
+   *         screen
+   */
   public int getNextVisualPositionFrom(JTextComponent t, int pos,
                                        Position.Bias b, int direction,
                                        Position.Bias[] biasRet)
     throws BadLocationException
   {
-    return 0;
+    return 0; // TODO: Implement me.
   }
 
+  /**
+   * Returns the root address@hidden View} of a text component.
+   *
+   * @return the root address@hidden View} of a text component
+   */
   public View getRootView(JTextComponent t)
   {
     return rootView;
   }
 
+  /**
+   * Maps a position in the document into the coordinate space of the View.
+   * The output rectangle usually reflects the font height but has a width
+   * of zero. A bias of address@hidden Position.Bias.Forward} is used in this 
method.
+   *
+   * @param pos the position of the character in the model
+   * @param a the area that is occupied by the view
+   *
+   * @return a rectangle that gives the location of the document position
+   *         inside the view coordinate space
+   *
+   * @throws BadLocationException if <code>pos</code> is invalid
+   * @throws IllegalArgumentException if b is not one of the above listed
+   *         valid values
+   */
   public Rectangle modelToView(JTextComponent t, int pos)
     throws BadLocationException
   {
     return modelToView(t, pos, Position.Bias.Forward);
   }
 
+  /**
+   * Maps a position in the document into the coordinate space of the View.
+   * The output rectangle usually reflects the font height but has a width
+   * of zero.
+   *
+   * @param pos the position of the character in the model
+   * @param a the area that is occupied by the view
+   * @param bias either address@hidden Position.Bias.Forward} or
+   *        address@hidden Position.Bias.Backward} depending on the preferred
+   *        direction bias. If <code>null</code> this defaults to
+   *        <code>Position.Bias.Forward</code>
+   *
+   * @return a rectangle that gives the location of the document position
+   *         inside the view coordinate space
+   *
+   * @throws BadLocationException if <code>pos</code> is invalid
+   * @throws IllegalArgumentException if b is not one of the above listed
+   *         valid values
+   */
   public Rectangle modelToView(JTextComponent t, int pos, Position.Bias bias)
     throws BadLocationException
   {
     return rootView.modelToView(pos, getVisibleEditorRect(), bias).getBounds();
   }
 
+  /**
+   * Maps a point in the <code>View</code> coordinate space to a position
+   * inside a document model.
+   *
+   * @param t the text component
+   * @param pt the point to be mapped
+   *
+   * @return the position inside the document model that corresponds to
+   *     <code>pt</code>
+   */
   public int viewToModel(JTextComponent t, Point pt)
   {
     return viewToModel(t, pt, null);
   }
 
+  /**
+   * Maps a point in the <code>View</code> coordinate space to a position
+   * inside a document model.
+   *
+   * @param t the text component
+   * @param pt the point to be mapped
+   * @param biasReturn filled in by the method to indicate the bias of the
+   *        return value
+   *
+   * @return the position inside the document model that corresponds to
+   *     <code>pt</code>
+   */
   public int viewToModel(JTextComponent t, Point pt, Position.Bias[] 
biasReturn)
   {
-    return 0;
+    return 0; // FIXME: Implement me.
   }
 
+  /**
+   * Creates a address@hidden View} for the specified address@hidden Element}.
+   *
+   * @param elem the <code>Element</code> to create a <code>View</code> for
+   *
+   * @see ViewFactory
+   */
   public View create(Element elem)
   {
     // Subclasses have to implement this to get this functionality.
     return null;
   }
 
+  /**
+   * Creates a address@hidden View} for the specified address@hidden Element}.
+   *
+   * @param elem the <code>Element</code> to create a <code>View</code> for
+   * @param p0 the start offset
+   * @param p1 the end offset
+   *
+   * @see ViewFactory
+   */
   public View create(Element elem, int p0, int p1)
   {
     // Subclasses have to implement this to get this functionality.
     return null;
   }
-  
+
+  /**
+   * Returns the allocation to give the root view.
+   *
+   * @return the allocation to give the root view
+   *
+   * @specnote The allocation has nothing to do with visibility. According
+   *           to the specs the naming of this method is unfortunate and
+   *           has historical reasons
+   */
   protected Rectangle getVisibleEditorRect()
   {
     int width = textComponent.getWidth();
@@ -614,11 +957,20 @@
                         height - insets.top + insets.bottom);
   }
 
+  /**
+   * Sets the root view for the text component.
+   *
+   * @param view the <code>View</code> to be set as root view
+   */
   protected final void setView(View view)
   {
     rootView.setView(view);
   }
 
+  /**
+   * Indicates that the model of a text component has changed. This
+   * triggers a rebuild of the view hierarchy.
+   */
   protected void modelChanged()
   {
     if (textComponent == null || rootView == null)