You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pivot.apache.org by rw...@apache.org on 2015/11/04 02:30:05 UTC
svn commit: r1712454 - /pivot/trunk/wtk/src/org/apache/pivot/wtk/
Author: rwhitcomb
Date: Wed Nov 4 01:30:04 2015
New Revision: 1712454
URL: http://svn.apache.org/viewvc?rev=1712454&view=rev
Log:
PIVOT-976: More Javadoc fixes for the warnings from Java 8.
Continuing on down the list, basically. Almost all of these are
@param descriptions, although some are @return.
Also continued a little bit using the Utils.checkNull method in some
places in the components that were update. This is a bit off-track
for Javadoc, but there is no separate JIRA for these changes, so ....
Modified:
pivot/trunk/wtk/src/org/apache/pivot/wtk/ColorChooser.java
pivot/trunk/wtk/src/org/apache/pivot/wtk/ColorChooserButton.java
pivot/trunk/wtk/src/org/apache/pivot/wtk/DragSource.java
pivot/trunk/wtk/src/org/apache/pivot/wtk/GridPane.java
pivot/trunk/wtk/src/org/apache/pivot/wtk/HyperlinkButton.java
pivot/trunk/wtk/src/org/apache/pivot/wtk/ImageView.java
pivot/trunk/wtk/src/org/apache/pivot/wtk/ImageViewBindingListener.java
pivot/trunk/wtk/src/org/apache/pivot/wtk/ImageViewListener.java
pivot/trunk/wtk/src/org/apache/pivot/wtk/Keyboard.java
pivot/trunk/wtk/src/org/apache/pivot/wtk/Label.java
pivot/trunk/wtk/src/org/apache/pivot/wtk/LabelBindingListener.java
pivot/trunk/wtk/src/org/apache/pivot/wtk/LabelListener.java
pivot/trunk/wtk/src/org/apache/pivot/wtk/ListButton.java
pivot/trunk/wtk/src/org/apache/pivot/wtk/ListButtonBindingListener.java
pivot/trunk/wtk/src/org/apache/pivot/wtk/ListButtonItemListener.java
pivot/trunk/wtk/src/org/apache/pivot/wtk/ListButtonListener.java
Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/ColorChooser.java
URL: http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/ColorChooser.java?rev=1712454&r1=1712453&r2=1712454&view=diff
==============================================================================
--- pivot/trunk/wtk/src/org/apache/pivot/wtk/ColorChooser.java (original)
+++ pivot/trunk/wtk/src/org/apache/pivot/wtk/ColorChooser.java Wed Nov 4 01:30:04 2015
@@ -20,6 +20,7 @@ import java.awt.Color;
import org.apache.pivot.json.JSON;
import org.apache.pivot.util.ListenerList;
+import org.apache.pivot.util.Utils;
/**
* Component that allows the user to select a color.
@@ -32,14 +33,17 @@ public class ColorChooser extends Contai
/**
* Converts a context value to a color.
*
- * @param value
+ * @param value The value returned from the bound object.
+ * @return The value converted to a {@link Color}.
*/
public Color toColor(Object value);
/**
* Converts a color to a context value.
*
- * @param color
+ * @param color The color value selected in this component.
+ * @return The color value converted to a format suitable for
+ * persistence in the bound object.
*/
public Object valueOf(Color color);
}
@@ -103,7 +107,7 @@ public class ColorChooser extends Contai
}
/**
- * Gets the currently selected color, or <tt>null</tt> if no color is
+ * @return The currently selected color, or <tt>null</tt> if no color is
* selected.
*/
public Color getSelectedColor() {
@@ -133,15 +137,13 @@ public class ColorChooser extends Contai
* selection.
*/
public void setSelectedColor(String selectedColor) {
- if (selectedColor == null) {
- throw new IllegalArgumentException("selectedColor is null.");
- }
+ Utils.checkNull(selectedColor, "selectedColor");
setSelectedColor(Color.decode(selectedColor));
}
/**
- * Gets the data binding key that is set on this color chooser.
+ * @return The data binding key that is set on this color chooser.
*/
public String getSelectedColorKey() {
return selectedColorKey;
@@ -149,6 +151,8 @@ public class ColorChooser extends Contai
/**
* Sets this color chooser's data binding key.
+ *
+ * @param selectedColorKey The binding key for the selected color.
*/
public void setSelectedColorKey(String selectedColorKey) {
String previousSelectedColorKey = this.selectedColorKey;
@@ -164,9 +168,7 @@ public class ColorChooser extends Contai
}
public void setSelectedColorBindType(BindType selectedColorBindType) {
- if (selectedColorBindType == null) {
- throw new IllegalArgumentException();
- }
+ Utils.checkNull(selectedColorBindType, "selectedColorBindType");
BindType previousSelectedColorBindType = this.selectedColorBindType;
@@ -240,14 +242,14 @@ public class ColorChooser extends Contai
}
/**
- * Returns the color chooser selection listener list.
+ * @return The color chooser selection listener list.
*/
public ListenerList<ColorChooserSelectionListener> getColorChooserSelectionListeners() {
return colorChooserSelectionListeners;
}
/**
- * Returns the color chooser binding listener list.
+ * @return The color chooser binding listener list.
*/
public ListenerList<ColorChooserBindingListener> getColorChooserBindingListeners() {
return colorChooserBindingListeners;
Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/ColorChooserButton.java
URL: http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/ColorChooserButton.java?rev=1712454&r1=1712453&r2=1712454&view=diff
==============================================================================
--- pivot/trunk/wtk/src/org/apache/pivot/wtk/ColorChooserButton.java (original)
+++ pivot/trunk/wtk/src/org/apache/pivot/wtk/ColorChooserButton.java Wed Nov 4 01:30:04 2015
@@ -20,6 +20,7 @@ import java.awt.Color;
import org.apache.pivot.json.JSON;
import org.apache.pivot.util.ListenerList;
+import org.apache.pivot.util.Utils;
import org.apache.pivot.wtk.content.ListButtonColorItemRenderer;
/**
@@ -118,7 +119,7 @@ public class ColorChooserButton extends
}
/**
- * @return the popup window associated with this components skin
+ * @return The popup window associated with this component's skin.
*/
public Window getListPopup() {
return ((ColorChooserButton.Skin) getSkin()).getColorChooserPopup();
@@ -134,8 +135,6 @@ public class ColorChooserButton extends
}
/**
- * Returns the currently selected color.
- *
* @return The currently selected color, or <tt>null</tt> if nothing is
* selected.
*/
@@ -163,17 +162,16 @@ public class ColorChooserButton extends
* Sets the selected color.
*
* @param selectedColor A string representing a color.
+ * @throws IllegalArgumentException if the string is {@code null}.
*/
public final void setSelectedColor(String selectedColor) {
- if (selectedColor == null) {
- throw new IllegalArgumentException("selectedColor is null.");
- }
+ Utils.checkNull(selectedColor, "selectedColor");
setSelectedColor(Color.decode(selectedColor));
}
/**
- * Gets the data binding key that is set on this color chooser button.
+ * @return The data binding key that is set on this color chooser button.
*/
public String getSelectedColorKey() {
return selectedColorKey;
@@ -181,6 +179,8 @@ public class ColorChooserButton extends
/**
* Sets this color chooser button's data binding key.
+ *
+ * @param selectedColorKey The binding key for the selected color.
*/
public void setSelectedColorKey(String selectedColorKey) {
String previousSelectedColorKey = this.selectedColorKey;
@@ -197,9 +197,7 @@ public class ColorChooserButton extends
}
public void setSelectedColorBindType(BindType selectedColorBindType) {
- if (selectedColorBindType == null) {
- throw new IllegalArgumentException();
- }
+ Utils.checkNull(selectedColorBindType, "selectedColorBindType");
BindType previousSelectedColorBindType = this.selectedColorBindType;
@@ -273,14 +271,14 @@ public class ColorChooserButton extends
}
/**
- * Returns the color chooser button selection listener list.
+ * @return The color chooser button selection listener list.
*/
public ListenerList<ColorChooserButtonSelectionListener> getColorChooserButtonSelectionListeners() {
return colorChooserButtonSelectionListeners;
}
/**
- * Returns the color chooser button binding listener list.
+ * @return The color chooser button binding listener list.
*/
public ListenerList<ColorChooserButtonBindingListener> getColorChooserButtonBindingListeners() {
return colorChooserButtonBindingListeners;
Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/DragSource.java
URL: http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/DragSource.java?rev=1712454&r1=1712453&r2=1712454&view=diff
==============================================================================
--- pivot/trunk/wtk/src/org/apache/pivot/wtk/DragSource.java (original)
+++ pivot/trunk/wtk/src/org/apache/pivot/wtk/DragSource.java Wed Nov 4 01:30:04 2015
@@ -23,9 +23,9 @@ public interface DragSource {
/**
* Called by the framework to initiate a drag operation.
*
- * @param component
- * @param x
- * @param y
+ * @param component The component to drag from.
+ * @param x The X-position of the mouse at the beginning of the drag.
+ * @param y The Y-position of the mouse.
* @return <tt>true</tt> to accept the drag; <tt>false</tt> to reject it.
*/
public boolean beginDrag(Component component, int x, int y);
@@ -33,8 +33,8 @@ public interface DragSource {
/**
* Called by the framework to terminate a drag operation.
*
- * @param component
- * @param dropAction
+ * @param component The drag component.
+ * @param dropAction Which operation to perform at the end of the drag.
*/
public void endDrag(Component component, DropAction dropAction);
@@ -47,7 +47,7 @@ public interface DragSource {
public boolean isNative();
/**
- * Returns the drag content.
+ * @return The drag content.
*/
public LocalManifest getContent();
Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/GridPane.java
URL: http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/GridPane.java?rev=1712454&r1=1712453&r2=1712454&view=diff
==============================================================================
--- pivot/trunk/wtk/src/org/apache/pivot/wtk/GridPane.java (original)
+++ pivot/trunk/wtk/src/org/apache/pivot/wtk/GridPane.java Wed Nov 4 01:30:04 2015
@@ -23,6 +23,7 @@ import org.apache.pivot.collections.Arra
import org.apache.pivot.collections.Sequence;
import org.apache.pivot.util.ImmutableIterator;
import org.apache.pivot.util.ListenerList;
+import org.apache.pivot.util.Utils;
/**
* Container that arranges components in a two-dimensional grid, where every
@@ -67,9 +68,7 @@ public class GridPane extends Container
@Override
public void insert(Component component, int index) {
- if (component == null) {
- throw new IllegalArgumentException("Component is null.");
- }
+ Utils.checkNull(component, "component");
if (component.getParent() != null) {
throw new IllegalArgumentException("Component already has a parent.");
@@ -88,9 +87,7 @@ public class GridPane extends Container
Component previousComponent = cells.get(index);
if (component != previousComponent) {
- if (component == null) {
- throw new IllegalArgumentException("Component is null.");
- }
+ Utils.checkNull(component, "Component");
if (component.getParent() != null) {
throw new IllegalArgumentException("Component already has a parent.");
@@ -188,12 +185,10 @@ public class GridPane extends Container
@Override
public void insert(Row row, int index) {
- if (row == null) {
- throw new IllegalArgumentException("row is null.");
- }
+ Utils.checkNull(row, "Row");
if (row.getGridPane() != null) {
- throw new IllegalArgumentException("row is already in use by another grid pane.");
+ throw new IllegalArgumentException("Row is already in use by another grid pane.");
}
rows.insert(row, index);
@@ -336,7 +331,7 @@ public class GridPane extends Container
/**
* Creates a new grid pane with the specified column count.
*
- * @param columnCount
+ * @param columnCount Number of columns for this grid.
*/
public GridPane(int columnCount) {
if (columnCount < 0) {
@@ -359,7 +354,7 @@ public class GridPane extends Container
}
/**
- * Returns the number of columns in the grid pane.
+ * @return The number of columns in the grid pane.
*/
public int getColumnCount() {
return columnCount;
@@ -368,7 +363,7 @@ public class GridPane extends Container
/**
* Sets the number of columns in the grid pane.
*
- * @param columnCount
+ * @param columnCount The new number of columns in the grid.
*/
public void setColumnCount(int columnCount) {
int previousColumnCount = this.columnCount;
@@ -380,9 +375,7 @@ public class GridPane extends Container
}
/**
- * Returns the grid pane row sequence.
- *
- * @return The grid pane row sequence
+ * @return The grid pane row sequence.
*/
public RowSequence getRows() {
return rowSequence;
@@ -404,6 +397,7 @@ public class GridPane extends Container
* Returns the bounds of a given row.
*
* @param row The row index.
+ * @return The bounds for the given row.
*/
public Bounds getRowBounds(int row) {
GridPane.Skin gridPaneSkin = (GridPane.Skin) getSkin();
@@ -426,6 +420,7 @@ public class GridPane extends Container
* Returns the bounds of a given column.
*
* @param column The column index.
+ * @return The bounds of the given column.
*/
public Bounds getColumnBounds(int column) {
GridPane.Skin gridPaneSkin = (GridPane.Skin) getSkin();
@@ -435,10 +430,10 @@ public class GridPane extends Container
/**
* Gets the component at the specified cell in this grid pane.
*
- * @param rowIndex The row index of the cell
- * @param columnIndex The column index of the cell
+ * @param rowIndex The row index of the cell.
+ * @param columnIndex The column index of the cell.
* @return The component in the specified cell, or <tt>null</tt> if the cell
- * is empty
+ * is empty.
*/
public Component getCellComponent(int rowIndex, int columnIndex) {
Row row = rows.get(rowIndex);
@@ -456,9 +451,9 @@ public class GridPane extends Container
* Overrides the base method to check whether or not a cell component is
* being removed, and fires the appropriate event in that case.
*
- * @param index The index at which components were removed
- * @param count The number of components removed
- * @return The sequence of components that were removed
+ * @param index The index at which components were removed.
+ * @param count The number of components removed.
+ * @return The sequence of components that were removed.
*/
@Override
public Sequence<Component> remove(int index, int count) {
@@ -477,7 +472,7 @@ public class GridPane extends Container
}
/**
- * Returns the grid pane listener list.
+ * @return The grid pane listener list.
*/
public ListenerList<GridPaneListener> getGridPaneListeners() {
return gridPaneListeners;
Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/HyperlinkButton.java
URL: http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/HyperlinkButton.java?rev=1712454&r1=1712453&r2=1712454&view=diff
==============================================================================
--- pivot/trunk/wtk/src/org/apache/pivot/wtk/HyperlinkButton.java (original)
+++ pivot/trunk/wtk/src/org/apache/pivot/wtk/HyperlinkButton.java Wed Nov 4 01:30:04 2015
@@ -141,6 +141,7 @@ public class HyperlinkButton extends Lin
/**
* Access the {@link URI} which is the target of this hyperlink.
+ * @return The target for this hyperlink.
*/
public URI getUri() {
return action == null ? null : action.getUri();
Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/ImageView.java
URL: http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/ImageView.java?rev=1712454&r1=1712453&r2=1712454&view=diff
==============================================================================
--- pivot/trunk/wtk/src/org/apache/pivot/wtk/ImageView.java (original)
+++ pivot/trunk/wtk/src/org/apache/pivot/wtk/ImageView.java Wed Nov 4 01:30:04 2015
@@ -24,6 +24,7 @@ import org.apache.pivot.collections.Arra
import org.apache.pivot.collections.HashMap;
import org.apache.pivot.json.JSON;
import org.apache.pivot.util.ListenerList;
+import org.apache.pivot.util.Utils;
import org.apache.pivot.util.concurrent.Task;
import org.apache.pivot.util.concurrent.TaskListener;
import org.apache.pivot.wtk.media.Image;
@@ -45,7 +46,7 @@ public class ImageView extends Component
}
/**
- * Returns the load type supported by this mapping.
+ * @return The load type supported by this mapping.
*/
public Type getType();
@@ -53,7 +54,8 @@ public class ImageView extends Component
* Converts a value from the bind context to an image representation
* during a {@link Component#load(Object)} operation.
*
- * @param value
+ * @param value The value returned from the bound object.
+ * @return The image converted from the bound value.
*/
public Image toImage(Object value);
@@ -61,7 +63,8 @@ public class ImageView extends Component
* Converts a value from the bind context to an image location during a
* {@link Component#load(Object)} operation.
*
- * @param value
+ * @param value The value returned from the bound object.
+ * @return The value converted to an image URL.
*/
public URL toImageURL(Object value);
@@ -69,15 +72,22 @@ public class ImageView extends Component
* Converts a value from the bind context to an image resource name
* during a {@link Component#load(Object)} operation.
*
- * @param value
+ * @param value The value returned from the bound object.
+ * @return The value converted to an image name.
*/
public String toImageName(Object value);
/**
- * Converts a text string to a value to be stored in the bind context
+ * Converts an image to a value to be stored in the bind context
* during a {@link Component#store(Object)} operation.
+ * <p> Note: if the bind type is {@link Type#URL} or {@link Type#NAME} then
+ * this will likely entail also persisting the image itself
+ * somewhere else and returning the name/location of the stored
+ * image.
*
- * @param image
+ * @param image The image currently stored in the image view.
+ * @return The image converted to a value suitable for persistence
+ * in the bound object.
*/
public Object valueOf(Image image);
}
@@ -188,9 +198,7 @@ public class ImageView extends Component
* @param imageURL The location of the image to set.
*/
public final void setImage(final URL imageURL) {
- if (imageURL == null) {
- throw new IllegalArgumentException("imageURL is null.");
- }
+ Utils.checkNull(imageURL, "imageURL");
Image imageLocal = (Image) ApplicationContext.getResourceCache().get(imageURL);
@@ -253,9 +261,7 @@ public class ImageView extends Component
* @see #setImage(URL)
*/
public final void setImage(String imageName) {
- if (imageName == null) {
- throw new IllegalArgumentException("imageName is null.");
- }
+ Utils.checkNull(imageName, "imageName");
ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
URL url = classLoader.getResource(imageName.substring(1));
@@ -317,9 +323,7 @@ public class ImageView extends Component
}
public void setImageBindType(BindType imageBindType) {
- if (imageBindType == null) {
- throw new IllegalArgumentException();
- }
+ Utils.checkNull(imageBindType, "imageBindType");
BindType previousImageBindType = this.imageBindType;
@@ -400,14 +404,14 @@ public class ImageView extends Component
}
/**
- * Returns the image view listener list.
+ * @return The image view listener list.
*/
public ListenerList<ImageViewListener> getImageViewListeners() {
return imageViewListeners;
}
/**
- * Returns the image view binding listener list.
+ * @return The image view binding listener list.
*/
public ListenerList<ImageViewBindingListener> getImageViewBindingListeners() {
return imageViewBindingListeners;
Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/ImageViewBindingListener.java
URL: http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/ImageViewBindingListener.java?rev=1712454&r1=1712453&r2=1712454&view=diff
==============================================================================
--- pivot/trunk/wtk/src/org/apache/pivot/wtk/ImageViewBindingListener.java (original)
+++ pivot/trunk/wtk/src/org/apache/pivot/wtk/ImageViewBindingListener.java Wed Nov 4 01:30:04 2015
@@ -44,24 +44,24 @@ public interface ImageViewBindingListene
/**
* Called when an image view's image key has changed.
*
- * @param imageView
- * @param previousImageKey
+ * @param imageView The image view whose binding has changed.
+ * @param previousImageKey The previous binding key for the image.
*/
public void imageKeyChanged(ImageView imageView, String previousImageKey);
/**
* Called when a image views's image bind type has changed.
*
- * @param imageView
- * @param previousImageBindType
+ * @param imageView The image view whose binding has changed.
+ * @param previousImageBindType The previous bind type for the image.
*/
public void imageBindTypeChanged(ImageView imageView, BindType previousImageBindType);
/**
- * Called when an image view's text bind mapping has changed.
+ * Called when an image view's bind mapping has changed.
*
- * @param imageView
- * @param previousImageBindMapping
+ * @param imageView The image view whose binding has changed.
+ * @param previousImageBindMapping The previous bind mapping for the image.
*/
public void imageBindMappingChanged(ImageView imageView,
ImageView.ImageBindMapping previousImageBindMapping);
Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/ImageViewListener.java
URL: http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/ImageViewListener.java?rev=1712454&r1=1712453&r2=1712454&view=diff
==============================================================================
--- pivot/trunk/wtk/src/org/apache/pivot/wtk/ImageViewListener.java (original)
+++ pivot/trunk/wtk/src/org/apache/pivot/wtk/ImageViewListener.java Wed Nov 4 01:30:04 2015
@@ -40,15 +40,15 @@ public interface ImageViewListener {
/**
* Called when an image view's image has changed.
*
- * @param imageView
- * @param previousImage
+ * @param imageView The image view whose image has changed.
+ * @param previousImage The previous image associated with this image view.
*/
public void imageChanged(ImageView imageView, Image previousImage);
/**
* Called when an image view's asynchronous flag has changed.
*
- * @param imageView
+ * @param imageView The image view whose asynchronous flag has changed.
*/
public void asynchronousChanged(ImageView imageView);
}
Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/Keyboard.java
URL: http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/Keyboard.java?rev=1712454&r1=1712453&r2=1712454&view=diff
==============================================================================
--- pivot/trunk/wtk/src/org/apache/pivot/wtk/Keyboard.java (original)
+++ pivot/trunk/wtk/src/org/apache/pivot/wtk/Keyboard.java Wed Nov 4 01:30:04 2015
@@ -20,6 +20,7 @@ import java.awt.event.InputEvent;
import java.awt.event.KeyEvent;
import java.lang.reflect.Field;
import java.util.Locale;
+import org.apache.pivot.util.Utils;
/**
* Class representing the system keyboard.
@@ -116,9 +117,7 @@ public final class Keyboard {
}
public static KeyStroke decode(String value) {
- if (value == null) {
- throw new IllegalArgumentException("value is null.");
- }
+ Utils.checkNull(value, "value");
int keyCode = KeyCode.UNDEFINED;
int modifiersLocal = 0x00;
@@ -261,7 +260,7 @@ public final class Keyboard {
private static int modifiers = 0;
/**
- * Returns a bitfield representing the keyboard modifiers that are currently
+ * @return A bitfield representing the keyboard modifiers that are currently
* pressed.
*/
public static int getModifiers() {
@@ -275,7 +274,7 @@ public final class Keyboard {
/**
* Tests the pressed state of a modifier.
*
- * @param modifier
+ * @param modifier The modifier to test.
* @return <tt>true</tt> if the modifier is pressed; <tt>false</tt>,
* otherwise.
*/
Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/Label.java
URL: http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/Label.java?rev=1712454&r1=1712453&r2=1712454&view=diff
==============================================================================
--- pivot/trunk/wtk/src/org/apache/pivot/wtk/Label.java (original)
+++ pivot/trunk/wtk/src/org/apache/pivot/wtk/Label.java Wed Nov 4 01:30:04 2015
@@ -18,6 +18,7 @@ package org.apache.pivot.wtk;
import org.apache.pivot.json.JSON;
import org.apache.pivot.util.ListenerList;
+import org.apache.pivot.util.Utils;
/**
* Component that displays a string of text.
@@ -31,7 +32,8 @@ public class Label extends Component {
* Converts a value from the bind context to a text representation
* during a {@link Component#load(Object)} operation.
*
- * @param value
+ * @param value The bound value from the component.
+ * @return The value converted to a {@link String} suitable for the label text.
*/
public String toString(Object value);
@@ -39,7 +41,9 @@ public class Label extends Component {
* Converts a text string to a value to be stored in the bind context
* during a {@link Component#store(Object)} operation.
*
- * @param text
+ * @param text The label text to be converted.
+ * @return The text value converted to a value suitable for persistence
+ * in the bound object.
*/
public Object valueOf(String text);
}
@@ -108,9 +112,7 @@ public class Label extends Component {
}
/**
- * Returns the label's text.
- *
- * @return The text.
+ * @return The label's text.
*/
public String getText() {
return text;
@@ -119,12 +121,12 @@ public class Label extends Component {
/**
* Set the text of the Label.
*
- * @param text The text to set, must be not null.
+ * @param text The text to set, must be not {@code null}.
+ * @throws IllegalArgumentException if the text is {@code null} or if
+ * the text length exceeds the allowed maximum.
*/
public void setText(String text) {
- if (text == null) {
- throw new IllegalArgumentException();
- }
+ Utils.checkNull(text, "text");
if (text.length() > maximumLength) {
throw new IllegalArgumentException("Text length is greater than maximum length.");
@@ -142,7 +144,7 @@ public class Label extends Component {
* null (to avoid the setText throw an IllegalArgumentException). This is
* useful to be called by code.
*
- * @param text The text to set
+ * @param text The text to set (if {@code null} will set an empty string {@code ""}).
* @see #setText
*/
public void setTextOrEmpty(String text) {
@@ -159,8 +161,6 @@ public class Label extends Component {
}
/**
- * Returns the maximum length of the label text.
- *
* @return The maximum length of the label text.
*/
public int getMaximumLength() {
@@ -171,6 +171,7 @@ public class Label extends Component {
* Sets the maximum length of the label text.
*
* @param maximumLength The maximum length of the label text.
+ * @throws IllegalArgumentException if the length given is negative.
*/
public void setMaximumLength(int maximumLength) {
if (maximumLength < 0) {
@@ -210,9 +211,7 @@ public class Label extends Component {
}
public void setTextBindType(BindType textBindType) {
- if (textBindType == null) {
- throw new IllegalArgumentException();
- }
+ Utils.checkNull(textBindType, "textBindType");
BindType previousTextBindType = this.textBindType;
Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/LabelBindingListener.java
URL: http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/LabelBindingListener.java?rev=1712454&r1=1712453&r2=1712454&view=diff
==============================================================================
--- pivot/trunk/wtk/src/org/apache/pivot/wtk/LabelBindingListener.java (original)
+++ pivot/trunk/wtk/src/org/apache/pivot/wtk/LabelBindingListener.java Wed Nov 4 01:30:04 2015
@@ -44,24 +44,24 @@ public interface LabelBindingListener {
/**
* Called when a label's text key has changed.
*
- * @param label
- * @param previousTextKey
+ * @param label The label whose binding has changed.
+ * @param previousTextKey The previous binding key for the label text.
*/
public void textKeyChanged(Label label, String previousTextKey);
/**
* Called when a label's text bind type has changed.
*
- * @param label
- * @param previousTextBindType
+ * @param label The label whose binding has changed.
+ * @param previousTextBindType The previous bind type for the label text.
*/
public void textBindTypeChanged(Label label, BindType previousTextBindType);
/**
* Called when a label's text bind mapping has changed.
*
- * @param label
- * @param previousTextBindMapping
+ * @param label The label whose binding has changed.
+ * @param previousTextBindMapping The previous bind mapping for the label text.
*/
public void textBindMappingChanged(Label label, Label.TextBindMapping previousTextBindMapping);
}
Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/LabelListener.java
URL: http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/LabelListener.java?rev=1712454&r1=1712453&r2=1712454&view=diff
==============================================================================
--- pivot/trunk/wtk/src/org/apache/pivot/wtk/LabelListener.java (original)
+++ pivot/trunk/wtk/src/org/apache/pivot/wtk/LabelListener.java Wed Nov 4 01:30:04 2015
@@ -39,16 +39,16 @@ public interface LabelListener {
/**
* Called when a label's text has changed.
*
- * @param label
- * @param previousText
+ * @param label The label that has changed.
+ * @param previousText The previous text associated with the label.
*/
public void textChanged(Label label, String previousText);
/**
* Called when a label text maximum length has changed.
*
- * @param label
- * @param previousMaximumLength
+ * @param label The label that has changed.
+ * @param previousMaximumLength The previous maximum text length for the label.
*/
public void maximumLengthChanged(Label label, int previousMaximumLength);
Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/ListButton.java
URL: http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/ListButton.java?rev=1712454&r1=1712453&r2=1712454&view=diff
==============================================================================
--- pivot/trunk/wtk/src/org/apache/pivot/wtk/ListButton.java (original)
+++ pivot/trunk/wtk/src/org/apache/pivot/wtk/ListButton.java Wed Nov 4 01:30:04 2015
@@ -30,6 +30,7 @@ import org.apache.pivot.json.JSONSeriali
import org.apache.pivot.serialization.SerializationException;
import org.apache.pivot.util.Filter;
import org.apache.pivot.util.ListenerList;
+import org.apache.pivot.util.Utils;
import org.apache.pivot.wtk.ListView.ListDataBindMapping;
import org.apache.pivot.wtk.content.ListButtonDataRenderer;
import org.apache.pivot.wtk.content.ListViewItemRenderer;
@@ -301,7 +302,7 @@ public class ListButton extends Button {
/**
* Creates a list button with the given button data and an empty list.
*
- * @param buttonData
+ * @param buttonData The button data (that is text and/or icon) for the list button.
*/
public ListButton(Object buttonData) {
this(buttonData, new ArrayList<>());
@@ -310,7 +311,7 @@ public class ListButton extends Button {
/**
* Creates a list button with no button data and the given list data.
*
- * @param listData
+ * @param listData The initial list data for the list button.
*/
public ListButton(List<?> listData) {
this(null, listData);
@@ -379,9 +380,7 @@ public class ListButton extends Button {
*/
@SuppressWarnings("unchecked")
public void setListData(List<?> listData) {
- if (listData == null) {
- throw new IllegalArgumentException("listData is null.");
- }
+ Utils.checkNull(listData, "listData");
List<?> previousListData = this.listData;
@@ -413,11 +412,11 @@ public class ListButton extends Button {
*
* @param listData The list data to be presented by the list button as a
* JSON array.
+ * @throws IllegalArgumentException if the data string is {@code null} or
+ * cannot be propertly parsed into a list.
*/
public final void setListData(String listData) {
- if (listData == null) {
- throw new IllegalArgumentException("listData is null.");
- }
+ Utils.checkNull(listData, "listData");
try {
setListData(JSONSerializer.parseList(listData));
@@ -431,11 +430,11 @@ public class ListButton extends Button {
*
* @param listData A URL referring to a JSON file containing the data to be
* presented by the list button.
+ * @throws IllegalArgumentException if the URL is {@code null} or
+ * the URL data stream cannot be propertly parsed into a list.
*/
public void setListData(URL listData) {
- if (listData == null) {
- throw new IllegalArgumentException("listData is null.");
- }
+ Utils.checkNull(listData, "listData");
JSONSerializer jsonSerializer = new JSONSerializer();
@@ -474,7 +473,7 @@ public class ListButton extends Button {
}
/**
- * Returns the list button's repeatable flag.
+ * @return The list button's repeatable flag.
*/
public boolean isRepeatable() {
return repeatable;
@@ -483,7 +482,8 @@ public class ListButton extends Button {
/**
* Sets the list button's repeatable flag.
*
- * @param repeatable
+ * @param repeatable Whether this list button's action is repeatable
+ * (that is, the action can be triggered even if the selection is unchanged).
*/
public void setRepeatable(boolean repeatable) {
if (this.repeatable != repeatable) {
@@ -581,7 +581,7 @@ public class ListButton extends Button {
}
/**
- * Returns the list size.
+ * @return The list size.
*/
public int getListSize() {
return listSize;
@@ -591,7 +591,8 @@ public class ListButton extends Button {
* Sets the list size. If the number of items in the list exceeds this
* value, the list will scroll.
*
- * @param listSize
+ * @param listSize The number of visible items in the list.
+ * @throws IllegalArgumentException if the specified size is negative.
*/
public void setListSize(int listSize) {
if (listSize < -1) {
@@ -787,28 +788,28 @@ public class ListButton extends Button {
}
/**
- * Returns the list button listener list.
+ * @return The list button listener list.
*/
public ListenerList<ListButtonListener> getListButtonListeners() {
return listButtonListeners;
}
/**
- * Returns the list button item listener list.
+ * @return The list button item listener list.
*/
public ListenerList<ListButtonItemListener> getListButtonItemListeners() {
return listButtonItemListeners;
}
/**
- * Returns the list button selection listener list.
+ * @return The list button selection listener list.
*/
public ListenerList<ListButtonSelectionListener> getListButtonSelectionListeners() {
return listButtonSelectionListeners;
}
/**
- * Returns the list button binding listener list.
+ * @return The list button binding listener list.
*/
public ListenerList<ListButtonBindingListener> getListButtonBindingListeners() {
return listButtonBindingListeners;
Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/ListButtonBindingListener.java
URL: http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/ListButtonBindingListener.java?rev=1712454&r1=1712453&r2=1712454&view=diff
==============================================================================
--- pivot/trunk/wtk/src/org/apache/pivot/wtk/ListButtonBindingListener.java (original)
+++ pivot/trunk/wtk/src/org/apache/pivot/wtk/ListButtonBindingListener.java Wed Nov 4 01:30:04 2015
@@ -61,24 +61,24 @@ public interface ListButtonBindingListen
/**
* Called when a list button's list data key has changed.
*
- * @param listButton
- * @param previousListDataKey
+ * @param listButton The list button that has changed.
+ * @param previousListDataKey The previous binding key for the list data.
*/
public void listDataKeyChanged(ListButton listButton, String previousListDataKey);
/**
* Called when a list button's list data bind type has changed.
*
- * @param listButton
- * @param previousListDataBindType
+ * @param listButton The list button that has changed.
+ * @param previousListDataBindType The previous bind type for the list data.
*/
public void listDataBindTypeChanged(ListButton listButton, BindType previousListDataBindType);
/**
* Called when a list button's list data bind mapping has changed.
*
- * @param listButton
- * @param previousListDataBindMapping
+ * @param listButton The list button that has changed.
+ * @param previousListDataBindMapping The previous bind mapping for the list data.
*/
public void listDataBindMappingChanged(ListButton listButton,
ListView.ListDataBindMapping previousListDataBindMapping);
@@ -86,16 +86,16 @@ public interface ListButtonBindingListen
/**
* Called when a list button's selected item key has changed.
*
- * @param listButton
- * @param previousSelectedItemKey
+ * @param listButton The list button that has changed.
+ * @param previousSelectedItemKey The previous binding key for the button's selected item.
*/
public void selectedItemKeyChanged(ListButton listButton, String previousSelectedItemKey);
/**
* Called when a list button's selected item bind type has changed.
*
- * @param listButton
- * @param previousSelectedItemBindType
+ * @param listButton The list button that has changed.
+ * @param previousSelectedItemBindType The previous bind type for the selected item.
*/
public void selectedItemBindTypeChanged(ListButton listButton,
BindType previousSelectedItemBindType);
@@ -103,8 +103,8 @@ public interface ListButtonBindingListen
/**
* Called when a list button's selected item bind mapping has changed.
*
- * @param listButton
- * @param previousSelectedItemBindMapping
+ * @param listButton The list button that has changed.
+ * @param previousSelectedItemBindMapping The previous bind mapping for the button's selected item.
*/
public void selectedItemBindMappingChanged(ListButton listButton,
ListView.ItemBindMapping previousSelectedItemBindMapping);
Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/ListButtonItemListener.java
URL: http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/ListButtonItemListener.java?rev=1712454&r1=1712453&r2=1712454&view=diff
==============================================================================
--- pivot/trunk/wtk/src/org/apache/pivot/wtk/ListButtonItemListener.java (original)
+++ pivot/trunk/wtk/src/org/apache/pivot/wtk/ListButtonItemListener.java Wed Nov 4 01:30:04 2015
@@ -53,39 +53,39 @@ public interface ListButtonItemListener
/**
* Called when an item is inserted into a list button's list data.
*
- * @param listButton
- * @param index
+ * @param listButton The list button that has changed.
+ * @param index The index where the new data was inserted.
*/
public void itemInserted(ListButton listButton, int index);
/**
* Called when items are removed from a list button's list data.
*
- * @param listButton
- * @param index
- * @param count
+ * @param listButton The list button that has changed.
+ * @param index The starting index of the removed data items.
+ * @param count The number of items removed.
*/
public void itemsRemoved(ListButton listButton, int index, int count);
/**
* Called when an item is updated within a list button's list data.
*
- * @param listButton
- * @param index
+ * @param listButton The list button whose data has changed.
+ * @param index The index into the data list of the updated item.
*/
public void itemUpdated(ListButton listButton, int index);
/**
* Called when a list button's list data has been cleared.
*
- * @param listButton
+ * @param listButton The list button whose data was cleared.
*/
public void itemsCleared(ListButton listButton);
/**
* Called when a list button's list data is sorted.
*
- * @param listButton
+ * @param listButton The list button whose data has been sorted.
*/
public void itemsSorted(ListButton listButton);
}
Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/ListButtonListener.java
URL: http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/ListButtonListener.java?rev=1712454&r1=1712453&r2=1712454&view=diff
==============================================================================
--- pivot/trunk/wtk/src/org/apache/pivot/wtk/ListButtonListener.java (original)
+++ pivot/trunk/wtk/src/org/apache/pivot/wtk/ListButtonListener.java Wed Nov 4 01:30:04 2015
@@ -58,16 +58,16 @@ public interface ListButtonListener {
/**
* Called when a list button's list data has changed.
*
- * @param listButton
- * @param previousListData
+ * @param listButton The list button that has changed.
+ * @param previousListData The previous list data.
*/
public void listDataChanged(ListButton listButton, List<?> previousListData);
/**
* Called when a list button's item renderer has changed.
*
- * @param listButton
- * @param previousItemRenderer
+ * @param listButton The list button that was changed.
+ * @param previousItemRenderer The previous renderer for the button's items.
*/
public void itemRendererChanged(ListButton listButton,
ListView.ItemRenderer previousItemRenderer);
@@ -75,15 +75,15 @@ public interface ListButtonListener {
/**
* Called when a list button's repeatable flag has changed.
*
- * @param listButton
+ * @param listButton The list button that has changed.
*/
public void repeatableChanged(ListButton listButton);
/**
* Called when a list button's disabled item filter has changed.
*
- * @param listButton
- * @param previousDisabledItemFilter
+ * @param listButton The list button that has changed.
+ * @param previousDisabledItemFilter The previous disabled item filter for the list button.
*/
public void disabledItemFilterChanged(ListButton listButton,
Filter<?> previousDisabledItemFilter);
@@ -91,8 +91,8 @@ public interface ListButtonListener {
/**
* Called when a list button's list size has changed.
*
- * @param listButton
- * @param previousListSize
+ * @param listButton The list button that has changed.
+ * @param previousListSize The previous value of the visible list size.
*/
public void listSizeChanged(ListButton listButton, int previousListSize);
}