# HG changeset patch # User aeremeev # Date 1404998456 -14400 # Node ID 88051e6ecdc77c8448ca7b6ed0bcb8ea2483220e # Parent 6333e4aa8a70bfb3adb6367a9025ef7ebd97a88e 8049808: Fix doclint warnings from javax.swing.plaf.basic package, 3 of 7 Reviewed-by: pchelko diff -r 6333e4aa8a70 -r 88051e6ecdc7 jdk/src/share/classes/javax/swing/plaf/basic/BasicBorders.java --- a/jdk/src/share/classes/javax/swing/plaf/basic/BasicBorders.java Thu Jul 10 15:08:50 2014 +0400 +++ b/jdk/src/share/classes/javax/swing/plaf/basic/BasicBorders.java Thu Jul 10 17:20:56 2014 +0400 @@ -45,6 +45,11 @@ public class BasicBorders { + /** + * Returns a border instance for a {@code JButton}. + * + * @return a border instance for a {@code JButton} + */ public static Border getButtonBorder() { UIDefaults table = UIManager.getLookAndFeelDefaults(); Border buttonBorder = new BorderUIResource.CompoundBorderUIResource( @@ -57,6 +62,11 @@ return buttonBorder; } + /** + * Returns a border instance for a {@code JRadioButton}. + * + * @return a border instance for a {@code JRadioButton} + */ public static Border getRadioButtonBorder() { UIDefaults table = UIManager.getLookAndFeelDefaults(); Border radioButtonBorder = new BorderUIResource.CompoundBorderUIResource( @@ -69,6 +79,11 @@ return radioButtonBorder; } + /** + * Returns a border instance for a {@code JToggleButton}. + * + * @return a border instance for a {@code JToggleButton} + */ public static Border getToggleButtonBorder() { UIDefaults table = UIManager.getLookAndFeelDefaults(); Border toggleButtonBorder = new BorderUIResource.CompoundBorderUIResource( @@ -81,6 +96,11 @@ return toggleButtonBorder; } + /** + * Returns a border instance for a {@code JMenuBar}. + * + * @return a border instance for a {@code JMenuBar} + */ public static Border getMenuBarBorder() { UIDefaults table = UIManager.getLookAndFeelDefaults(); Border menuBarBorder = new BasicBorders.MenuBarBorder( @@ -90,6 +110,11 @@ return menuBarBorder; } + /** + * Returns a border instance for a {@code JSplitPane}. + * + * @return a border instance for a {@code JSplitPane} + */ public static Border getSplitPaneBorder() { UIDefaults table = UIManager.getLookAndFeelDefaults(); Border splitPaneBorder = new BasicBorders.SplitPaneBorder( @@ -99,7 +124,9 @@ } /** - * Returns a border instance for a JSplitPane divider + * Returns a border instance for a {@code JSplitPane} divider. + * + * @return a border instance for a {@code JSplitPane} divider * @since 1.3 */ public static Border getSplitPaneDividerBorder() { @@ -110,6 +137,11 @@ return splitPaneBorder; } + /** + * Returns a border instance for a {@code JTextField}. + * + * @return a border instance for a {@code JTextField} + */ public static Border getTextFieldBorder() { UIDefaults table = UIManager.getLookAndFeelDefaults(); Border textFieldBorder = new BasicBorders.FieldBorder( @@ -120,12 +152,22 @@ return textFieldBorder; } + /** + * Returns a border instance for a {@code JProgressBar}. + * + * @return a border instance for a {@code JProgressBar} + */ public static Border getProgressBarBorder() { UIDefaults table = UIManager.getLookAndFeelDefaults(); Border progressBarBorder = new BorderUIResource.LineBorderUIResource(Color.green, 2); return progressBarBorder; } + /** + * Returns a border instance for a {@code JInternalFrame}. + * + * @return a border instance for a {@code JInternalFrame} + */ public static Border getInternalFrameBorder() { UIDefaults table = UIManager.getLookAndFeelDefaults(); Border internalFrameBorder = new BorderUIResource.CompoundBorderUIResource( @@ -147,6 +189,14 @@ @SuppressWarnings("serial") // Superclass is not serializable across versions public static class RolloverButtonBorder extends ButtonBorder { + /** + * Constructs a new instance of a {@code RolloverButtonBorder}. + * + * @param shadow a color of shadow + * @param darkShadow a color of dark shadow + * @param highlight a color of highlight + * @param lightHighlight a color of light highlight + */ public RolloverButtonBorder(Color shadow, Color darkShadow, Color highlight, Color lightHighlight) { super(shadow, darkShadow, highlight, lightHighlight); @@ -227,13 +277,36 @@ } } + /** + * Draws a border around a button. + */ @SuppressWarnings("serial") // Superclass is not serializable across versions public static class ButtonBorder extends AbstractBorder implements UIResource { + /** + * The color of shadow. + */ protected Color shadow; + /** + * The color of dark shadow. + */ protected Color darkShadow; + /** + * The color of highlight. + */ protected Color highlight; + /** + * The color of light highlight. + */ protected Color lightHighlight; + /** + * Constructs a new instance of a {@code ButtonBorder}. + * + * @param shadow a color of shadow + * @param darkShadow a color of dark shadow + * @param highlight a color of highlight + * @param lightHighlight a color of light highlight + */ public ButtonBorder(Color shadow, Color darkShadow, Color highlight, Color lightHighlight) { this.shadow = shadow; @@ -270,9 +343,20 @@ } + /** + * Draws the border around a toggle button. + */ @SuppressWarnings("serial") // Superclass is not serializable across versions public static class ToggleButtonBorder extends ButtonBorder { + /** + * Constructs a new instance of a {@code ToggleButtonBorder}. + * + * @param shadow a color of shadow + * @param darkShadow a color of dark shadow + * @param highlight a color of highlight + * @param lightHighlight a color of light highlight + */ public ToggleButtonBorder(Color shadow, Color darkShadow, Color highlight, Color lightHighlight) { super(shadow, darkShadow, highlight, lightHighlight); @@ -292,9 +376,20 @@ } } + /** + * Draws the border around a radio button. + */ @SuppressWarnings("serial") // Superclass is not serializable across versions public static class RadioButtonBorder extends ButtonBorder { + /** + * Constructs a new instance of a {@code RadioButtonBorder}. + * + * @param shadow a color of shadow + * @param darkShadow a color of dark shadow + * @param highlight a color of highlight + * @param lightHighlight a color of light highlight + */ public RadioButtonBorder(Color shadow, Color darkShadow, Color highlight, Color lightHighlight) { super(shadow, darkShadow, highlight, lightHighlight); @@ -329,11 +424,26 @@ } } + /** + * Draws the border around a menu bar. + */ @SuppressWarnings("serial") // Superclass is not serializable across versions public static class MenuBarBorder extends AbstractBorder implements UIResource { + /** + * The color of shadow. + */ private Color shadow; + /** + * The color of highlight. + */ private Color highlight; + /** + * Constructs a new instance of a {@code MenuBarBorder}. + * + * @param shadow a color of shadow + * @param highlight a color of highlight + */ public MenuBarBorder(Color shadow, Color highlight) { this.shadow = shadow; this.highlight = highlight; @@ -356,6 +466,9 @@ } } + /** + * Draws the border around components which support margins. + */ @SuppressWarnings("serial") // Superclass is not serializable across versions public static class MarginBorder extends AbstractBorder implements UIResource { public Insets getBorderInsets(Component c, Insets insets) { @@ -384,13 +497,36 @@ } } + /** + * Draws the border around a field. + */ @SuppressWarnings("serial") // Superclass is not serializable across versions public static class FieldBorder extends AbstractBorder implements UIResource { + /** + * The color of shadow. + */ protected Color shadow; + /** + * The color of dark shadow. + */ protected Color darkShadow; + /** + * The color of highlight. + */ protected Color highlight; + /** + * The color of light highlight. + */ protected Color lightHighlight; + /** + * Constructs a new instance of a {@code FieldBorder}. + * + * @param shadow a color of shadow + * @param darkShadow a color of dark shadow + * @param highlight a color of highlight + * @param lightHighlight a color of light highlight + */ public FieldBorder(Color shadow, Color darkShadow, Color highlight, Color lightHighlight) { this.shadow = shadow; @@ -509,9 +645,21 @@ * also install a border on the divider (property SplitPaneDivider.border). */ public static class SplitPaneBorder implements Border, UIResource { + /** + * The color of highlight + */ protected Color highlight; + /** + * The color of shadow + */ protected Color shadow; + /** + * Constructs a new instance of a {@code SplitPaneBorder}. + * + * @param highlight a color of highlight + * @param shadow a color of shadow + */ public SplitPaneBorder(Color highlight, Color shadow) { this.highlight = highlight; this.shadow = shadow; diff -r 6333e4aa8a70 -r 88051e6ecdc7 jdk/src/share/classes/javax/swing/plaf/basic/BasicListUI.java --- a/jdk/src/share/classes/javax/swing/plaf/basic/BasicListUI.java Thu Jul 10 15:08:50 2014 +0400 +++ b/jdk/src/share/classes/javax/swing/plaf/basic/BasicListUI.java Thu Jul 10 17:20:56 2014 +0400 @@ -59,20 +59,53 @@ private static final StringBuilder BASELINE_COMPONENT_KEY = new StringBuilder("List.baselineComponent"); + /** + * The instance of {@code JList}. + */ protected JList list = null; + /** + * The instance of {@code CellRendererPane}. + */ protected CellRendererPane rendererPane; // Listeners that this UI attaches to the JList + /** + * {@code FocusListener} that attached to {@code JList}. + */ protected FocusListener focusListener; + /** + * {@code MouseInputListener} that attached to {@code JList}. + */ protected MouseInputListener mouseInputListener; + /** + * {@code ListSelectionListener} that attached to {@code JList}. + */ protected ListSelectionListener listSelectionListener; + /** + * {@code ListDataListener} that attached to {@code JList}. + */ protected ListDataListener listDataListener; + /** + * {@code PropertyChangeListener} that attached to {@code JList}. + */ protected PropertyChangeListener propertyChangeListener; private Handler handler; + /** + * The array of cells' height + */ protected int[] cellHeights = null; + /** + * The height of cell. + */ protected int cellHeight = -1; + /** + * The width of cell. + */ protected int cellWidth = -1; + /** + * The value represents changes to {@code JList} model. + */ protected int updateLayoutStateNeeded = modelChanged; /** * Height of the list. When asked to paint, if the current size of @@ -131,12 +164,33 @@ * models length changed, are handled similarly, see DataListener. */ + /** + * The bit relates to model changed property. + */ protected final static int modelChanged = 1 << 0; + /** + * The bit relates to selection model changed property. + */ protected final static int selectionModelChanged = 1 << 1; + /** + * The bit relates to font changed property. + */ protected final static int fontChanged = 1 << 2; + /** + * The bit relates to fixed cell width changed property. + */ protected final static int fixedCellWidthChanged = 1 << 3; + /** + * The bit relates to fixed cell height changed property. + */ protected final static int fixedCellHeightChanged = 1 << 4; + /** + * The bit relates to prototype cell value changed property. + */ protected final static int prototypeCellValueChanged = 1 << 5; + /** + * The bit relates to cell renderer changed property. + */ protected final static int cellRendererChanged = 1 << 6; private final static int layoutOrientationChanged = 1 << 7; private final static int heightChanged = 1 << 8; @@ -187,9 +241,16 @@ /** * Paint one List cell: compute the relevant state, get the "rubber stamp" - * cell renderer component, and then use the CellRendererPane to paint it. - * Subclasses may want to override this method rather than paint(). + * cell renderer component, and then use the {@code CellRendererPane} to paint it. + * Subclasses may want to override this method rather than {@code paint()}. * + * @param g an instance of {@code Graphics} + * @param row a row + * @param rowBounds a bounding rectangle to render to + * @param cellRenderer a list of {@code ListCellRenderer} + * @param dataModel a list model + * @param selModel a selection model + * @param leadIndex a lead index * @see #paint */ protected void paintCell( @@ -916,10 +977,11 @@ /** - * Returns a new instance of BasicListUI. BasicListUI delegates are - * allocated one per JList. + * Returns a new instance of {@code BasicListUI}. + * {@code BasicListUI} delegates are allocated one per {@code JList}. * - * @return A new ListUI implementation for the Windows look and feel. + * @param list a component + * @return a new {@code ListUI} implementation for the Windows look and feel. */ public static ComponentUI createUI(JComponent list) { return new BasicListUI(); @@ -1046,7 +1108,8 @@ /** * Returns the height of the specified row based on the current layout. * - * @return The specified row height or -1 if row isn't valid. + * @param row a row + * @return the specified row height or -1 if row isn't valid * @see #convertYToRow * @see #convertRowToY * @see #updateLayoutState @@ -1058,11 +1121,12 @@ /** - * Convert the JList relative coordinate to the row that contains it, - * based on the current layout. If y0 doesn't fall within any row, + * Convert the {@code JList} relative coordinate to the row that contains it, + * based on the current layout. If {@code y0} doesn't fall within any row, * return -1. * - * @return The row that contains y0, or -1. + * @param y0 a relative Y coordinate + * @return the row that contains y0, or -1 * @see #getRowHeight * @see #updateLayoutState */ @@ -1073,10 +1137,11 @@ /** - * Return the JList relative Y coordinate of the origin of the specified + * Return the {@code JList} relative Y coordinate of the origin of the specified * row or -1 if row isn't valid. * - * @return The Y coordinate of the origin of row, or -1. + * @param row a row + * @return the Y coordinate of the origin of row, or -1 * @see #getRowHeight * @see #updateLayoutState */ @@ -1535,10 +1600,10 @@ /** - * Creates a delegate that implements MouseInputListener. - * The delegate is added to the corresponding java.awt.Component listener - * lists at installUI() time. Subclasses can override this method to return - * a custom MouseInputListener, e.g. + * Creates a delegate that implements {@code MouseInputListener}. + * The delegate is added to the corresponding {@code java.awt.Component} listener + * lists at {@code installUI()} time. Subclasses can override this method to return + * a custom {@code MouseInputListener}, e.g. * 
      * class MyListUI extends BasicListUI {
      *    protected MouseInputListener createMouseInputListener() {
@@ -1553,6 +1618,7 @@
      * }
      *
* + * @return an instance of {@code MouseInputListener} * @see MouseInputHandler * @see #installUI */ @@ -1566,6 +1632,9 @@ */ public class FocusHandler implements FocusListener { + /** + * Repaints focused cells. + */ protected void repaintCellFocus() { getHandler().repaintCellFocus(); @@ -1584,6 +1653,11 @@ } } + /** + * Returns an instance of {@code FocusListener}. + * + * @return an instance of {@code FocusListener} + */ protected FocusListener createFocusListener() { return getHandler(); } @@ -1617,9 +1691,9 @@ /** - * Creates an instance of ListSelectionHandler that's added to - * the JLists by selectionModel as needed. Subclasses can override - * this method to return a custom ListSelectionListener, e.g. + * Creates an instance of {@code ListSelectionHandler} that's added to + * the {@code JLists} by selectionModel as needed. Subclasses can override + * this method to return a custom {@code ListSelectionListener}, e.g. * 
      * class MyListUI extends BasicListUI {
      *    protected ListSelectionListener createListSelectionListener() {
@@ -1634,6 +1708,7 @@
      * }
      *
* + * @return an instance of {@code ListSelectionHandler} * @see ListSelectionHandler * @see #installUI */ @@ -1649,8 +1724,8 @@ /** - * The ListDataListener that's added to the JLists model at - * installUI time, and whenever the JList.model property changes. + * The {@code ListDataListener} that's added to the {@code JLists} model at + * {@code installUI time}, and whenever the JList.model property changes. *

* Warning: * Serialized objects of this class will not be compatible with @@ -1687,9 +1762,9 @@ /** - * Creates an instance of ListDataListener that's added to - * the JLists by model as needed. Subclasses can override - * this method to return a custom ListDataListener, e.g. + * Creates an instance of {@code ListDataListener} that's added to + * the {@code JLists} by model as needed. Subclasses can override + * this method to return a custom {@code ListDataListener}, e.g. * 

      * class MyListUI extends BasicListUI {
      *    protected ListDataListener createListDataListener() {
@@ -1704,6 +1779,7 @@
      * }
      *
* + * @return an instance of {@code ListDataListener} * @see ListDataListener * @see JList#getModel * @see #installUI @@ -1744,9 +1820,9 @@ /** - * Creates an instance of PropertyChangeHandler that's added to - * the JList by installUI(). Subclasses can override this method - * to return a custom PropertyChangeListener, e.g. + * Creates an instance of {@code PropertyChangeHandler} that's added to + * the {@code JList} by {@code installUI()}. Subclasses can override this method + * to return a custom {@code PropertyChangeListener}, e.g. * 
      * class MyListUI extends BasicListUI {
      *    protected PropertyChangeListener createPropertyChangeListener() {
@@ -1763,6 +1839,7 @@
      * }
      *
* + * @return an instance of {@code PropertyChangeHandler} * @see PropertyChangeListener * @see #installUI */ diff -r 6333e4aa8a70 -r 88051e6ecdc7 jdk/src/share/classes/javax/swing/plaf/basic/BasicMenuItemUI.java --- a/jdk/src/share/classes/javax/swing/plaf/basic/BasicMenuItemUI.java Thu Jul 10 15:08:50 2014 +0400 +++ b/jdk/src/share/classes/javax/swing/plaf/basic/BasicMenuItemUI.java Thu Jul 10 17:20:56 2014 +0400 @@ -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 @@ -47,11 +47,29 @@ */ public class BasicMenuItemUI extends MenuItemUI { + /** + * The instance of {@code JMenuItem}. + */ protected JMenuItem menuItem = null; + /** + * The color of the selection background. + */ protected Color selectionBackground; + /** + * The color of the selection foreground. + */ protected Color selectionForeground; + /** + * The color of the disabled foreground. + */ protected Color disabledForeground; + /** + * The color of the accelerator foreground. + */ protected Color acceleratorForeground; + /** + * The color of the accelerator selection. + */ protected Color acceleratorSelectionForeground; /** @@ -60,18 +78,33 @@ */ protected String acceleratorDelimiter; + /** + * The gap between the text and the icon. + */ protected int defaultTextIconGap; + /** + * The accelerator font. + */ protected Font acceleratorFont; + /** + * The instance of {@code MouseInputListener}. + */ protected MouseInputListener mouseInputListener; + /** + * The instance of {@code MenuDragMouseListener}. + */ protected MenuDragMouseListener menuDragMouseListener; + /** + * The instance of {@code MenuKeyListener}. + */ protected MenuKeyListener menuKeyListener; /** - * PropertyChangeListener returned from - * createPropertyChangeListener. You should not + * {@code PropertyChangeListener} returned from + * {@code createPropertyChangeListener}. You should not * need to access this field, rather if you want to customize the - * PropertyChangeListener override - * createPropertyChangeListener. + * {@code PropertyChangeListener} override + * {@code createPropertyChangeListener}. * * @since 1.6 * @see #createPropertyChangeListener @@ -79,10 +112,17 @@ protected PropertyChangeListener propertyChangeListener; // BasicMenuUI also uses this. Handler handler; - + /** + * The arrow icon. + */ protected Icon arrowIcon = null; + /** + * The check icon. + */ protected Icon checkIcon = null; - + /** + * The value represents if the old border is painted. + */ protected boolean oldBorderPainted; /* diagnostic aids -- should be false for production builds. */ @@ -97,6 +137,12 @@ BasicLookAndFeel.installAudioActionMap(map); } + /** + * Returns a new instance of {@code BasicMenuItemUI}. + * + * @param c a component + * @return a new instance of {@code BasicMenuItemUI} + */ public static ComponentUI createUI(JComponent c) { return new BasicMenuItemUI(); } @@ -110,7 +156,9 @@ installKeyboardActions(); } - + /** + * Installs default properties. + */ protected void installDefaults() { String prefix = getPropertyPrefix(); @@ -202,16 +250,26 @@ } /** + * + * @param menuItem a menu item * @since 1.3 */ protected void installComponents(JMenuItem menuItem){ BasicHTML.updateRenderer(menuItem, menuItem.getText()); } + /** + * Returns a property prefix. + * + * @return a property prefix + */ protected String getPropertyPrefix() { return "MenuItem"; } + /** + * Registers listeners. + */ protected void installListeners() { if ((mouseInputListener = createMouseInputListener(menuItem)) != null) { menuItem.addMouseListener(mouseInputListener); @@ -228,6 +286,9 @@ } } + /** + * Registers keyboard action. + */ protected void installKeyboardActions() { installLazyActionMap(); updateAcceleratorBinding(); @@ -248,7 +309,9 @@ menuItem = null; } - + /** + * Uninstalls default properties. + */ protected void uninstallDefaults() { LookAndFeel.uninstallBorder(menuItem); LookAndFeel.installProperty(menuItem, "borderPainted", oldBorderPainted); @@ -261,12 +324,18 @@ } /** + * Unregisters components. + * + * @param menuItem a menu item * @since 1.3 */ protected void uninstallComponents(JMenuItem menuItem){ BasicHTML.updateRenderer(menuItem, ""); } + /** + * Unregisters listeners. + */ protected void uninstallListeners() { if (mouseInputListener != null) { menuItem.removeMouseListener(mouseInputListener); @@ -289,30 +358,52 @@ handler = null; } + /** + * Unregisters keyboard actions. + */ protected void uninstallKeyboardActions() { SwingUtilities.replaceUIActionMap(menuItem, null); SwingUtilities.replaceUIInputMap(menuItem, JComponent. WHEN_IN_FOCUSED_WINDOW, null); } + /** + * Returns an instance of {@code MouseInputListener}. + * + * @param c a component + * @return an instance of {@code MouseInputListener} + */ protected MouseInputListener createMouseInputListener(JComponent c) { return getHandler(); } + /** + * Returns an instance of {@code MenuDragMouseListener}. + * + * @param c a component + * @return an instance of {@code MenuDragMouseListener} + */ protected MenuDragMouseListener createMenuDragMouseListener(JComponent c) { return getHandler(); } + /** + * Returns an instance of {@code MenuKeyListener}. + * + * @param c a component + * @return an instance of {@code MenuKeyListener} + */ protected MenuKeyListener createMenuKeyListener(JComponent c) { return null; } /** - * Creates a PropertyChangeListener which will be added to + * Creates a {@code PropertyChangeListener} which will be added to * the menu item. * If this method returns null then it will not be added to the menu item. * - * @return an instance of a PropertyChangeListener or null + * @param c a component + * @return an instance of a {@code PropertyChangeListener} or null * @since 1.6 */ protected PropertyChangeListener @@ -380,6 +471,15 @@ return d; } + /** + * Returns the preferred size of a menu item. + * + * @param c a component + * @param checkIcon a check icon + * @param arrowIcon an arrow icon + * @param defaultTextIconGap a gap between a text and an icon + * @return the preferred size of a menu item + */ protected Dimension getPreferredMenuItemSize(JComponent c, Icon checkIcon, Icon arrowIcon, @@ -477,6 +577,17 @@ defaultTextIconGap); } + /** + * Paints a menu item. + * + * @param g an instance of {@code Graphics} + * @param c a component + * @param checkIcon a check icon + * @param arrowIcon an arrow icon + * @param background a background color + * @param foreground a foreground color + * @param defaultTextIconGap a gap between a text and an icon + */ protected void paintMenuItem(Graphics g, JComponent c, Icon checkIcon, Icon arrowIcon, Color background, Color foreground, @@ -701,6 +812,11 @@ } } + /** + * Returns a menu element path. + * + * @return a menu element path + */ public MenuElement[] getPath() { MenuSelectionManager m = MenuSelectionManager.defaultManager(); MenuElement oldPath[] = m.getSelectedPath(); diff -r 6333e4aa8a70 -r 88051e6ecdc7 jdk/src/share/classes/javax/swing/plaf/basic/BasicProgressBarUI.java --- a/jdk/src/share/classes/javax/swing/plaf/basic/BasicProgressBarUI.java Thu Jul 10 15:08:50 2014 +0400 +++ b/jdk/src/share/classes/javax/swing/plaf/basic/BasicProgressBarUI.java Thu Jul 10 17:20:56 2014 +0400 @@ -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 @@ -53,7 +53,13 @@ private Animator animator; + /** + * The instance of {@code JProgressBar}. + */ protected JProgressBar progressBar; + /** + * The instance of {@code ChangeListener}. + */ protected ChangeListener changeListener; private Handler handler; @@ -127,7 +133,12 @@ private int maxPosition = 0; //maximum X (horiz) or Y box location - + /** + * Returns a new instance of {@code BasicProgressBarUI}. + * + * @param x a component + * @return a new instance of {@code BasicProgressBarUI} + */ public static ComponentUI createUI(JComponent x) { return new BasicProgressBarUI(); } @@ -150,6 +161,9 @@ progressBar = null; } + /** + * Installs default properties. + */ protected void installDefaults() { LookAndFeel.installProperty(progressBar, "opaque", Boolean.TRUE); LookAndFeel.installBorder(progressBar,"ProgressBar.border"); @@ -164,10 +178,16 @@ selectionBackground = UIManager.getColor("ProgressBar.selectionBackground"); } + /** + * Unintalls default properties. + */ protected void uninstallDefaults() { LookAndFeel.uninstallBorder(progressBar); } + /** + * Registers listeners. + */ protected void installListeners() { //Listen for changes in the progress bar's data. changeListener = getHandler(); @@ -291,6 +311,11 @@ // protected void installKeyboardActions() // protected void uninstallKeyboardActions() + /** + * Returns preferred size of the horizontal {@code JProgressBar}. + * + * @return preferred size of the horizontal {@code JProgressBar} + */ protected Dimension getPreferredInnerHorizontal() { Dimension horizDim = (Dimension)DefaultLookup.get(progressBar, this, "ProgressBar.horizontalSize"); @@ -300,6 +325,11 @@ return horizDim; } + /** + * Returns preferred size of the vertical {@code JProgressBar}. + * + * @return preferred size of the vertical {@code JProgressBar} + */ protected Dimension getPreferredInnerVertical() { Dimension vertDim = (Dimension)DefaultLookup.get(progressBar, this, "ProgressBar.verticalSize"); @@ -312,6 +342,8 @@ /** * The "selectionForeground" is the color of the text when it is painted * over a filled area of the progress bar. + * + * @return the color of the selected foreground */ protected Color getSelectionForeground() { return selectionForeground; @@ -320,6 +352,8 @@ /** * The "selectionBackground" is the color of the text when it is painted * over an unfilled area of the progress bar. + * + * @return the color of the selected background */ protected Color getSelectionBackground() { return selectionBackground; @@ -352,6 +386,11 @@ } } + /** + * Sets the cell length. + * + * @param cellLen a new cell length + */ protected void setCellLength(int cellLen) { this.cellLength = cellLen; } @@ -374,6 +413,11 @@ } } + /** + * Sets the cell spacing. + * + * @param cellSpace a new cell spacing + */ protected void setCellSpacing(int cellSpace) { this.cellSpacing = cellSpace; } @@ -384,6 +428,11 @@ * operation so it was abstracted out. It assumes that your progress bar * is linear. That is, if you are making a circular progress indicator, * you will want to override this method. + * + * @param b insets + * @param width a width + * @param height a height + * @return the amount of the progress bar that should be filled */ protected int getAmountFull(Insets b, int width, int height) { int amountFull = 0; @@ -577,6 +626,8 @@ * Override this if you are making another kind of * progress bar. * + * @param g an instance of {@code Graphics} + * @param c a component * @see #paintDeterminate * * @since 1.4 @@ -628,6 +679,8 @@ * Naturally, override this if you are making a circular or * semi-circular progress bar. * + * @param g an instance of {@code Graphics} + * @param c a component * @see #paintIndeterminate * * @since 1.4 @@ -703,7 +756,18 @@ } } - + /** + * Paints the progress string. + * + * @param g an instance of {@code Graphics} + * @param x X location of bounding box + * @param y Y location of bounding box + * @param width width of bounding box + * @param height height of bounding box + * @param amountFull size of the fill region, either width or height + * depending upon orientation. + * @param b Insets of the progress bar. + */ protected void paintString(Graphics g, int x, int y, int width, int height, int amountFull, Insets b) { @@ -793,6 +857,14 @@ * bar (in both x and y). Override this if you want to right, * left, top, or bottom align the progress string or if you need * to nudge it around for any reason. + * + * @param g an instance of {@code Graphics} + * @param progressString a text + * @param x an X coordinate + * @param y an Y coordinate + * @param width a width + * @param height a height + * @return the place where the progress string will be painted */ protected Point getStringPlacement(Graphics g, String progressString, int x,int y,int width,int height) { @@ -894,6 +966,7 @@ /** * Gets the index of the current animation frame. * + * @return the index of the current animation frame * @since 1.4 */ protected int getAnimationIndex() { diff -r 6333e4aa8a70 -r 88051e6ecdc7 jdk/src/share/classes/javax/swing/plaf/basic/BasicSplitPaneUI.java --- a/jdk/src/share/classes/javax/swing/plaf/basic/BasicSplitPaneUI.java Thu Jul 10 15:08:50 2014 +0400 +++ b/jdk/src/share/classes/javax/swing/plaf/basic/BasicSplitPaneUI.java Thu Jul 10 17:20:56 2014 +0400 @@ -286,7 +286,10 @@ /** - * Creates a new BasicSplitPaneUI instance + * Creates a new instance of {@code BasicSplitPaneUI}. + * + * @param x a component + * @return a new instance of {@code BasicSplitPaneUI} */ public static ComponentUI createUI(JComponent x) { return new BasicSplitPaneUI(); @@ -503,7 +506,9 @@ /** - * Creates a PropertyChangeListener for the JSplitPane UI. + * Creates a {@code PropertyChangeListener} for the {@code JSplitPane} UI. + * + * @return an instance of {@code PropertyChangeListener} */ protected PropertyChangeListener createPropertyChangeListener() { return getHandler(); @@ -518,7 +523,9 @@ /** - * Creates a FocusListener for the JSplitPane UI. + * Creates a {@code FocusListener} for the {@code JSplitPane} UI. + * + * @return an instance of {@code FocusListener} */ protected FocusListener createFocusListener() { return getHandler(); @@ -526,16 +533,17 @@ /** - * As of Java 2 platform v1.3 this method is no - * longer used. Subclassers previously using this method should - * instead create an Action wrapping the ActionListener, and register - * that Action by overriding installKeyboardActions and - * placing the Action in the SplitPane's ActionMap. Please refer to - * the key bindings specification for further details. + * As of Java 2 platform v1.3 this method is no longer used. + * Subclassers previously using this method should instead create + * an {@code Action} wrapping the {@code ActionListener}, and register + * that {@code Action} by overriding {@code installKeyboardActions} + * and placing the {@code Action} in the {@code SplitPane's ActionMap}. + * Please refer to the key bindings specification for further details. *

- * Creates a ActionListener for the JSplitPane UI that listens for - * specific key presses. + * Creates an {@code ActionListener} for the {@code JSplitPane} UI that + * listens for specific key presses. * + * @return an instance of {@code ActionListener} * @deprecated As of Java 2 platform v1.3. */ @Deprecated @@ -545,16 +553,17 @@ /** - * As of Java 2 platform v1.3 this method is no - * longer used. Subclassers previously using this method should - * instead create an Action wrapping the ActionListener, and register - * that Action by overriding installKeyboardActions and - * placing the Action in the SplitPane's ActionMap. Please refer to - * the key bindings specification for further details. + * As of Java 2 platform v1.3 this method is no longer used. + * Subclassers previously using this method should instead create + * an {@code Action} wrapping the {@code ActionListener}, and register + * that {@code Action} by overriding {@code installKeyboardActions} + * and placing the {@code Action} in the {@code SplitPane's ActionMap}. + * Please refer to the key bindings specification for further details. *

- * Creates a ActionListener for the JSplitPane UI that listens for - * specific key presses. + * Creates an {@code ActionListener} for the {@code JSplitPane} UI that + * listens for specific key presses. * + * @return an instance of {@code ActionListener} * @deprecated As of Java 2 platform v1.3. */ @Deprecated @@ -564,16 +573,17 @@ /** - * As of Java 2 platform v1.3 this method is no - * longer used. Subclassers previously using this method should - * instead create an Action wrapping the ActionListener, and register - * that Action by overriding installKeyboardActions and - * placing the Action in the SplitPane's ActionMap. Please refer to - * the key bindings specification for further details. + * As of Java 2 platform v1.3 this method is no longer used. + * Subclassers previously using this method should instead create + * an {@code Action} wrapping the {@code ActionListener}, and register + * that {@code Action} by overriding {@code installKeyboardActions} + * and placing the {@code Action} in the {@code SplitPane's ActionMap}. + * Please refer to the key bindings specification for further details. *

- * Creates a ActionListener for the JSplitPane UI that listens for - * specific key presses. + * Creates an {@code ActionListener} for the {@code JSplitPane} UI that + * listens for specific key presses. * + * @return an instance of {@code ActionListener} * @deprecated As of Java 2 platform v1.3. */ @Deprecated @@ -583,16 +593,17 @@ /** - * As of Java 2 platform v1.3 this method is no - * longer used. Subclassers previously using this method should - * instead create an Action wrapping the ActionListener, and register - * that Action by overriding installKeyboardActions and - * placing the Action in the SplitPane's ActionMap. Please refer to - * the key bindings specification for further details. + * As of Java 2 platform v1.3 this method is no longer used. + * Subclassers previously using this method should instead create + * an {@code Action} wrapping the {@code ActionListener}, and register + * that {@code Action} by overriding {@code installKeyboardActions} + * and placing the {@code Action} in the {@code SplitPane's ActionMap}. + * Please refer to the key bindings specification for further details. *

- * Creates a ActionListener for the JSplitPane UI that listens for - * specific key presses. + * Creates an {@code ActionListener} for the {@code JSplitPane} UI that + * listens for specific key presses. * + * @return an instance of {@code ActionListener} * @deprecated As of Java 2 platform v1.3. */ @Deprecated @@ -602,16 +613,17 @@ /** - * As of Java 2 platform v1.3 this method is no - * longer used. Subclassers previously using this method should - * instead create an Action wrapping the ActionListener, and register - * that Action by overriding installKeyboardActions and - * placing the Action in the SplitPane's ActionMap. Please refer to - * the key bindings specification for further details. + * As of Java 2 platform v1.3 this method is no longer used. + * Subclassers previously using this method should instead create + * an {@code Action} wrapping the {@code ActionListener}, and register + * that {@code Action} by overriding {@code installKeyboardActions} + * and placing the {@code Action} in the {@code SplitPane's ActionMap}. + * Please refer to the key bindings specification for further details. *

- * Creates a ActionListener for the JSplitPane UI that listens for - * specific key presses. + * Creates an {@code ActionListener} for the {@code JSplitPane} UI that + * listens for specific key presses. * + * @return an instance of {@code ActionListener} * @deprecated As of Java 2 platform v1.3. */ @Deprecated @@ -621,7 +633,9 @@ /** - * Returns the orientation for the JSplitPane. + * Returns the orientation for the {@code JSplitPane}. + * + * @return the orientation */ public int getOrientation() { return orientation; @@ -629,7 +643,9 @@ /** - * Set the orientation for the JSplitPane. + * Set the orientation for the {@code JSplitPane}. + * + * @param orientation the orientation */ public void setOrientation(int orientation) { this.orientation = orientation; @@ -637,7 +653,9 @@ /** - * Determines whether the JSplitPane is set to use a continuous layout. + * Determines whether the {@code JSplitPane} is set to use a continuous layout. + * + * @return {@code true} if a continuous layout is set */ public boolean isContinuousLayout() { return continuousLayout; @@ -646,6 +664,8 @@ /** * Turn continuous layout on/off. + * + * @param b if {@code true} the continuous layout turns on */ public void setContinuousLayout(boolean b) { continuousLayout = b; @@ -653,7 +673,9 @@ /** - * Returns the last drag location of the JSplitPane. + * Returns the last drag location of the {@code JSplitPane}. + * + * @return the last drag location */ public int getLastDragLocation() { return lastDragLocation; @@ -661,7 +683,9 @@ /** - * Set the last drag location of the JSplitPane. + * Set the last drag location of the {@code JSplitPane}. + * + * @param l the drag location */ public void setLastDragLocation(int l) { lastDragLocation = l; @@ -819,6 +843,8 @@ /** * Returns the divider between the top Components. + * + * @return the divider between the top Components */ public BasicSplitPaneDivider getDivider() { return divider; @@ -828,6 +854,8 @@ /** * Returns the default non continuous layout divider, which is an * instance of {@code Canvas} that fills in the background with dark gray. + * + * @return the default non continuous layout divider */ @SuppressWarnings("serial") // anonymous class protected Component createDefaultNonContinuousLayoutDivider() { @@ -849,10 +877,12 @@ /** - * Sets the divider to use when the splitPane is configured to + * Sets the divider to use when the {@code JSplitPane} is configured to * not continuously layout. This divider will only be used during a * dragging session. It is recommended that the passed in component * be a heavy weight. + * + * @param newDivider the new divider */ protected void setNonContinuousLayoutDivider(Component newDivider) { setNonContinuousLayoutDivider(newDivider, true); @@ -861,6 +891,9 @@ /** * Sets the divider to use. + * + * @param newDivider the new divider + * @param rememberSizes if {@code true} the pane size is remembered */ protected void setNonContinuousLayoutDivider(Component newDivider, boolean rememberSizes) { @@ -903,9 +936,11 @@ /** - * Returns the divider to use when the splitPane is configured to + * Returns the divider to use when the {@code JSplitPane} is configured to * not continuously layout. This divider will only be used during a * dragging session. + * + * @return the divider */ public Component getNonContinuousLayoutDivider() { return nonContinuousLayoutDivider; @@ -913,8 +948,10 @@ /** - * Returns the splitpane this instance is currently contained + * Returns the {@code JSplitPane} this instance is currently contained * in. + * + * @return the instance of {@code JSplitPane} */ public JSplitPane getSplitPane() { return splitPane; @@ -923,6 +960,8 @@ /** * Creates the default divider. + * + * @return the default divider */ public BasicSplitPaneDivider createDefaultDivider() { return new BasicSplitPaneDivider(this); @@ -1108,6 +1147,9 @@ /** * Returns the insets. The insets are returned from the border insets * of the current border. + * + * @param jc a component + * @return the insets */ public Insets getInsets(JComponent jc) { return null; @@ -1187,8 +1229,10 @@ /** * Messaged during a dragging session to move the divider to the - * passed in location. If continuousLayout is true the location is - * reset and the splitPane validated. + * passed in {@code location}. If {@code continuousLayout} is {@code true} + * the location is reset and the splitPane validated. + * + * @param location the location of divider */ protected void dragDividerTo(int location) { if(getLastDragLocation() != location) { @@ -1230,7 +1274,9 @@ /** * Messaged to finish the dragging session. If not continuous display - * the dividers location will be reset. + * the dividers {@code location} will be reset. + * + * @param location the location of divider */ protected void finishDraggingTo(int location) { dragDividerTo(location); @@ -1259,6 +1305,7 @@ *

* Returns the width of one side of the divider border. * + * @return the width of one side of the divider border * @deprecated As of Java 2 platform v1.3, instead set the border on the * divider. */ @@ -1275,7 +1322,13 @@ public class BasicHorizontalLayoutManager implements LayoutManager2 { /* left, right, divider. (in this exact order) */ + /** + * The size of components. + */ protected int[] sizes; + /** + * The components. + */ protected Component[] components; /** Size of the splitpane the last time laid out. */ private int lastSplitPaneSize; @@ -1596,6 +1649,8 @@ /** * Resets the size of the Component at the passed in location. + * + * @param index the index of a component */ protected void resetSizeAt(int index) { sizes[index] = 0; @@ -1604,7 +1659,9 @@ /** - * Sets the sizes to newSizes. + * Sets the sizes to {@code newSizes}. + * + * @param newSizes the new sizes */ protected void setSizes(int[] newSizes) { System.arraycopy(newSizes, 0, sizes, 0, 3); @@ -1613,6 +1670,8 @@ /** * Returns the sizes of the components. + * + * @return the sizes of the components */ protected int[] getSizes() { int[] retSizes = new int[3]; @@ -1624,6 +1683,9 @@ /** * Returns the width of the passed in Components preferred size. + * + * @param c a component + * @return the preferred width of the component */ protected int getPreferredSizeOfComponent(Component c) { return getSizeForPrimaryAxis(c.getPreferredSize()); @@ -1632,6 +1694,9 @@ /** * Returns the width of the passed in Components minimum size. + * + * @param c a component + * @return the minimum width of the component */ int getMinimumSizeOfComponent(Component c) { return getSizeForPrimaryAxis(c.getMinimumSize()); @@ -1640,6 +1705,9 @@ /** * Returns the width of the passed in component. + * + * @param c a component + * @return the width of the component */ protected int getSizeOfComponent(Component c) { return getSizeForPrimaryAxis(c.getSize()); @@ -1648,7 +1716,11 @@ /** * Returns the available width based on the container size and - * Insets. + * {@code Insets}. + * + * @param containerSize a container size + * @param insets an insets + * @return the available width */ protected int getAvailableSize(Dimension containerSize, Insets insets) { @@ -1661,8 +1733,11 @@ /** - * Returns the left inset, unless the Insets are null in which case + * Returns the left inset, unless the {@code Insets} are null in which case * 0 is returned. + * + * @param insets the insets + * @return the left inset */ protected int getInitialLocation(Insets insets) { if(insets != null) @@ -1672,9 +1747,15 @@ /** - * Sets the width of the component c to be size, placing its - * x location at location, y to the insets.top and height - * to the containersize.height less the top and bottom insets. + * Sets the width of the component {@code c} to be {@code size}, placing its + * x location at {@code location}, y to the {@code insets.top} and height + * to the {@code containerSize.height} less the top and bottom insets. + * + * @param c a component + * @param size a new width + * @param location a new X coordinate + * @param insets an insets + * @param containerSize a container size */ protected void setComponentToSize(Component c, int size, int location, Insets insets, @@ -2021,6 +2102,9 @@ public class BasicVerticalLayoutManager extends BasicHorizontalLayoutManager { + /** + * Constructs a new instance of {@code BasicVerticalLayoutManager}. + */ public BasicVerticalLayoutManager() { super(1); }