From 61b92329697c34a6f0e13a70ffb6e651e5b89c1b Mon Sep 17 00:00:00 2001 From: Andrei Eremeev Date: Thu, 10 Jul 2014 12:21:29 +0400 Subject: [PATCH] 8049704: Fix doclint warnings from javax.swing.plaf.basic package, 2 of 7 Reviewed-by: pchelko --- .../javax/swing/plaf/basic/BasicButtonUI.java | 104 +++++++++++++++- .../swing/plaf/basic/BasicComboBoxUI.java | 66 ++++++++-- .../swing/plaf/basic/BasicComboPopup.java | 52 ++++++++ .../swing/plaf/basic/BasicDesktopIconUI.java | 61 ++++++++- .../javax/swing/plaf/basic/BasicLabelUI.java | 82 +++++++++++-- .../swing/plaf/basic/BasicScrollPaneUI.java | 116 +++++++++++++++--- .../plaf/basic/BasicSplitPaneDivider.java | 85 ++++++++++--- .../javax/swing/plaf/basic/BasicTableUI.java | 46 ++++++- 8 files changed, 556 insertions(+), 56 deletions(-) diff --git a/jdk/src/share/classes/javax/swing/plaf/basic/BasicButtonUI.java b/jdk/src/share/classes/javax/swing/plaf/basic/BasicButtonUI.java index 34595149b95..0e1aa403fac 100644 --- a/jdk/src/share/classes/javax/swing/plaf/basic/BasicButtonUI.java +++ b/jdk/src/share/classes/javax/swing/plaf/basic/BasicButtonUI.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1997, 2008, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1997, 2014, 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 @@ -49,6 +49,9 @@ public class BasicButtonUI extends ButtonUI{ // Visual constants // NOTE: This is not used or set any where. Were we allowed to remove // fields, this would be removed. + /** + * The default gap between a text and an icon. + */ protected int defaultTextIconGap; // Amount to offset text, the value of this comes from @@ -56,6 +59,9 @@ public class BasicButtonUI extends ButtonUI{ private int shiftOffset = 0; // Value that is set in shiftOffset once setTextShiftOffset has been // invoked. The value of this comes from the defaults table. + /** + * The default offset of a text. + */ protected int defaultTextShiftOffset; private final static String propertyPrefix = "Button" + "."; @@ -65,6 +71,12 @@ public class BasicButtonUI extends ButtonUI{ // ******************************** // Create PLAF // ******************************** + /** + * Returns an instance of {@code BasicButtonUI}. + * + * @param c a component + * @return an instance of {@code BasicButtonUI} + */ public static ComponentUI createUI(JComponent c) { AppContext appContext = AppContext.getAppContext(); BasicButtonUI buttonUI = @@ -76,6 +88,11 @@ public class BasicButtonUI extends ButtonUI{ return buttonUI; } + /** + * Returns the property prefix. + * + * @return the property prefix + */ protected String getPropertyPrefix() { return propertyPrefix; } @@ -91,6 +108,11 @@ public class BasicButtonUI extends ButtonUI{ BasicHTML.updateRenderer(c, ((AbstractButton) c).getText()); } + /** + * Installs default properties. + * + * @param b an abstract button + */ protected void installDefaults(AbstractButton b) { // load shared instance defaults String pp = getPropertyPrefix(); @@ -120,6 +142,11 @@ public class BasicButtonUI extends ButtonUI{ LookAndFeel.installProperty(b, "iconTextGap", Integer.valueOf(4)); } + /** + * Registers listeners. + * + * @param b an abstract button + */ protected void installListeners(AbstractButton b) { BasicButtonListener listener = createButtonListener(b); if(listener != null) { @@ -131,6 +158,11 @@ public class BasicButtonUI extends ButtonUI{ } } + /** + * Registers keyboard actions. + * + * @param b an abstract button + */ protected void installKeyboardActions(AbstractButton b){ BasicButtonListener listener = getButtonListener(b); @@ -150,6 +182,11 @@ public class BasicButtonUI extends ButtonUI{ BasicHTML.updateRenderer(c, ""); } + /** + * Unregisters keyboard actions. + * + * @param b an abstract button + */ protected void uninstallKeyboardActions(AbstractButton b) { BasicButtonListener listener = getButtonListener(b); if(listener != null) { @@ -157,6 +194,11 @@ public class BasicButtonUI extends ButtonUI{ } } + /** + * Unregisters listeners. + * + * @param b an abstract button + */ protected void uninstallListeners(AbstractButton b) { BasicButtonListener listener = getButtonListener(b); if(listener != null) { @@ -168,6 +210,11 @@ public class BasicButtonUI extends ButtonUI{ } } + /** + * Uninstalls default properties. + * + * @param b an abstract button + */ protected void uninstallDefaults(AbstractButton b) { LookAndFeel.uninstallBorder(b); } @@ -175,10 +222,22 @@ public class BasicButtonUI extends ButtonUI{ // ******************************** // Create Listeners // ******************************** + /** + * Returns a new instance of {@code BasicButtonListener}. + * + * @param b an abstract button + * @return a new instance of {@code BasicButtonListener} + */ protected BasicButtonListener createButtonListener(AbstractButton b) { return new BasicButtonListener(b); } + /** + * Returns the default gap between a text and an icon. + * + * @param b an abstract button + * @return the default gap between text and an icon + */ public int getDefaultTextIconGap(AbstractButton b) { return defaultTextIconGap; } @@ -231,6 +290,13 @@ public class BasicButtonUI extends ButtonUI{ } } + /** + * Paints an icon of the current button. + * + * @param g an instance of {@code Graphics} + * @param c a component + * @param iconRect a bounding rectangle to render the icon + */ protected void paintIcon(Graphics g, JComponent c, Rectangle iconRect){ AbstractButton b = (AbstractButton) c; ButtonModel model = b.getModel(); @@ -295,8 +361,15 @@ public class BasicButtonUI extends ButtonUI{ } /** + * Method which renders the text of the current button. + * * As of Java 2 platform v 1.4 this method should not be used or overriden. * Use the paintText method which takes the AbstractButton argument. + * + * @param g an instance of {@code Graphics} + * @param c a component + * @param textRect a bounding rectangle to render the text + * @param text a string to render */ protected void paintText(Graphics g, JComponent c, Rectangle textRect, String text) { AbstractButton b = (AbstractButton) c; @@ -328,7 +401,7 @@ public class BasicButtonUI extends ButtonUI{ * * @param g Graphics context * @param b Current button to render - * @param textRect Bounding rectangle to render the text. + * @param textRect Bounding rectangle to render the text * @param text String to render * @since 1.4 */ @@ -338,23 +411,48 @@ public class BasicButtonUI extends ButtonUI{ // Method signature defined here overriden in subclasses. // Perhaps this class should be abstract? + /** + * Paints a focused button. + * + * @param g an instance of {@code Graphics} + * @param b an abstract button + * @param viewRect a bounding rectangle to render the button + * @param textRect a bounding rectangle to render the text + * @param iconRect a bounding rectangle to render the icon + */ protected void paintFocus(Graphics g, AbstractButton b, Rectangle viewRect, Rectangle textRect, Rectangle iconRect){ } - + /** + * Paints a pressed button. + * + * @param g an instance of {@code Graphics} + * @param b an abstract button + */ protected void paintButtonPressed(Graphics g, AbstractButton b){ } + /** + * Clears the offset of the text. + */ protected void clearTextShiftOffset(){ this.shiftOffset = 0; } + /** + * Sets the offset of the text. + */ protected void setTextShiftOffset(){ this.shiftOffset = defaultTextShiftOffset; } + /** + * Returns the offset of the text. + * + * @return the offset of the text + */ protected int getTextShiftOffset() { return shiftOffset; } diff --git a/jdk/src/share/classes/javax/swing/plaf/basic/BasicComboBoxUI.java b/jdk/src/share/classes/javax/swing/plaf/basic/BasicComboBoxUI.java index de26e386efd..a144ce120e7 100644 --- a/jdk/src/share/classes/javax/swing/plaf/basic/BasicComboBoxUI.java +++ b/jdk/src/share/classes/javax/swing/plaf/basic/BasicComboBoxUI.java @@ -61,6 +61,10 @@ import sun.swing.UIAction; * @author Mark Davidson */ public class BasicComboBoxUI extends ComboBoxUI { + + /** + * The instance of {@code JComboBox}. + */ protected JComboBox comboBox; /** * This protected field is implementation specific. Do not access directly @@ -73,20 +77,30 @@ public class BasicComboBoxUI extends ComboBoxUI { private boolean isTableCellEditor = false; private static final String IS_TABLE_CELL_EDITOR = "JComboBox.isTableCellEditor"; - // This list is for drawing the current item in the combo box. + /** + * This list is for drawing the current item in the combo box. + */ protected JList listBox; - // Used to render the currently selected item in the combo box. - // It doesn't have anything to do with the popup's rendering. + /** + * Used to render the currently selected item in the combo box. + * It doesn't have anything to do with the popup's rendering. + */ protected CellRendererPane currentValuePane = new CellRendererPane(); - // The implementation of ComboPopup that is used to show the popup. + /** + * The implementation of {@code ComboPopup} that is used to show the popup. + */ protected ComboPopup popup; - // The Component that the ComboBoxEditor uses for editing + /** + * The Component that the @{code ComboBoxEditor} uses for editing. + */ protected Component editor; - // The arrow button that invokes the popup. + /** + * The arrow button that invokes the popup. + */ protected JButton arrowButton; // Listeners that are attached to the JComboBox @@ -121,8 +135,19 @@ public class BasicComboBoxUI extends ComboBoxUI { protected ItemListener itemListener; // Listeners that the ComboPopup produces. + /** + * The {@code MouseListener} listens to events. + */ protected MouseListener popupMouseListener; + + /** + * The {@code MouseMotionListener} listens to events. + */ protected MouseMotionListener popupMouseMotionListener; + + /** + * The {@code KeyListener} listens to events. + */ protected KeyListener popupKeyListener; // This is used for knowing when to cache the minimum preferred size. @@ -160,10 +185,14 @@ public class BasicComboBoxUI extends ComboBoxUI { */ JComboBox.KeySelectionManager keySelectionManager; - // Flag for recalculating the minimum preferred size. + /** + * The flag for recalculating the minimum preferred size. + */ protected boolean isMinimumSizeDirty = true; - // Cached minimum preferred size. + /** + * The cached minimum preferred size. + */ protected Dimension cachedMinimumSize = new Dimension( 0, 0 ); // Flag for calculating the display size @@ -238,6 +267,12 @@ public class BasicComboBoxUI extends ComboBoxUI { // begin UI Initialization // + /** + * Constructs a new instance of {@code BasicComboBoxUI}. + * + * @param c a component + * @return a new instance of {@code BasicComboBoxUI} + */ public static ComponentUI createUI(JComponent c) { return new BasicComboBoxUI(); } @@ -1090,6 +1125,9 @@ public class BasicComboBoxUI extends ComboBoxUI { * navigation. This is used for optimizing key input by only passing non- * navigation keys to the type-ahead mechanism. Subclasses should override this * if they change the navigation keys. + * + * @param keyCode a key code + * @return {@code true} if the supplied {@code keyCode} maps to a navigation key */ protected boolean isNavigationKey( int keyCode ) { return keyCode == KeyEvent.VK_UP || keyCode == KeyEvent.VK_DOWN || @@ -1167,6 +1205,8 @@ public class BasicComboBoxUI extends ComboBoxUI { /** * Returns the area that is reserved for drawing the currently selected item. + * + * @return the area that is reserved for drawing the currently selected item */ protected Rectangle rectangleForCurrentValue() { int width = comboBox.getWidth(); @@ -1190,6 +1230,8 @@ public class BasicComboBoxUI extends ComboBoxUI { /** * Gets the insets from the JComboBox. + * + * @return the insets */ protected Insets getInsets() { return comboBox.getInsets(); @@ -1206,6 +1248,10 @@ public class BasicComboBoxUI extends ComboBoxUI { /** * Paints the currently selected item. + * + * @param g an instance of {@code Graphics} + * @param bounds a bounding rectangle to render to + * @param hasFocus is focused */ public void paintCurrentValue(Graphics g,Rectangle bounds,boolean hasFocus) { ListCellRenderer renderer = comboBox.getRenderer(); @@ -1263,6 +1309,10 @@ public class BasicComboBoxUI extends ComboBoxUI { /** * Paints the background of the currently selected item. + * + * @param g an instance of {@code Graphics} + * @param bounds a bounding rectangle to render to + * @param hasFocus is focused */ public void paintCurrentValueBackground(Graphics g,Rectangle bounds,boolean hasFocus) { Color t = g.getColor(); diff --git a/jdk/src/share/classes/javax/swing/plaf/basic/BasicComboPopup.java b/jdk/src/share/classes/javax/swing/plaf/basic/BasicComboPopup.java index 2f0cd03923d..9e06857d4b3 100644 --- a/jdk/src/share/classes/javax/swing/plaf/basic/BasicComboPopup.java +++ b/jdk/src/share/classes/javax/swing/plaf/basic/BasicComboPopup.java @@ -75,6 +75,9 @@ public class BasicComboPopup extends JPopupMenu implements ComboPopup { private static Border LIST_BORDER = new LineBorder(Color.BLACK, 1); + /** + * The instance of {@code JComboBox}. + */ protected JComboBox comboBox; /** * This protected field is implementation specific. Do not access directly @@ -186,11 +189,30 @@ public class BasicComboPopup extends JPopupMenu implements ComboPopup { * or override. */ protected Timer autoscrollTimer; + + /** + * {@code true} if the mouse cursor is in the popup. + */ protected boolean hasEntered = false; + + /** + * If {@code true} the auto-scrolling is enabled. + */ protected boolean isAutoScrolling = false; + + /** + * The direction of scrolling. + */ protected int scrollDirection = SCROLL_UP; + /** + * The direction of scrolling up. + */ protected static final int SCROLL_UP = 0; + + /** + * The direction of scrolling down. + */ protected static final int SCROLL_DOWN = 1; @@ -309,6 +331,9 @@ public class BasicComboPopup extends JPopupMenu implements ComboPopup { } } + /** + * Unregisters keyboard actions. + */ protected void uninstallKeyboardActions() { // XXX - shouldn't call this method // comboBox.unregisterKeyboardAction( KeyStroke.getKeyStroke( KeyEvent.VK_ENTER, 0 ) ); @@ -319,6 +344,12 @@ public class BasicComboPopup extends JPopupMenu implements ComboPopup { //=================================================================== // begin Initialization routines // + + /** + * Constructs a new instance of {@code BasicComboPopup}. + * + * @param combo an instance of {@code JComboBox} + */ public BasicComboPopup( JComboBox combo ) { super(); setName("ComboPopup.popup"); @@ -555,6 +586,8 @@ public class BasicComboPopup extends JPopupMenu implements ComboPopup { /** * Creates the scroll pane which houses the scrollable list. + * + * @return the scroll pane which houses the scrollable list */ protected JScrollPane createScroller() { JScrollPane sp = new JScrollPane( list, @@ -616,6 +649,9 @@ public class BasicComboPopup extends JPopupMenu implements ComboPopup { } } + /** + * Registers keyboard actions. + */ protected void installKeyboardActions() { /* XXX - shouldn't call this method. take it out for testing. @@ -1007,6 +1043,8 @@ public class BasicComboPopup extends JPopupMenu implements ComboPopup { /** * This protected method is implementation specific and should be private. * do not call or override. + * + * @param direction the direction of scrolling */ protected void startAutoScrolling( int direction ) { // XXX - should be a private method within InvocationMouseMotionHandler @@ -1107,6 +1145,8 @@ public class BasicComboPopup extends JPopupMenu implements ComboPopup { * send the focus when the popup is brought up. The standard implementation * delegates the focus to the editor (if the combo box is editable) or to * the JComboBox if it is not editable. + * + * @param e a mouse event */ protected void delegateFocus( MouseEvent e ) { if ( comboBox.isEditable() ) { @@ -1150,6 +1190,12 @@ public class BasicComboPopup extends JPopupMenu implements ComboPopup { } } + /** + * Converts mouse event. + * + * @param e a mouse event + * @return converted mouse event + */ protected MouseEvent convertMouseEvent( MouseEvent e ) { Point convertedPoint = SwingUtilities.convertPoint( (Component)e.getSource(), e.getPoint(), list ); @@ -1171,6 +1217,9 @@ public class BasicComboPopup extends JPopupMenu implements ComboPopup { /** * Retrieves the height of the popup based on the current * ListCellRenderer and the maximum row count. + * + * @param maxRowCount the row count + * @return the height of the popup */ protected int getPopupHeightForRowCount(int maxRowCount) { // Set the cached value of the minimum row count @@ -1272,6 +1321,9 @@ public class BasicComboPopup extends JPopupMenu implements ComboPopup { /** * A utility method used by the event listeners. Given a mouse event, it changes * the list selection to the list item below the mouse. + * + * @param anEvent a mouse event + * @param shouldScroll if {@code true} list should be scrolled. */ protected void updateListBoxSelectionForEvent(MouseEvent anEvent,boolean shouldScroll) { // XXX - only seems to be called from this class. shouldScroll flag is diff --git a/jdk/src/share/classes/javax/swing/plaf/basic/BasicDesktopIconUI.java b/jdk/src/share/classes/javax/swing/plaf/basic/BasicDesktopIconUI.java index 8d68668af6a..262f36ee7d8 100644 --- a/jdk/src/share/classes/javax/swing/plaf/basic/BasicDesktopIconUI.java +++ b/jdk/src/share/classes/javax/swing/plaf/basic/BasicDesktopIconUI.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1997, 2014, 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 @@ -42,7 +42,14 @@ import java.beans.*; */ public class BasicDesktopIconUI extends DesktopIconUI { + /** + * The instance of {@code JInternalFrame.JDesktopIcon}. + */ protected JInternalFrame.JDesktopIcon desktopIcon; + + /** + * The instance of {@code JInternalFrame}. + */ protected JInternalFrame frame; /** @@ -53,12 +60,19 @@ public class BasicDesktopIconUI extends DesktopIconUI { protected JComponent iconPane; MouseInputListener mouseInputListener; - - + /** + * Constructs a new instance of {@code BasicDesktopIconUI}. + * + * @param c a component + * @return a new instance of {@code BasicDesktopIconUI} + */ public static ComponentUI createUI(JComponent c) { return new BasicDesktopIconUI(); } + /** + * Constructs a new instance of {@code BasicDesktopIconUI}. + */ public BasicDesktopIconUI() { } @@ -108,39 +122,62 @@ public class BasicDesktopIconUI extends DesktopIconUI { desktopIcon = null; } + /** + * Registers components. + */ protected void installComponents() { iconPane = new BasicInternalFrameTitlePane(frame); desktopIcon.setLayout(new BorderLayout()); desktopIcon.add(iconPane, BorderLayout.CENTER); } + /** + * Unregisters components. + */ protected void uninstallComponents() { desktopIcon.remove(iconPane); desktopIcon.setLayout(null); iconPane = null; } + /** + * Registers listeners. + */ protected void installListeners() { mouseInputListener = createMouseInputListener(); desktopIcon.addMouseMotionListener(mouseInputListener); desktopIcon.addMouseListener(mouseInputListener); } + /** + * Unregisters listeners. + */ protected void uninstallListeners() { desktopIcon.removeMouseMotionListener(mouseInputListener); desktopIcon.removeMouseListener(mouseInputListener); mouseInputListener = null; } + /** + * Installs default properties. + */ protected void installDefaults() { LookAndFeel.installBorder(desktopIcon, "DesktopIcon.border"); LookAndFeel.installProperty(desktopIcon, "opaque", Boolean.TRUE); } + /** + * Uninstalls default properties. + */ protected void uninstallDefaults() { LookAndFeel.uninstallBorder(desktopIcon); } + /** + * Returns a new instance of {@code MouseInputListener}. + * + * @return a new instance of {@code MouseInputListener} + */ protected MouseInputListener createMouseInputListener() { return new MouseInputHandler(); } @@ -170,6 +207,12 @@ public class BasicDesktopIconUI extends DesktopIconUI { return iconPane.getMaximumSize(); } + /** + * Returns the insets. + * + * @param c a component + * @return the insets + */ public Insets getInsets(JComponent c) { JInternalFrame iframe = desktopIcon.getInternalFrame(); Border border = iframe.getBorder(); @@ -179,6 +222,9 @@ public class BasicDesktopIconUI extends DesktopIconUI { return new Insets(0,0,0,0); } + /** + * De-iconifies the internal frame. + */ public void deiconize() { try { frame.setIcon(false); } catch (PropertyVetoException e2) { } } @@ -284,6 +330,15 @@ public class BasicDesktopIconUI extends DesktopIconUI { return; } + /** + * Moves and repaints a component {@code f}. + * + * @param f a component + * @param newX a new X coordinate + * @param newY a new Y coordinate + * @param newWidth a new width + * @param newHeight a new height + */ public void moveAndRepaint(JComponent f, int newX, int newY, int newWidth, int newHeight) { Rectangle r = f.getBounds(); diff --git a/jdk/src/share/classes/javax/swing/plaf/basic/BasicLabelUI.java b/jdk/src/share/classes/javax/swing/plaf/basic/BasicLabelUI.java index 9c31265d180..e5576c2aca9 100644 --- a/jdk/src/share/classes/javax/swing/plaf/basic/BasicLabelUI.java +++ b/jdk/src/share/classes/javax/swing/plaf/basic/BasicLabelUI.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1997, 2014, 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 @@ -80,6 +80,14 @@ public class BasicLabelUI extends LabelUI implements PropertyChangeListener * This method is here so that a subclass could do Label specific * layout and to shorten the method name a little. * + * @param label an instance of {@code JLabel} + * @param fontMetrics a font metrics + * @param text a text + * @param icon an icon + * @param viewR a bounding rectangle to lay out label + * @param iconR a bounding rectangle to lay out icon + * @param textR a bounding rectangle to lay out text + * @return a possibly clipped version of the compound labels string * @see SwingUtilities#layoutCompoundLabel */ protected String layoutCL( @@ -109,6 +117,11 @@ public class BasicLabelUI extends LabelUI implements PropertyChangeListener /** * Paint clippedText at textX, textY with the labels foreground color. * + * @param l an instance of {@code JLabel} + * @param g an instance of {@code Graphics} + * @param s a text + * @param textX an X coordinate + * @param textY an Y coordinate * @see #paint * @see #paintDisabledText */ @@ -125,6 +138,11 @@ public class BasicLabelUI extends LabelUI implements PropertyChangeListener * Paint clippedText at textX, textY with background.lighter() and then * shifted down and to the right by one pixel with background.darker(). * + * @param l an instance of {@code JLabel} + * @param g an instance of {@code Graphics} + * @param s a text + * @param textX an X coordinate + * @param textY an Y coordinate * @see #paint * @see #paintEnabledText */ @@ -329,26 +347,46 @@ public class BasicLabelUI extends LabelUI implements PropertyChangeListener public void uninstallUI(JComponent c) { - uninstallDefaults((JLabel)c); - uninstallComponents((JLabel)c); - uninstallListeners((JLabel)c); - uninstallKeyboardActions((JLabel)c); + uninstallDefaults((JLabel) c); + uninstallComponents((JLabel) c); + uninstallListeners((JLabel) c); + uninstallKeyboardActions((JLabel) c); } - protected void installDefaults(JLabel c){ - LookAndFeel.installColorsAndFont(c, "Label.background", "Label.foreground", "Label.font"); - LookAndFeel.installProperty(c, "opaque", Boolean.FALSE); - } + /** + * Installs default properties. + * + * @param c an instance of {@code JLabel} + */ + protected void installDefaults(JLabel c){ + LookAndFeel.installColorsAndFont(c, "Label.background", "Label.foreground", "Label.font"); + LookAndFeel.installProperty(c, "opaque", Boolean.FALSE); + } + /** + * Registers listeners. + * + * @param c an instance of {@code JLabel} + */ protected void installListeners(JLabel c){ c.addPropertyChangeListener(this); } + /** + * Registers components. + * + * @param c an instance of {@code JLabel} + */ protected void installComponents(JLabel c){ BasicHTML.updateRenderer(c, c.getText()); c.setInheritsPopupMenu(true); } + /** + * Registers keyboard actions. + * + * @param l an instance of {@code JLabel} + */ protected void installKeyboardActions(JLabel l) { int dka = l.getDisplayedMnemonic(); Component lf = l.getLabelFor(); @@ -374,17 +412,37 @@ public class BasicLabelUI extends LabelUI implements PropertyChangeListener } } + /** + * Uninstalls default properties. + * + * @param c an instance of {@code JLabel} + */ protected void uninstallDefaults(JLabel c){ } + /** + * Unregisters listeners. + * + * @param c an instance of {@code JLabel} + */ protected void uninstallListeners(JLabel c){ c.removePropertyChangeListener(this); } + /** + * Unregisters components. + * + * @param c an instance of {@code JLabel} + */ protected void uninstallComponents(JLabel c){ BasicHTML.updateRenderer(c, ""); } + /** + * Unregisters keyboard actions. + * + * @param c an instance of {@code JLabel} + */ protected void uninstallKeyboardActions(JLabel c) { SwingUtilities.replaceUIInputMap(c, JComponent.WHEN_FOCUSED, null); SwingUtilities.replaceUIInputMap(c, JComponent.WHEN_IN_FOCUSED_WINDOW, @@ -392,6 +450,12 @@ public class BasicLabelUI extends LabelUI implements PropertyChangeListener SwingUtilities.replaceUIActionMap(c, null); } + /** + * Returns an instance of {@code BasicLabelUI}. + * + * @param c a component + * @return an instance of {@code BasicLabelUI} + */ public static ComponentUI createUI(JComponent c) { if (System.getSecurityManager() != null) { AppContext appContext = AppContext.getAppContext(); diff --git a/jdk/src/share/classes/javax/swing/plaf/basic/BasicScrollPaneUI.java b/jdk/src/share/classes/javax/swing/plaf/basic/BasicScrollPaneUI.java index 646282046b3..18df8abf202 100644 --- a/jdk/src/share/classes/javax/swing/plaf/basic/BasicScrollPaneUI.java +++ b/jdk/src/share/classes/javax/swing/plaf/basic/BasicScrollPaneUI.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1997, 2014, 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 @@ -52,21 +52,40 @@ import java.awt.event.*; public class BasicScrollPaneUI extends ScrollPaneUI implements ScrollPaneConstants { + /** + * The instance of {@code JScrollPane}. + */ protected JScrollPane scrollpane; + + /** + * {@code ChangeListener} installed on the vertical scrollbar. + */ protected ChangeListener vsbChangeListener; + + /** + * {@code ChangeListener} installed on the horizontal scrollbar. + */ protected ChangeListener hsbChangeListener; + + /** + * {@code ChangeListener} installed on the viewport. + */ protected ChangeListener viewportChangeListener; + + /** + * {@code PropertyChangeListener} installed on the scroll pane. + */ protected PropertyChangeListener spPropertyChangeListener; private MouseWheelListener mouseScrollListener; private int oldExtent = Integer.MIN_VALUE; /** - * PropertyChangeListener installed on the vertical scrollbar. + * {@code PropertyChangeListener} installed on the vertical scrollbar. */ private PropertyChangeListener vsbPropertyChangeListener; /** - * PropertyChangeListener installed on the horizontal scrollbar. + * {@code PropertyChangeListener} installed on the horizontal scrollbar. */ private PropertyChangeListener hsbPropertyChangeListener; @@ -79,7 +98,12 @@ public class BasicScrollPaneUI */ private boolean setValueCalled = false; - + /** + * Returns a new instance of {@code BasicScrollPaneUI}. + * + * @param x a component. + * @return a new instance of {@code BasicScrollPaneUI} + */ public static ComponentUI createUI(JComponent x) { return new BasicScrollPaneUI(); } @@ -115,7 +139,11 @@ public class BasicScrollPaneUI return new Dimension(Short.MAX_VALUE, Short.MAX_VALUE); } - + /** + * Installs default properties. + * + * @param scrollpane an instance of {@code JScrollPane} + */ protected void installDefaults(JScrollPane scrollpane) { LookAndFeel.installBorder(scrollpane, "ScrollPane.border"); @@ -132,7 +160,11 @@ public class BasicScrollPaneUI LookAndFeel.installProperty(scrollpane, "opaque", Boolean.TRUE); } - + /** + * Registers listeners. + * + * @param c an instance of {@code JScrollPane} + */ protected void installListeners(JScrollPane c) { vsbChangeListener = createVSBChangeListener(); @@ -165,6 +197,11 @@ public class BasicScrollPaneUI } + /** + * Registers keyboard actions. + * + * @param c an instance of {@code JScrollPane} + */ protected void installKeyboardActions(JScrollPane c) { InputMap inputMap = getInputMap(JComponent. WHEN_ANCESTOR_OF_FOCUSED_COMPONENT); @@ -201,7 +238,11 @@ public class BasicScrollPaneUI installKeyboardActions(scrollpane); } - + /** + * Uninstalls default properties. + * + * @param c an instance of {@code JScrollPane} + */ protected void uninstallDefaults(JScrollPane c) { LookAndFeel.uninstallBorder(scrollpane); @@ -210,7 +251,11 @@ public class BasicScrollPaneUI } } - + /** + * Unregisters listeners. + * + * @param c a component + */ protected void uninstallListeners(JComponent c) { JViewport viewport = scrollpane.getViewport(); JScrollBar vsb = scrollpane.getVerticalScrollBar(); @@ -242,7 +287,11 @@ public class BasicScrollPaneUI handler = null; } - + /** + * Unregisters keyboard actions. + * + * @param c an instance of {@code JScrollPane} + */ protected void uninstallKeyboardActions(JScrollPane c) { SwingUtilities.replaceUIActionMap(c, null); SwingUtilities.replaceUIInputMap(c, JComponent. @@ -264,6 +313,9 @@ public class BasicScrollPaneUI return handler; } + /** + * Synchronizes the {@code JScrollPane} with {@code Viewport}. + */ protected void syncScrollPaneWithViewport() { JViewport viewport = scrollpane.getViewport(); @@ -453,6 +505,11 @@ public class BasicScrollPaneUI } } + /** + * Returns an instance of viewport {@code ChangeListener}. + * + * @return an instance of viewport {@code ChangeListener} + */ protected ChangeListener createViewportChangeListener() { return getHandler(); } @@ -483,6 +540,11 @@ public class BasicScrollPaneUI return getHandler(); } + /** + * Returns an instance of horizontal scroll bar {@code ChangeListener}. + * + * @return an instance of horizontal scroll bar {@code ChangeListener} + */ protected ChangeListener createHSBChangeListener() { return getHandler(); } @@ -514,6 +576,11 @@ public class BasicScrollPaneUI return getHandler(); } + /** + * Returns an instance of vertical scroll bar {@code ChangeListener}. + * + * @return an instance of vertical scroll bar {@code ChangeListener} + */ protected ChangeListener createVSBChangeListener() { return getHandler(); } @@ -565,12 +632,21 @@ public class BasicScrollPaneUI return getHandler(); } + /** + * Updates a scroll bar display policy. + * + * @param e the property change event + */ protected void updateScrollBarDisplayPolicy(PropertyChangeEvent e) { scrollpane.revalidate(); scrollpane.repaint(); } - + /** + * Updates viewport. + * + * @param e the property change event + */ protected void updateViewport(PropertyChangeEvent e) { JViewport oldViewport = (JViewport)(e.getOldValue()); @@ -599,7 +675,11 @@ public class BasicScrollPaneUI } } - + /** + * Updates row header. + * + * @param e the property change event + */ protected void updateRowHeader(PropertyChangeEvent e) { JViewport newRowHead = (JViewport)(e.getNewValue()); @@ -611,7 +691,11 @@ public class BasicScrollPaneUI } } - + /** + * Updates column header. + * + * @param e the property change event + */ protected void updateColumnHeader(PropertyChangeEvent e) { JViewport newColHead = (JViewport)(e.getNewValue()); @@ -679,9 +763,9 @@ public class BasicScrollPaneUI /** - * Creates an instance of PropertyChangeListener that's added to - * the JScrollPane by installUI(). Subclasses can override this method - * to return a custom PropertyChangeListener, e.g. + * Creates an instance of {@code PropertyChangeListener} that's added to + * the {@code JScrollPane} by {@code installUI()}. Subclasses can override + * this method to return a custom {@code PropertyChangeListener}, e.g. * 
      * class MyScrollPaneUI extends BasicScrollPaneUI {
      *    protected PropertyChangeListener createPropertyChangeListener() {
@@ -698,6 +782,8 @@ public class BasicScrollPaneUI
      * }
      *
* + * @return an instance of {@code PropertyChangeListener} + * * @see java.beans.PropertyChangeListener * @see #installUI */ diff --git a/jdk/src/share/classes/javax/swing/plaf/basic/BasicSplitPaneDivider.java b/jdk/src/share/classes/javax/swing/plaf/basic/BasicSplitPaneDivider.java index 36b4129598c..34dfeb5710a 100644 --- a/jdk/src/share/classes/javax/swing/plaf/basic/BasicSplitPaneDivider.java +++ b/jdk/src/share/classes/javax/swing/plaf/basic/BasicSplitPaneDivider.java @@ -65,9 +65,13 @@ public class BasicSplitPaneDivider extends Container { /** * Width or height of the divider based on orientation - * BasicSplitPaneUI adds two to this. + * {@code BasicSplitPaneUI} adds two to this. */ protected static final int ONE_TOUCH_SIZE = 6; + + /** + * The offset of the divider. + */ protected static final int ONE_TOUCH_OFFSET = 2; /** @@ -136,8 +140,10 @@ public class BasicSplitPaneDivider extends Container /** - * Creates an instance of BasicSplitPaneDivider. Registers this + * Creates an instance of {@code BasicSplitPaneDivider}. Registers this * instance for mouse events and mouse dragged events. + * + * @param ui an instance of {@code BasicSplitPaneUI} */ public BasicSplitPaneDivider(BasicSplitPaneUI ui) { oneTouchSize = DefaultLookup.getInt(ui.getSplitPane(), ui, @@ -163,7 +169,9 @@ public class BasicSplitPaneDivider extends Container } /** - * Sets the SplitPaneUI that is using the receiver. + * Sets the {@code SplitPaneUI} that is using the receiver. + * + * @param newUI the new {@code SplitPaneUI} */ public void setBasicSplitPaneUI(BasicSplitPaneUI newUI) { if (splitPane != null) { @@ -198,8 +206,9 @@ public class BasicSplitPaneDivider extends Container /** - * Returns the SplitPaneUI the receiver is currently - * in. + * Returns the {@code SplitPaneUI} the receiver is currently in. + * + * @return the {@code SplitPaneUI} the receiver is currently in */ public BasicSplitPaneUI getBasicSplitPaneUI() { return splitPaneUI; @@ -207,9 +216,11 @@ public class BasicSplitPaneDivider extends Container /** - * Sets the size of the divider to newSize. That is - * the width if the splitpane is HORIZONTAL_SPLIT, or - * the height of VERTICAL_SPLIT. + * Sets the size of the divider to {@code newSize}. That is + * the width if the splitpane is {@code HORIZONTAL_SPLIT}, or + * the height of {@code VERTICAL_SPLIT}. + * + * @param newSize a new size */ public void setDividerSize(int newSize) { dividerSize = newSize; @@ -219,6 +230,8 @@ public class BasicSplitPaneDivider extends Container /** * Returns the size of the divider, that is the width if the splitpane * is HORIZONTAL_SPLIT, or the height of VERTICAL_SPLIT. + * + * @return the size of the divider */ public int getDividerSize() { return dividerSize; @@ -227,6 +240,8 @@ public class BasicSplitPaneDivider extends Container /** * Sets the border of this component. + * + * @param border a new border * @since 1.3 */ public void setBorder(Border border) { @@ -382,8 +397,10 @@ public class BasicSplitPaneDivider extends Container /** - * Creates and return an instance of JButton that can be used to + * Creates and return an instance of {@code JButton} that can be used to * collapse the left component in the split pane. + * + * @return an instance of {@code JButton} */ protected JButton createLeftOneTouchButton() { JButton b = new JButton() { @@ -438,8 +455,10 @@ public class BasicSplitPaneDivider extends Container /** - * Creates and return an instance of JButton that can be used to + * Creates and return an instance of {@code JButton} that can be used to * collapse the right component in the split pane. + * + * @return an instance of {@code JButton} */ protected JButton createRightOneTouchButton() { JButton b = new JButton() { @@ -503,6 +522,8 @@ public class BasicSplitPaneDivider extends Container /** * Messages the BasicSplitPaneUI with dragDividerTo that this instance * is contained in. + * + * @param location a location */ protected void dragDividerTo(int location) { splitPaneUI.dragDividerTo(location); @@ -512,6 +533,8 @@ public class BasicSplitPaneDivider extends Container /** * Messages the BasicSplitPaneUI with finishDraggingTo that this instance * is contained in. + * + * @param location a location */ protected void finishDraggingTo(int location) { splitPaneUI.finishDraggingTo(location); @@ -694,7 +717,11 @@ public class BasicSplitPaneDivider extends Container */ int offset; - + /** + * Constructs a new instance of {@code DragController}. + * + * @param e a mouse event + */ protected DragController(MouseEvent e) { JSplitPane splitPane = splitPaneUI.getSplitPane(); Component leftC = splitPane.getLeftComponent(); @@ -741,7 +768,9 @@ public class BasicSplitPaneDivider extends Container /** - * Returns true if the dragging session is valid. + * Returns {@code true} if the dragging session is valid. + * + * @return {@code true} if the dragging session is valid */ protected boolean isValid() { return (maxX > 0); @@ -751,6 +780,9 @@ public class BasicSplitPaneDivider extends Container /** * Returns the new position to put the divider at based on * the passed in MouseEvent. + * + * @param e a mouse event + * @return the new position */ protected int positionForMouseEvent(MouseEvent e) { int newX = (e.getSource() == BasicSplitPaneDivider.this) ? @@ -764,6 +796,10 @@ public class BasicSplitPaneDivider extends Container /** * Returns the x argument, since this is used for horizontal * splits. + * + * @param x an X coordinate + * @param y an Y coordinate + * @return the X argument */ protected int getNeededLocation(int x, int y) { int newX; @@ -772,7 +808,13 @@ public class BasicSplitPaneDivider extends Container return newX; } - + /** + * Messages dragDividerTo with the new location for the mouse + * event. + * + * @param newX an X coordinate + * @param newY an Y coordinate + */ protected void continueDrag(int newX, int newY) { dragDividerTo(getNeededLocation(newX, newY)); } @@ -781,12 +823,20 @@ public class BasicSplitPaneDivider extends Container /** * Messages dragDividerTo with the new location for the mouse * event. + * + * @param e a mouse event */ protected void continueDrag(MouseEvent e) { dragDividerTo(positionForMouseEvent(e)); } - + /** + * Messages finishDraggingTo with the new location for the mouse + * event. + * + * @param x an X coordinate + * @param y an Y coordinate + */ protected void completeDrag(int x, int y) { finishDraggingTo(getNeededLocation(x, y)); } @@ -795,6 +845,8 @@ public class BasicSplitPaneDivider extends Container /** * Messages finishDraggingTo with the new location for the mouse * event. + * + * @param e a mouse event */ protected void completeDrag(MouseEvent e) { finishDraggingTo(positionForMouseEvent(e)); @@ -813,6 +865,11 @@ public class BasicSplitPaneDivider extends Container protected class VerticalDragController extends DragController { /* DragControllers ivars are now in terms of y, not x. */ + /** + * Constructs a new instance of {@code VerticalDragController}. + * + * @param e a mouse event + */ protected VerticalDragController(MouseEvent e) { super(e); JSplitPane splitPane = splitPaneUI.getSplitPane(); diff --git a/jdk/src/share/classes/javax/swing/plaf/basic/BasicTableUI.java b/jdk/src/share/classes/javax/swing/plaf/basic/BasicTableUI.java index ba92184b436..bff514b57ff 100644 --- a/jdk/src/share/classes/javax/swing/plaf/basic/BasicTableUI.java +++ b/jdk/src/share/classes/javax/swing/plaf/basic/BasicTableUI.java @@ -64,12 +64,29 @@ public class BasicTableUI extends TableUI // // The JTable that is delegating the painting to this UI. + /** + * The instance of {@code JTable}. + */ protected JTable table; + + /** + * The instance of {@code CellRendererPane}. + */ protected CellRendererPane rendererPane; - // Listeners that are attached to the JTable + /** + * {@code KeyListener} that are attached to the {@code JTable}. + */ protected KeyListener keyListener; + + /** + * {@code FocusListener} that are attached to the {@code JTable}. + */ protected FocusListener focusListener; + + /** + * {@code MouseInputListener} that are attached to the {@code JTable}. + */ protected MouseInputListener mouseInputListener; private Handler handler; @@ -1350,21 +1367,27 @@ public class BasicTableUI extends TableUI } /** - * Creates the key listener for handling keyboard navigation in the JTable. + * Creates the key listener for handling keyboard navigation in the {@code JTable}. + * + * @return the key listener for handling keyboard navigation in the {@code JTable} */ protected KeyListener createKeyListener() { return null; } /** - * Creates the focus listener for handling keyboard navigation in the JTable. + * Creates the focus listener for handling keyboard navigation in the {@code JTable}. + * + * @return the focus listener for handling keyboard navigation in the {@code JTable} */ protected FocusListener createFocusListener() { return getHandler(); } /** - * Creates the mouse listener for the JTable. + * Creates the mouse listener for the {@code JTable}. + * + * @return the mouse listener for the {@code JTable} */ protected MouseInputListener createMouseInputListener() { return getHandler(); @@ -1374,6 +1397,12 @@ public class BasicTableUI extends TableUI // The installation/uninstall procedures and support // + /** + * Returns a new instance of {@code BasicTableUI}. + * + * @param c a component + * @return a new instance of {@code BasicTableUI} + */ public static ComponentUI createUI(JComponent c) { return new BasicTableUI(); } @@ -1616,12 +1645,18 @@ public class BasicTableUI extends TableUI table = null; } + /** + * Uninstalls default properties. + */ protected void uninstallDefaults() { if (table.getTransferHandler() instanceof UIResource) { table.setTransferHandler(null); } } + /** + * Unregisters listeners. + */ protected void uninstallListeners() { table.removeFocusListener(focusListener); table.removeKeyListener(keyListener); @@ -1638,6 +1673,9 @@ public class BasicTableUI extends TableUI handler = null; } + /** + * Unregisters keyboard actions. + */ protected void uninstallKeyboardActions() { SwingUtilities.replaceUIInputMap(table, JComponent. WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, null);