Author: rwhitcomb
Date: Tue Nov 3 20:31:41 2015
New Revision: 1712396
URL: http://svn.apache.org/viewvc?rev=1712396&view=rev
Log:
PIVOT-976: More Javadoc fixes for the warnings discovered by Java 8.
Now we're into more files in the A*-G* range, mostly listeners, but some
components as well. Added some @throws mostly for IllegalArgumentException.
Modified:
pivot/trunk/wtk/src/org/apache/pivot/wtk/Application.java
pivot/trunk/wtk/src/org/apache/pivot/wtk/ApplicationContext.java
pivot/trunk/wtk/src/org/apache/pivot/wtk/BrowserApplicationContext.java
pivot/trunk/wtk/src/org/apache/pivot/wtk/Calendar.java
pivot/trunk/wtk/src/org/apache/pivot/wtk/CalendarButton.java
pivot/trunk/wtk/src/org/apache/pivot/wtk/Clipboard.java
pivot/trunk/wtk/src/org/apache/pivot/wtk/DesktopApplicationContext.java
pivot/trunk/wtk/src/org/apache/pivot/wtk/Editor.java
pivot/trunk/wtk/src/org/apache/pivot/wtk/ExpanderListener.java
pivot/trunk/wtk/src/org/apache/pivot/wtk/FileBrowser.java
pivot/trunk/wtk/src/org/apache/pivot/wtk/FileBrowserListener.java
pivot/trunk/wtk/src/org/apache/pivot/wtk/FileBrowserSheet.java
pivot/trunk/wtk/src/org/apache/pivot/wtk/FileBrowserSheetListener.java
pivot/trunk/wtk/src/org/apache/pivot/wtk/FillPaneListener.java
pivot/trunk/wtk/src/org/apache/pivot/wtk/Form.java
pivot/trunk/wtk/src/org/apache/pivot/wtk/FormAttributeListener.java
pivot/trunk/wtk/src/org/apache/pivot/wtk/FormListener.java
pivot/trunk/wtk/src/org/apache/pivot/wtk/FrameListener.java
pivot/trunk/wtk/src/org/apache/pivot/wtk/GraphicsUtilities.java
pivot/trunk/wtk/src/org/apache/pivot/wtk/GridPaneListener.java
pivot/trunk/wtk/src/org/apache/pivot/wtk/Window.java
Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/Application.java
URL:
http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/Application.java?rev=1712396&r1=1712395&r2=1712396&view=diff
==============================================================================
--- pivot/trunk/wtk/src/org/apache/pivot/wtk/Application.java (original)
+++ pivot/trunk/wtk/src/org/apache/pivot/wtk/Application.java Tue Nov 3
20:31:41 2015
@@ -109,6 +109,7 @@ public interface Application {
*
* @param display The display on which this application was started.
* @param properties Initialization properties passed to the application.
+ * @throws Exception if there is any problem during startup.
*/
public void startup(Display display, Map<String, String> properties)
throws Exception;
@@ -118,16 +119,21 @@ public interface Application {
* @param optional If <tt>true</tt>, the shutdown may be cancelled by
* returning a value of <tt>true</tt>.
* @return <tt>true</tt> to cancel shutdown, <tt>false</tt> to continue.
+ * @throws Exception if there is a problem during shutdown.
*/
public boolean shutdown(boolean optional) throws Exception;
/**
* Called to notify the application that it is being suspended.
+ *
+ * @throws Exception if there is a problem doing the suspend.
*/
public void suspend() throws Exception;
/**
* Called when a suspended application has been resumed.
+ *
+ * @throws Exception if there is a problem doing the resume.
*/
public void resume() throws Exception;
}
Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/ApplicationContext.java
URL:
http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/ApplicationContext.java?rev=1712396&r1=1712395&r2=1712396&view=diff
==============================================================================
--- pivot/trunk/wtk/src/org/apache/pivot/wtk/ApplicationContext.java (original)
+++ pivot/trunk/wtk/src/org/apache/pivot/wtk/ApplicationContext.java Tue Nov 3
20:31:41 2015
@@ -374,7 +374,7 @@ public abstract class ApplicationContext
}
/**
- * Access the current scale (or zoom) factor for the entire
application's
+ * @return The current scale (or zoom) factor for the entire
application's
* display.
* @see #setScale
*/
@@ -387,6 +387,7 @@ public abstract class ApplicationContext
* the entire application's display.
* <p> For the main application window, a {@link
org.apache.pivot.wtk.effects.ScaleDecorator}
* cannot be used. This method (and related ones) must be used
instead.
+ * @param scale The new scale (zoom) factor for the entire display.
* @see #scaleUp
* @see #scaleDown
* @see #getScale
@@ -457,6 +458,7 @@ public abstract class ApplicationContext
/**
* Under some conditions, e.g. running under Linux in an applet,
* volatile buffering can reduce performance.
+ * @param enabled Whether or not to use volatile image painting.
*/
public void setVolatileImagePaintEnabled(boolean enabled) {
volatileImagePaintEnabled = enabled;
@@ -1747,7 +1749,7 @@ public abstract class ApplicationContext
}
/**
- * Resource properties accessor.
+ * @return The dictionary of cached resources.
*/
public static ResourceCacheDictionary getResourceCache() {
return resourceCacheDictionary;
@@ -1757,7 +1759,7 @@ public abstract class ApplicationContext
* Adds the styles from a named stylesheet to the named or typed style
* collections.
*
- * @param resourceName
+ * @param resourceName The resource name of the stylesheet to apply.
*/
@SuppressWarnings("unchecked")
public static void applyStylesheet(String resourceName) {
@@ -1830,6 +1832,7 @@ public abstract class ApplicationContext
* @param callback The task to execute.
* @param delay The length of time to wait before executing the task (in
* milliseconds).
+ * @return The callback object.
*/
public static ScheduledCallback scheduleCallback(Runnable callback, long
delay) {
ScheduledCallback scheduledCallback = new ScheduledCallback(callback);
@@ -1856,6 +1859,7 @@ public abstract class ApplicationContext
* @param callback The task to execute.
* @param period The interval at which the task will be repeated (in
* milliseconds).
+ * @return The callback object.
*/
public static ScheduledCallback scheduleRecurringCallback(Runnable
callback, long period) {
return scheduleRecurringCallback(callback, 0, period);
@@ -1870,6 +1874,7 @@ public abstract class ApplicationContext
* task (milliseconds).
* @param period The interval at which the task will be repeated (also in
* milliseconds).
+ * @return The callback object.
*/
public static ScheduledCallback scheduleRecurringCallback(Runnable
callback, long delay,
long period) {
@@ -1895,6 +1900,7 @@ public abstract class ApplicationContext
* returns without waiting for the task to complete.
*
* @param callback The task to execute.
+ * @return The callback object (used to manipulate or wait for the task).
*/
public static QueuedCallback queueCallback(Runnable callback) {
return queueCallback(callback, false);
@@ -1907,6 +1913,7 @@ public abstract class ApplicationContext
* @param callback The task to execute.
* @param wait If <tt>true</tt>, does not return until the task has
* executed. Otherwise, returns immediately.
+ * @return The callback object (used to manipulate or wait for the task).
*/
public static QueuedCallback queueCallback(Runnable callback, boolean
wait) {
QueuedCallback queuedCallback = new QueuedCallback(callback);
Modified:
pivot/trunk/wtk/src/org/apache/pivot/wtk/BrowserApplicationContext.java
URL:
http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/BrowserApplicationContext.java?rev=1712396&r1=1712395&r2=1712396&view=diff
==============================================================================
--- pivot/trunk/wtk/src/org/apache/pivot/wtk/BrowserApplicationContext.java
(original)
+++ pivot/trunk/wtk/src/org/apache/pivot/wtk/BrowserApplicationContext.java Tue
Nov 3 20:31:41 2015
@@ -351,6 +351,8 @@ public final class BrowserApplicationCon
* Retrieves a named application.
*
* @param name The name of the applet hosting the application.
+ * @return The application being run in the given applet (if any).
+ * @throws IllegalArgumentException if the name is {@code null}.
*/
public static Application getApplication(String name) {
if (name == null) {
@@ -371,8 +373,9 @@ public final class BrowserApplicationCon
/**
* Evaluates a script in the page context and returns the result.
*
- * @param script
- * @param application
+ * @param script The script to be run.
+ * @param application The application used to find the correct applet.
+ * @return The result of the script evaluation.
*/
public static Object eval(String script, Application application) {
if (application == null) {
Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/Calendar.java
URL:
http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/Calendar.java?rev=1712396&r1=1712395&r2=1712396&view=diff
==============================================================================
--- pivot/trunk/wtk/src/org/apache/pivot/wtk/Calendar.java (original)
+++ pivot/trunk/wtk/src/org/apache/pivot/wtk/Calendar.java Tue Nov 3 20:31:41
2015
@@ -37,14 +37,16 @@ public class Calendar extends Container
/**
* Converts a context value to a calendar date.
*
- * @param value
+ * @param value The value retrieved from the bound object.
+ * @return The value converted to a calendar date.
*/
public CalendarDate toDate(Object value);
/**
* Converts a calendar date to a context value.
*
- * @param calendarDate
+ * @param calendarDate The current calendar date value from the
component.
+ * @return The converted object value suitable for persistence in the
bound object.
*/
public Object valueOf(CalendarDate calendarDate);
}
@@ -154,6 +156,8 @@ public class Calendar extends Container
/**
* Gets the year to which this calendar is currently set.
+ *
+ * @return The current year value.
*/
public int getYear() {
return year;
@@ -161,6 +165,8 @@ public class Calendar extends Container
/**
* Sets this calendar's year.
+ *
+ * @param year The new year to set this calendar to.
*/
public void setYear(int year) {
int previousYear = this.year;
@@ -173,6 +179,8 @@ public class Calendar extends Container
/**
* Gets the month to which this calendar is currently set.
+ *
+ * @return The current month value.
*/
public int getMonth() {
return month;
@@ -180,6 +188,8 @@ public class Calendar extends Container
/**
* Sets this calendar's month.
+ *
+ * @param month The new month value to set this calendar to.
*/
public void setMonth(int month) {
int previousMonth = this.month;
@@ -191,7 +201,7 @@ public class Calendar extends Container
}
/**
- * Gets the currently selected date, or <tt>null</tt> if no date is
+ * @return The currently selected date, or <tt>null</tt> if no date is
* selected.
*/
public CalendarDate getSelectedDate() {
@@ -220,6 +230,7 @@ public class Calendar extends Container
*
* @param selectedDate A string in the form of <tt>[YYYY]-[MM]-[DD]</tt>
* (e.g. 2008-07-23)
+ * @throws IllegalArgumentException if the given date is {@code null}.
*/
public final void setSelectedDate(String selectedDate) {
if (selectedDate == null) {
@@ -230,7 +241,7 @@ public class Calendar extends Container
}
/**
- * Returns the locale used to present calendar data.
+ * @return The locale used to present calendar data.
*/
public Locale getLocale() {
return locale;
@@ -239,7 +250,8 @@ public class Calendar extends Container
/**
* Sets the locale used to present calendar data.
*
- * @param locale
+ * @param locale The new locale for this calendar.
+ * @throws IllegalArgumentException if the locale argument is {@code null}.
*/
public void setLocale(Locale locale) {
if (locale == null) {
@@ -261,6 +273,7 @@ public class Calendar extends Container
* following rules: <ul> <li>If variant is specified, language and country
* are required;</li> <li>Otherwise, if country is specified, language is
* required;</li> <li>Otherwise, language is required.</li> </ul>
+ * @throws IllegalArgumentException if the given locale dictionary is
{@code null}.
*/
public void setLocale(Dictionary<String, ?> locale) {
if (locale == null) {
@@ -285,6 +298,8 @@ public class Calendar extends Container
*
* @param locale A JSON map containing values for language, country, and
* variant.
+ * @throws IllegalArgumentException if the locale string is {@code null}
+ * or if it cannot be parsed successfully.
* @see #setLocale(Dictionary)
*/
public void setLocale(String locale) {
@@ -314,6 +329,8 @@ public class Calendar extends Container
/**
* Gets the data binding key that is set on this calendar.
+ *
+ * @return The current value of the selected date binding key.
*/
public String getSelectedDateKey() {
return selectedDateKey;
@@ -321,6 +338,8 @@ public class Calendar extends Container
/**
* Sets this calendar's data binding key.
+ *
+ * @param selectedDateKey The new key to use for binding to the selected
date.
*/
public void setSelectedDateKey(String selectedDateKey) {
String previousSelectedDateKey = this.selectedDateKey;
@@ -400,21 +419,21 @@ public class Calendar extends Container
}
/**
- * Returns the calendar listener list.
+ * @return The calendar listener list.
*/
public ListenerList<CalendarListener> getCalendarListeners() {
return calendarListeners;
}
/**
- * Returns the calendar selection listener list.
+ * @return The calendar selection listener list.
*/
public ListenerList<CalendarSelectionListener>
getCalendarSelectionListeners() {
return calendarSelectionListeners;
}
/**
- * Returns the calendar binding listener list.
+ * @return The calendar binding listener list.
*/
public ListenerList<CalendarBindingListener> getCalendarBindingListeners()
{
return calendarBindingListeners;
Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/CalendarButton.java
URL:
http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/CalendarButton.java?rev=1712396&r1=1712395&r2=1712396&view=diff
==============================================================================
--- pivot/trunk/wtk/src/org/apache/pivot/wtk/CalendarButton.java (original)
+++ pivot/trunk/wtk/src/org/apache/pivot/wtk/CalendarButton.java Tue Nov 3
20:31:41 2015
@@ -179,7 +179,7 @@ public class CalendarButton extends Butt
}
/**
- * Gets the year to which this calendar button is currently set.
+ * @return The year to which this calendar button is currently set.
*/
public int getYear() {
return year;
@@ -187,6 +187,8 @@ public class CalendarButton extends Butt
/**
* Sets this calendar's year.
+ *
+ * @param year The new current year for this calendar button.
*/
public void setYear(int year) {
int previousYear = this.year;
@@ -198,7 +200,7 @@ public class CalendarButton extends Butt
}
/**
- * Gets the month to which this calendar button is currently set.
+ * @return The month to which this calendar button is currently set.
*/
public int getMonth() {
return month;
@@ -206,6 +208,8 @@ public class CalendarButton extends Butt
/**
* Sets this calendar's month.
+ *
+ * @param month The new month value to set this calendar button to.
*/
public void setMonth(int month) {
int previousMonth = this.month;
@@ -248,6 +252,7 @@ public class CalendarButton extends Butt
*
* @param selectedDate A string in the form of <tt>[YYYY]-[MM]-[DD]</tt>
* (e.g. 2008-07-23)
+ * @throws IllegalArgumentException if the selected data value is {@code
null}.
*/
public final void setSelectedDate(String selectedDate) {
if (selectedDate == null) {
@@ -258,7 +263,7 @@ public class CalendarButton extends Butt
}
/**
- * Returns the locale used to present calendar data.
+ * @return The locale used to present calendar data.
*/
public Locale getLocale() {
return locale;
@@ -267,7 +272,8 @@ public class CalendarButton extends Butt
/**
* Sets the locale used to present calendar data.
*
- * @param locale
+ * @param locale The new locale used to format/present the data.
+ * @throws IllegalArgumentException if the given locale is {@code null}.
*/
public void setLocale(Locale locale) {
if (locale == null) {
@@ -289,6 +295,7 @@ public class CalendarButton extends Butt
* following rules: <ul> <li>If variant is specified, language and country
* are required;</li> <li>Otherwise, if country is specified, language is
* required;</li> <li>Otherwise, language is required.</li> </ul>
+ * @throws IllegalArgumentException if the given locale dictionary is
{@code null}.
*/
public void setLocale(Dictionary<String, ?> locale) {
if (locale == null) {
@@ -313,6 +320,8 @@ public class CalendarButton extends Butt
*
* @param locale A JSON map containing values for language, country, and
* variant.
+ * @throws IllegalArgumentException if the locale string is {@code null} or
+ * if there is a problem parsing the string.
* @see #setLocale(Dictionary)
*/
public void setLocale(String locale) {
@@ -341,7 +350,7 @@ public class CalendarButton extends Butt
}
/**
- * Gets the data binding key that is set on this calendar button.
+ * @return The data binding key that is set on this calendar button.
*/
public String getSelectedDateKey() {
return selectedDateKey;
@@ -349,6 +358,8 @@ public class CalendarButton extends Butt
/**
* Sets this calendar button's data binding key.
+ *
+ * @param selectedDateKey The new binding key for the calendar's selected
date.
*/
public void setSelectedDateKey(String selectedDateKey) {
String previousSelectedDateKey = this.selectedDateKey;
@@ -439,14 +450,14 @@ public class CalendarButton extends Butt
}
/**
- * Returns the calendar button listener list.
+ * @return The calendar button listener list.
*/
public ListenerList<CalendarButtonListener> getCalendarButtonListeners() {
return calendarButtonListeners;
}
/**
- * Returns the calendar button selection listener list.
+ * @return The calendar button selection listener list.
*/
public ListenerList<CalendarButtonSelectionListener>
getCalendarButtonSelectionListeners() {
return calendarButtonSelectionListeners;
Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/Clipboard.java
URL:
http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/Clipboard.java?rev=1712396&r1=1712395&r2=1712396&view=diff
==============================================================================
--- pivot/trunk/wtk/src/org/apache/pivot/wtk/Clipboard.java (original)
+++ pivot/trunk/wtk/src/org/apache/pivot/wtk/Clipboard.java Tue Nov 3 20:31:41
2015
@@ -43,6 +43,8 @@ public final class Clipboard {
/**
* Retrieves the contents of the clipboard.
+ *
+ * @return The current clipboard content manifest.
*/
public static Manifest getContent() {
Manifest contentLocal = Clipboard.content;
@@ -62,7 +64,7 @@ public final class Clipboard {
/**
* Places content on the clipboard.
*
- * @param content
+ * @param content The new content manifest to place on the clipboard.
*/
public static void setContent(LocalManifest content) {
setContent(content, null);
@@ -71,7 +73,10 @@ public final class Clipboard {
/**
* Places content on the clipboard.
*
- * @param content
+ * @param content The new content manifest for the clipboard.
+ * @param clipboardContentListener A listener for changes in the content
+ * (which can be {@code null}).
+ * @throws IllegalArgumentException if the content is {@code null}.
*/
public static void setContent(LocalManifest content,
ClipboardContentListener clipboardContentListener) {
Modified:
pivot/trunk/wtk/src/org/apache/pivot/wtk/DesktopApplicationContext.java
URL:
http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/DesktopApplicationContext.java?rev=1712396&r1=1712395&r2=1712396&view=diff
==============================================================================
--- pivot/trunk/wtk/src/org/apache/pivot/wtk/DesktopApplicationContext.java
(original)
+++ pivot/trunk/wtk/src/org/apache/pivot/wtk/DesktopApplicationContext.java Tue
Nov 3 20:31:41 2015
@@ -68,14 +68,14 @@ public final class DesktopApplicationCon
/**
* Called when the host window for secondary display has been opened.
*
- * @param display
+ * @param display The new secondary display.
*/
public void hostWindowOpened(Display display);
/**
* Called when the host window for secondary display has been closed.
*
- * @param display
+ * @param display The secondary display.
*/
public void hostWindowClosed(Display display);
}
@@ -407,6 +407,7 @@ public final class DesktopApplicationCon
*
* @param optional If <tt>true</tt>, shutdown is optional and may be
* cancelled. If <tt>false</tt>, shutdown cannot be cancelled.
+ * @return Whether shutdown was canceled by the application.
*/
public static boolean exit(boolean optional) {
boolean cancelShutdown = false;
@@ -737,6 +738,7 @@ public final class DesktopApplicationCon
/**
* Returns the full-screen mode flag.
+ * @return Whether or not the application is/should be displayed full
screen.
*/
public static boolean isFullScreen() {
return fullScreenHostFrame.isVisible();
@@ -745,7 +747,7 @@ public final class DesktopApplicationCon
/**
* Sets the full-screen mode flag.
*
- * @param fullScreen
+ * @param fullScreen Whether to display the application full screen.
*/
public static void setFullScreen(boolean fullScreen) {
setFullScreen(fullScreen, true);
@@ -816,7 +818,9 @@ public final class DesktopApplicationCon
/**
* Sizes the window's native host frame to match its preferred size.
*
- * @param window
+ * @param window The window to size.
+ * @throws IllegalArgumentException if the window parameter is {@code
null}.
+ * @throws IllegalStateException if the application is being displayed
full screen.
*/
public static void sizeHostToFit(Window window) {
if (window == null) {
@@ -837,12 +841,17 @@ public final class DesktopApplicationCon
/**
* Creates a new secondary display.
*
- * @param width
- * @param height
- * @param x
- * @param y
- * @param modal
- * @param owner
+ * @param width The new width for the secondary display.
+ * @param height The height for the secondary display.
+ * @param x The new X-position for the display.
+ * @param y The new Y-position for the display.
+ * @param modal Whether or not the new display is to be modal.
+ * @param resizable Whether or not to make the new display resizable by
the user.
+ * @param undecorated Whether the new display should be undecorated (that
is just a bare window) or normal.
+ * @param owner The owner for the new display.
+ * @param displayCloseListener The listener for the dialog being closed.
+ * @return The newly created display.
+ * @throws IllegalStateException if the full screen flag is set.
*/
public static Display createDisplay(int width, int height, int x, int y,
boolean modal,
boolean resizable, boolean undecorated, java.awt.Window owner,
@@ -858,8 +867,7 @@ public final class DesktopApplicationCon
hostDialog.setUndecorated(undecorated);
// Open the window in a callback; otherwise, if it is modal, it will
- // block the
- // calling thread
+ // block the calling thread
ApplicationContext.queueCallback(new Runnable() {
@Override
public void run() {
Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/Editor.java
URL:
http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/Editor.java?rev=1712396&r1=1712395&r2=1712396&view=diff
==============================================================================
--- pivot/trunk/wtk/src/org/apache/pivot/wtk/Editor.java (original)
+++ pivot/trunk/wtk/src/org/apache/pivot/wtk/Editor.java Tue Nov 3 20:31:41
2015
@@ -21,7 +21,7 @@ package org.apache.pivot.wtk;
*/
public interface Editor {
/**
- * Tells whether or not an edit is currently in progress.
+ * @return Flag saying whether or not an edit is currently in progress.
*/
public boolean isEditing();
Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/ExpanderListener.java
URL:
http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/ExpanderListener.java?rev=1712396&r1=1712395&r2=1712396&view=diff
==============================================================================
--- pivot/trunk/wtk/src/org/apache/pivot/wtk/ExpanderListener.java (original)
+++ pivot/trunk/wtk/src/org/apache/pivot/wtk/ExpanderListener.java Tue Nov 3
20:31:41 2015
@@ -60,45 +60,46 @@ public interface ExpanderListener {
/**
* Called when an expander's title has changed.
*
- * @param expander
- * @param previousTitle
+ * @param expander The expander that has changed.
+ * @param previousTitle The previous title for the expander.
*/
public void titleChanged(Expander expander, String previousTitle);
/**
* Called when an expander's collapsible flag has changed.
*
- * @param expander
+ * @param expander The expander that has changed.
*/
public void collapsibleChanged(Expander expander);
/**
* Called to preview an expanded change event.
*
- * @param expander
+ * @param expander The expander that is about to expand or collapse.
+ * @return The consensus vote as to whether to allow the change.
*/
public Vote previewExpandedChange(Expander expander);
/**
* Called when an expanded change event has been vetoed.
*
- * @param expander
- * @param reason
+ * @param expander The expander that is not going to change.
+ * @param reason The consensus vote that disallowed the change.
*/
public void expandedChangeVetoed(Expander expander, Vote reason);
/**
* Called when an expander's expanded state has changed.
*
- * @param expander
+ * @param expander The expander that has now expanded or collapsed.
*/
public void expandedChanged(Expander expander);
/**
* Called when an expander's content component has changed.
*
- * @param expander
- * @param previousContent
+ * @param expander The expander that has changed content.
+ * @param previousContent The previous content of the expander.
*/
public void contentChanged(Expander expander, Component previousContent);
}
Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/FileBrowser.java
URL:
http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/FileBrowser.java?rev=1712396&r1=1712395&r2=1712396&view=diff
==============================================================================
--- pivot/trunk/wtk/src/org/apache/pivot/wtk/FileBrowser.java (original)
+++ pivot/trunk/wtk/src/org/apache/pivot/wtk/FileBrowser.java Tue Nov 3
20:31:41 2015
@@ -131,7 +131,9 @@ public class FileBrowser extends Contain
/**
* Sets the root directory. Clears any existing file selection.
*
- * @param rootDirectory
+ * @param rootDirectory The new root directory to browse in.
+ * @throws IllegalArgumentException if the argument is {@code null}
+ * or is not a directory.
*/
public void setRootDirectory(File rootDirectory) {
if (rootDirectory == null || !rootDirectory.isDirectory()) {
@@ -154,9 +156,11 @@ public class FileBrowser extends Contain
/**
* Adds a file to the file selection.
*
- * @param file
+ * @param file The new file to add to the selection.
* @return <tt>true</tt> if the file was added; <tt>false</tt> if it was
* already selected.
+ * @throws IllegalArgumentException if the file argument is {@code null}
+ * or if the file is not in the current root directory.
*/
public boolean addSelectedFile(final File file) {
if (file == null) {
@@ -183,9 +187,10 @@ public class FileBrowser extends Contain
/**
* Removes a file from the file selection.
*
- * @param file
+ * @param file The previously selected file to be removed from the
selection.
* @return <tt>true</tt> if the file was removed; <tt>false</tt> if it was
* not already selected.
+ * @throws IllegalArgumentException if the file argument is {@code null}.
*/
public boolean removeSelectedFile(File file) {
if (file == null) {
@@ -216,7 +221,7 @@ public class FileBrowser extends Contain
/**
* Sets the selection to a single file.
*
- * @param file
+ * @param file The only file to select, or {@code null} to select nothing.
*/
public void setSelectedFile(File file) {
if (file == null) {
@@ -247,6 +252,10 @@ public class FileBrowser extends Contain
*
* @param selectedFiles The files to select.
* @return The files that were selected, with duplicates eliminated.
+ * @throws IllegalArgumentException if the selected files sequence is
{@code null}
+ * or if the sequence is longer than one file and multi-select is not
enabled, or
+ * if any entry is the sequence is {@code null} or whose parent is not the
+ * current root directory.
*/
public Sequence<File> setSelectedFiles(Sequence<File> selectedFiles) {
if (selectedFiles == null) {
@@ -299,7 +308,7 @@ public class FileBrowser extends Contain
}
/**
- * Returns the file browser's multi-select state.
+ * @return The file browser's multi-select state.
*/
public boolean isMultiSelect() {
return multiSelect;
Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/FileBrowserListener.java
URL:
http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/FileBrowserListener.java?rev=1712396&r1=1712395&r2=1712396&view=diff
==============================================================================
--- pivot/trunk/wtk/src/org/apache/pivot/wtk/FileBrowserListener.java (original)
+++ pivot/trunk/wtk/src/org/apache/pivot/wtk/FileBrowserListener.java Tue Nov
3 20:31:41 2015
@@ -65,47 +65,47 @@ public interface FileBrowserListener {
/**
* Called when a file browser's root directory has changed.
*
- * @param fileBrowser
- * @param previousRootDirectory
+ * @param fileBrowser The file browser that has changed.
+ * @param previousRootDirectory The previous root directory of the
browser.
*/
public void rootDirectoryChanged(FileBrowser fileBrowser, File
previousRootDirectory);
/**
* Called when a file has been added to a file browser's selection.
*
- * @param fileBrowser
- * @param file
+ * @param fileBrowser The file browser that has changed.
+ * @param file The newly selected file.
*/
public void selectedFileAdded(FileBrowser fileBrowser, File file);
/**
* Called when a file has been removed from a file browser's selection.
*
- * @param fileBrowser
- * @param file
+ * @param fileBrowser The file browser that has changed.
+ * @param file The file that was just unselected.
*/
public void selectedFileRemoved(FileBrowser fileBrowser, File file);
/**
* Called when a file browser's selection state has been reset.
*
- * @param fileBrowser
- * @param previousSelectedFiles
+ * @param fileBrowser The file browser that has changed.
+ * @param previousSelectedFiles The complete sequence of files that used
to be selected.
*/
public void selectedFilesChanged(FileBrowser fileBrowser, Sequence<File>
previousSelectedFiles);
/**
* Called when a file browser's multi-select flag has changed.
*
- * @param fileBrowser
+ * @param fileBrowser The file browser that has changed.
*/
public void multiSelectChanged(FileBrowser fileBrowser);
/**
* Called when a file browser's file filter has changed.
*
- * @param fileBrowser
- * @param previousDisabledFileFilter
+ * @param fileBrowser The file browser that has changed.
+ * @param previousDisabledFileFilter The previous disabled file filter.
*/
public void disabledFileFilterChanged(FileBrowser fileBrowser,
Filter<File> previousDisabledFileFilter);
Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/FileBrowserSheet.java
URL:
http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/FileBrowserSheet.java?rev=1712396&r1=1712395&r2=1712396&view=diff
==============================================================================
--- pivot/trunk/wtk/src/org/apache/pivot/wtk/FileBrowserSheet.java (original)
+++ pivot/trunk/wtk/src/org/apache/pivot/wtk/FileBrowserSheet.java Tue Nov 3
20:31:41 2015
@@ -155,7 +155,12 @@ public class FileBrowserSheet extends Sh
return rootDirectory;
}
- // set the root folder but without firing events
+ /**
+ * Set the root folder but without firing events.
+ *
+ * @param rootFolder The new root directory to browse.
+ * @throws IllegalArgumentException if the folder argument is {@code null}.
+ */
public void setRootFolder(String rootFolder) {
if (rootFolder == null) {
throw new IllegalArgumentException("Root folder is null.");
@@ -203,7 +208,8 @@ public class FileBrowserSheet extends Sh
/**
* When in single-select mode, returns the currently selected file.
*
- * @return The currently selected file.
+ * @return The currently selected file or {@code null} if nothing is
selected.
+ * @throws IllegalStateException if not in single-select mode.
*/
public File getSelectedFile() {
if (mode == Mode.OPEN_MULTIPLE) {
@@ -216,7 +222,7 @@ public class FileBrowserSheet extends Sh
/**
* Sets the selection to a single file.
*
- * @param file
+ * @param file The single file to be selected or {@code null} to select
nothing.
*/
public void setSelectedFile(File file) {
if (file == null) {
@@ -247,6 +253,10 @@ public class FileBrowserSheet extends Sh
*
* @param selectedFiles The files to select.
* @return The files that were selected, with duplicates eliminated.
+ * @throws IllegalArgumentException if the selected files sequence is
{@code null}
+ * or if the sequence is longer than one file and multi-select is not
enabled, or
+ * if any entry is the sequence is {@code null} or whose parent is not the
+ * current root directory.
*/
public Sequence<File> setSelectedFiles(Sequence<File> selectedFiles) {
if (selectedFiles == null) {
Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/FileBrowserSheetListener.java
URL:
http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/FileBrowserSheetListener.java?rev=1712396&r1=1712395&r2=1712396&view=diff
==============================================================================
--- pivot/trunk/wtk/src/org/apache/pivot/wtk/FileBrowserSheetListener.java
(original)
+++ pivot/trunk/wtk/src/org/apache/pivot/wtk/FileBrowserSheetListener.java Tue
Nov 3 20:31:41 2015
@@ -57,24 +57,24 @@ public interface FileBrowserSheetListene
/**
* Called when a file browser sheet's mode has changed.
*
- * @param fileBrowserSheet
- * @param previousMode
+ * @param fileBrowserSheet The browser sheet that has changed.
+ * @param previousMode The previous mode that was in effect.
*/
public void modeChanged(FileBrowserSheet fileBrowserSheet,
FileBrowserSheet.Mode previousMode);
/**
* Called when a file browser sheet's root directory has changed.
*
- * @param fileBrowserSheet
- * @param previousRootDirectory
+ * @param fileBrowserSheet The browser sheet that has changed.
+ * @param previousRootDirectory The previous root directory that was being
browsed.
*/
public void rootDirectoryChanged(FileBrowserSheet fileBrowserSheet, File
previousRootDirectory);
/**
* Called when a file browser sheet's selection state has been reset.
*
- * @param fileBrowserSheet
- * @param previousSelectedFiles
+ * @param fileBrowserSheet The browser sheet that has changed.
+ * @param previousSelectedFiles The complete sequence of files that used
to be selected.
*/
public void selectedFilesChanged(FileBrowserSheet fileBrowserSheet,
Sequence<File> previousSelectedFiles);
@@ -82,8 +82,8 @@ public interface FileBrowserSheetListene
/**
* Called when a file browser sheet's disabled file filter has changed.
*
- * @param fileBrowserSheet
- * @param previousDisabledFileFilter
+ * @param fileBrowserSheet The browser sheet that has changed.
+ * @param previousDisabledFileFilter The previous disabled file filter.
*/
public void disabledFileFilterChanged(FileBrowserSheet fileBrowserSheet,
Filter<File> previousDisabledFileFilter);
Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/FillPaneListener.java
URL:
http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/FillPaneListener.java?rev=1712396&r1=1712395&r2=1712396&view=diff
==============================================================================
--- pivot/trunk/wtk/src/org/apache/pivot/wtk/FillPaneListener.java (original)
+++ pivot/trunk/wtk/src/org/apache/pivot/wtk/FillPaneListener.java Tue Nov 3
20:31:41 2015
@@ -23,7 +23,7 @@ public interface FillPaneListener {
/**
* Called when a fill pane's orientation has changed.
*
- * @param fillPane
+ * @param fillPane The fill pane that has changed.
*/
public void orientationChanged(FillPane fillPane);
}
Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/Form.java
URL:
http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/Form.java?rev=1712396&r1=1712395&r2=1712396&view=diff
==============================================================================
--- pivot/trunk/wtk/src/org/apache/pivot/wtk/Form.java (original)
+++ pivot/trunk/wtk/src/org/apache/pivot/wtk/Form.java Tue Nov 3 20:31:41 2015
@@ -294,7 +294,8 @@ public class Form extends Container {
/**
* Sets the flag's message type.
*
- * @param messageType
+ * @param messageType The new message type for this flag.
+ * @throws IllegalArgumentException if the message type is {@code
null}.
*/
public void setMessageType(MessageType messageType) {
if (messageType == null) {
@@ -450,6 +451,7 @@ public class Form extends Container {
*
* @param messageType The message type to count, or <tt>null</tt> to return
* the count of all flagged fields regardless of message type.
+ * @return The number of flagged fields.
*/
public int getFlaggedFieldCount(MessageType messageType) {
int count = 0;
@@ -530,6 +532,8 @@ public class Form extends Container {
* Finds the {@link Form.Section} that the given component belongs to. Only
* finds the section if the component is a direct child of the section.
*
+ * @param component The component in question.
+ * @return The section this component belongs to.
* @see #getEnclosingSection getEnclosingSection(Component)
*/
public static Section getSection(Component component) {
@@ -541,6 +545,7 @@ public class Form extends Container {
* search up the parent hierarchy in case the component is nested inside
* other containers inside the form.
*
+ * @param component The component in question.
* @return The form section this component (or one of its parents) belongs
* to or <code>null</code> if the component does not belong to a form.
* @see #getSection getSection(Component)
Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/FormAttributeListener.java
URL:
http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/FormAttributeListener.java?rev=1712396&r1=1712395&r2=1712396&view=diff
==============================================================================
--- pivot/trunk/wtk/src/org/apache/pivot/wtk/FormAttributeListener.java
(original)
+++ pivot/trunk/wtk/src/org/apache/pivot/wtk/FormAttributeListener.java Tue Nov
3 20:31:41 2015
@@ -41,28 +41,28 @@ public interface FormAttributeListener {
}
/**
- * Called when a fields's label attribute has changed.
+ * Called when a field's label attribute has changed.
*
- * @param form
- * @param field
- * @param previousLabel
+ * @param form The enclosing form.
+ * @param field The field whose form label has changed.
+ * @param previousLabel The previous form label for this field.
*/
public void labelChanged(Form form, Component field, String previousLabel);
/**
* Called when a fields's required attribute has changed.
*
- * @param form
- * @param field
+ * @param form The enclosing form.
+ * @param field The field that is or is not now required.
*/
public void requiredChanged(Form form, Component field);
/**
* Called when a field's flag attribute has changed.
*
- * @param form
- * @param field
- * @param previousFlag
+ * @param form The enclosing form.
+ * @param field The field whose flag attribute has changed.
+ * @param previousFlag The previous flag value for this field.
*/
public void flagChanged(Form form, Component field, Form.Flag
previousFlag);
}
Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/FormListener.java
URL:
http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/FormListener.java?rev=1712396&r1=1712395&r2=1712396&view=diff
==============================================================================
--- pivot/trunk/wtk/src/org/apache/pivot/wtk/FormListener.java (original)
+++ pivot/trunk/wtk/src/org/apache/pivot/wtk/FormListener.java Tue Nov 3
20:31:41 2015
@@ -55,41 +55,41 @@ public interface FormListener {
/**
* Called when a form section has been inserted.
*
- * @param form
- * @param index
+ * @param form The form that has changed.
+ * @param index The index where the new section has been inserted.
*/
public void sectionInserted(Form form, int index);
/**
* Called when form sections have been removed.
*
- * @param form
- * @param index
- * @param removed
+ * @param form The form that has changed.
+ * @param index The starting index where sections were removed.
+ * @param removed The complete sequence of the removed sections.
*/
public void sectionsRemoved(Form form, int index, Sequence<Form.Section>
removed);
/**
* Called when a form section's heading has changed.
*
- * @param section
+ * @param section The form section whose heading changed.
*/
public void sectionHeadingChanged(Form.Section section);
/**
* Called when a form field has been inserted.
*
- * @param section
- * @param index
+ * @param section The enclosing form section that has changed.
+ * @param index The index where a new field has been inserted.
*/
public void fieldInserted(Form.Section section, int index);
/**
- * Called when forms fields items have been removed.
+ * Called when form fields have been removed.
*
- * @param section
- * @param index
- * @param fields
+ * @param section The enclosing form section.
+ * @param index The starting index where fields were removed.
+ * @param fields The complete sequence of fields that were removed.
*/
public void fieldsRemoved(Form.Section section, int index,
Sequence<Component> fields);
}
Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/FrameListener.java
URL:
http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/FrameListener.java?rev=1712396&r1=1712395&r2=1712396&view=diff
==============================================================================
--- pivot/trunk/wtk/src/org/apache/pivot/wtk/FrameListener.java (original)
+++ pivot/trunk/wtk/src/org/apache/pivot/wtk/FrameListener.java Tue Nov 3
20:31:41 2015
@@ -23,8 +23,8 @@ public interface FrameListener {
/**
* Called when a frame's menu bar has changed.
*
- * @param frame
- * @param previousMenuBar
+ * @param frame The frame that has changed.
+ * @param previousMenuBar The previous menu bar for this frame.
*/
public void menuBarChanged(Frame frame, MenuBar previousMenuBar);
}
Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/GraphicsUtilities.java
URL:
http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/GraphicsUtilities.java?rev=1712396&r1=1712395&r2=1712396&view=diff
==============================================================================
--- pivot/trunk/wtk/src/org/apache/pivot/wtk/GraphicsUtilities.java (original)
+++ pivot/trunk/wtk/src/org/apache/pivot/wtk/GraphicsUtilities.java Tue Nov 3
20:31:41 2015
@@ -228,6 +228,9 @@ public final class GraphicsUtilities {
* {@linkplain GraphicsUtilities#decodeColor color values recognized by
* Pivot} or (b) A {@linkplain GraphicsUtilities#decodePaint(Dictionary)
* JSON dictionary describing a Paint value}.
+ * @return The decoded paint value.
+ * @throws IllegalArgumentException if the given value is {@code null} or
+ * there is a problem decoding the value.
*/
public static Paint decodePaint(String value) {
if (value == null) {
@@ -267,6 +270,8 @@ public final class GraphicsUtilities {
* {@value #CENTER_Y_KEY} (coordinates), {@value #RADIUS_KEY} (a number),
* {@value #STOPS_KEY} (a list of dictionaries with keys
* {@value #OFFSET_KEY} and {@value #COLOR_KEY})</li> </ul>
+ * @return The fully decoded paint value.
+ * @throws IllegalArgumentException if there is no paint type key found.
*/
public static Paint decodePaint(Dictionary<String, ?> dictionary) {
String paintType = JSON.get(dictionary, PAINT_TYPE_KEY);
Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/GridPaneListener.java
URL:
http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/GridPaneListener.java?rev=1712396&r1=1712395&r2=1712396&view=diff
==============================================================================
--- pivot/trunk/wtk/src/org/apache/pivot/wtk/GridPaneListener.java (original)
+++ pivot/trunk/wtk/src/org/apache/pivot/wtk/GridPaneListener.java Tue Nov 3
20:31:41 2015
@@ -60,51 +60,51 @@ public interface GridPaneListener {
/**
* Called when a grid pane's column count has changed.
*
- * @param gridPane
- * @param previousColumnCount
+ * @param gridPane The grid pane that has changed.
+ * @param previousColumnCount The previous column count for the grid.
*/
public void columnCountChanged(GridPane gridPane, int previousColumnCount);
/**
* Called when a row has been inserted into a grid pane.
*
- * @param gridPane
- * @param index
+ * @param gridPane The grid pane that has changed.
+ * @param index The index of the row that was just inserted.
*/
public void rowInserted(GridPane gridPane, int index);
/**
* Called when rows have been removed from a grid pane.
*
- * @param gridPane
- * @param index
- * @param rows
+ * @param gridPane The grid pane that has changed.
+ * @param index The starting index of the row(s) that were removed.
+ * @param rows The complete sequence of removed rows.
*/
public void rowsRemoved(GridPane gridPane, int index,
Sequence<GridPane.Row> rows);
/**
* Called when a cell has been inserted into a grid pane.
*
- * @param row
- * @param column
+ * @param row The parent row of the cell that was inserted.
+ * @param column The column index of the inserted cell.
*/
public void cellInserted(GridPane.Row row, int column);
/**
- * Called when cell's have been removed from a grid pane.
+ * Called when cells have been removed from a grid pane.
*
- * @param row
- * @param column
- * @param removed
+ * @param row The parent row of the removed cell(s).
+ * @param column The starting column index of the removed cells.
+ * @param removed The complete sequence of removed cells.
*/
public void cellsRemoved(GridPane.Row row, int column, Sequence<Component>
removed);
/**
* Called when a cell has been updated in a grid pane.
*
- * @param row
- * @param column
- * @param previousComponent
+ * @param row The parent row object of the updated cell.
+ * @param column The column index of the updated cell.
+ * @param previousComponent The previous contents of this cell.
*/
public void cellUpdated(GridPane.Row row, int column, Component
previousComponent);
}
Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/Window.java
URL:
http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/Window.java?rev=1712396&r1=1712395&r2=1712396&view=diff
==============================================================================
--- pivot/trunk/wtk/src/org/apache/pivot/wtk/Window.java (original)
+++ pivot/trunk/wtk/src/org/apache/pivot/wtk/Window.java Tue Nov 3 20:31:41
2015
@@ -545,7 +545,7 @@ public class Window extends Container {
* Tests whether this window is an owning ancestor of a given window. A
* window is not considered an owner of itself.
*
- * @param window
+ * @param window The window which could be an owned descendant of this
window.
* @return <tt>true</tt> if this window is an owning ancestor of the given
* window; <tt>false</tt>, otherwise.
*/
@@ -585,7 +585,7 @@ public class Window extends Container {
/**
* Opens the window.
*
- * @param display
+ * @param display The display on which to open this window.
*/
public final void open(Display display) {
open(display, null);
@@ -596,6 +596,7 @@ public class Window extends Container {
*
* @param ownerArgument The window's owner. The window is opened on the
* owner's display.
+ * @throws IllegalArgumentException if the owner argument is {@code null}.
*/
public final void open(Window ownerArgument) {
if (ownerArgument == null) {
@@ -769,7 +770,7 @@ public class Window extends Container {
}
/**
- * Returns the icons for this window.
+ * @return The icons for this window.
*/
public IconImageSequence getIcons() {
return iconImageSequence;
@@ -840,7 +841,7 @@ public class Window extends Container {
}
/**
- * Returns the bounds of the window's client area.
+ * @return The bounds of the window's client area.
*/
public Bounds getClientArea() {
Window.Skin windowSkin = (Window.Skin) getSkin();
@@ -873,8 +874,8 @@ public class Window extends Container {
/**
* Called to notify a window that its active state has changed.
*
- * @param active
- * @param obverseWindow
+ * @param active The new value of the "active" state for this
window.
+ * @param obverseWindow The "other" window (that is now in the obverse
state).
*/
protected void setActive(boolean active, Window obverseWindow) {
windowListeners.activeChanged(this, obverseWindow);
@@ -928,7 +929,7 @@ public class Window extends Container {
}
/**
- * Returns the window descendant to which focus will be restored when this
+ * @return The window descendant to which focus will be restored when this
* window is moved to the front.
*/
public Component getFocusDescendant() {
@@ -961,7 +962,7 @@ public class Window extends Container {
}
/**
- * Returns the action mappings for this window.
+ * @return The action mappings for this window.
*/
public ActionMappingSequence getActionMappings() {
return actionMappingSequence;
@@ -969,6 +970,8 @@ public class Window extends Container {
/**
* Determines if this is the top-most window.
+ *
+ * @return {@code true} if this window is at the top of the Z-order of its
display.
*/
public boolean isTopMost() {
Display display = getDisplay();
@@ -977,6 +980,8 @@ public class Window extends Container {
/**
* Determines if this is the bottom-most window.
+ *
+ * @return {@code true} if this window is at the bottom of the Z-order of
its display.
*/
public boolean isBottomMost() {
Display display = getDisplay();
