[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[cp-patches] FYI: API for javax.swing.text classes
From: |
Roman Kennke |
Subject: |
[cp-patches] FYI: API for javax.swing.text classes |
Date: |
Fri, 29 Jul 2005 16:14:02 +0200 |
User-agent: |
Mozilla Thunderbird 1.0.2 (X11/20050317) |
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)
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [cp-patches] FYI: API for javax.swing.text classes,
Roman Kennke <=