Author: mes
Date: 2010-11-14 16:33:27 -0800 (Sun, 14 Nov 2010)
New Revision: 22840
Modified:
core3/swing-application-api/trunk/src/main/java/org/cytoscape/application/swing/CyHelpBroker.java
core3/swing-application-api/trunk/src/main/java/org/cytoscape/application/swing/CytoPanelName.java
core3/swing-application-api/trunk/src/main/java/org/cytoscape/application/swing/CytoPanelState.java
core3/swing-application-api/trunk/src/main/java/org/cytoscape/application/swing/CytoscapeVersion.java
core3/swing-application-api/trunk/src/main/java/org/cytoscape/application/swing/ViewUpdater.java
core3/swing-application-api/trunk/src/main/java/org/cytoscape/application/swing/events/CytoscapeShutdownEvent.java
core3/swing-application-api/trunk/src/main/java/org/cytoscape/application/swing/events/CytoscapeShutdownListener.java
core3/swing-application-api/trunk/src/main/java/org/cytoscape/application/swing/events/PreferencesUpdatedEvent.java
core3/swing-application-api/trunk/src/main/java/org/cytoscape/application/swing/events/PreferencesUpdatedListener.java
core3/swing-application-api/trunk/src/main/java/org/cytoscape/application/swing/util/OpenBrowser.java
Log:
updated javadoc
Modified:
core3/swing-application-api/trunk/src/main/java/org/cytoscape/application/swing/CyHelpBroker.java
===================================================================
---
core3/swing-application-api/trunk/src/main/java/org/cytoscape/application/swing/CyHelpBroker.java
2010-11-14 23:48:03 UTC (rev 22839)
+++
core3/swing-application-api/trunk/src/main/java/org/cytoscape/application/swing/CyHelpBroker.java
2010-11-15 00:33:27 UTC (rev 22840)
@@ -48,14 +48,12 @@
/**
* Returns the HelpBroker.
- *
* @return the HelpBroker.
*/
public HelpBroker getHelpBroker();
/**
* Returns the HelpSet.
- *
* @return the HelpSet.
*/
public HelpSet getHelpSet();
Modified:
core3/swing-application-api/trunk/src/main/java/org/cytoscape/application/swing/CytoPanelName.java
===================================================================
---
core3/swing-application-api/trunk/src/main/java/org/cytoscape/application/swing/CytoPanelName.java
2010-11-14 23:48:03 UTC (rev 22839)
+++
core3/swing-application-api/trunk/src/main/java/org/cytoscape/application/swing/CytoPanelName.java
2010-11-15 00:33:27 UTC (rev 22840)
@@ -31,12 +31,28 @@
/**
- * An enum that maps names to compass directions.
+ * An enum that describes CytoPanels uses compass directions
+ * to describe their location within the application.
*/
public enum CytoPanelName {
+ /**
+ * The south or bottom panel.
+ */
SOUTH("Data Panel"),
+
+ /**
+ * The east or righthand panel.
+ */
EAST("Results Panel"),
+
+ /**
+ * The west or lefthand panel.
+ */
WEST("Control Panel"),
+
+ /**
+ * The southwest or bottom left panel.
+ */
SOUTH_WEST("Tool Panel"),
;
@@ -46,6 +62,10 @@
this.title = title;
}
+ /**
+ * Returns the human readable title used for labeling this CytoPanel.
+ * @return The human readable title used for labeling this CytoPanel.
+ */
public String getTitle() {
return title;
}
Modified:
core3/swing-application-api/trunk/src/main/java/org/cytoscape/application/swing/CytoPanelState.java
===================================================================
---
core3/swing-application-api/trunk/src/main/java/org/cytoscape/application/swing/CytoPanelState.java
2010-11-14 23:48:03 UTC (rev 22839)
+++
core3/swing-application-api/trunk/src/main/java/org/cytoscape/application/swing/CytoPanelState.java
2010-11-15 00:33:27 UTC (rev 22840)
@@ -39,26 +39,24 @@
/**
- * CytoPanelState enum. The following States are supported:
- * <UL>
- * <LI>CytoPanelState.HIDE: Hide the CytoPanel.
- * <LI>CytoPanelState.FLOAT: Float the CytoPanel.
- * <LI>CytoPanelState.DOCK: Dock the CytoPanel.
- * </UL>
+ * The different display states available for a CytoPanel.
*/
public enum CytoPanelState {
- HIDE("hide"),
- FLOAT("float"),
- DOCK("dock"),
- ;
+ /**
+ * The CytoPanel will be hidden and only appear as a menu item.
+ */
+ HIDE,
- private final String name;
+ /**
+ * The CytoPanel will be open and appear as a separate frame
+ * independent of the application.
+ */
+ FLOAT,
- private CytoPanelState(String name) {
- this.name = name;
- }
-
- public String getName() {
- return name;
- }
+ /**
+ * The CytoPanel will be open and appear as a nested frame
+ * within the application.
+ */
+ DOCK,
+ ;
}
Modified:
core3/swing-application-api/trunk/src/main/java/org/cytoscape/application/swing/CytoscapeVersion.java
===================================================================
---
core3/swing-application-api/trunk/src/main/java/org/cytoscape/application/swing/CytoscapeVersion.java
2010-11-14 23:48:03 UTC (rev 22839)
+++
core3/swing-application-api/trunk/src/main/java/org/cytoscape/application/swing/CytoscapeVersion.java
2010-11-15 00:33:27 UTC (rev 22840)
@@ -38,7 +38,9 @@
/**
* An interface providing access to version information about this
- * version of the Cytoscape application.
+ * version of the Cytoscape application. Cytoscape strives to follow
+ * the <a href="http://semver.org";>Semantic Versioning</a> standard
+ * to ensure comprehensible backwards compatibility versioning.
*/
public interface CytoscapeVersion {
@@ -63,6 +65,7 @@
* changes only for comprehensive software changes and while APIs
* may be similar between versions, they are not guaranteed to be
* compatible.
+ * @return The integer describing the major version of this application.
*/
public int getMajorVersion();
@@ -74,6 +77,7 @@
* Minor version APIs are guaranteed to be backwards compatibile for
* all previous versions within the major version (i.e. version 3.2
* will be completely compatible with all 3.1.x, and 3.0.x code).
+ * @return The integer describing the minor version of this application.
*/
public int getMinorVersion();
@@ -81,17 +85,22 @@
/**
* The third of the three numbers defining the version of the
* software, meaning "5" if the version is "3.2.5". This number
- * changes as bug fixes are made and no new features or APIs should be
- * added. Bug fix version APIs are guaranteed to be backwards
+ * changes as bug fixes are made but no new features or APIs are
+ * added. Bug fix versions contain NO NEW FEATRURES!
+ * Bug fix version APIs are guaranteed to be backwards
* compatibile for all previous versions within the major version
* (i.e. version 3.2.5 will be completely compatible with all 3.x
* versions of the code).
+ * @return The integer describing the bug fix version of this
application.
*/
public int getBugFixVersion();
/**
* Any text following the last digit of the bug fix version. If
* the version is 3.0.2-beta1 then the qualifier will be "-beta1".
+ * Final (stable) versions of the application should not include any
+ * qualifying information. All qualifying text indicates a pre-release,
+ * an unstable release, or unfinished release.
* @return Any text following the last digit of the bug fix version.
*/
public String getQualifier();
Modified:
core3/swing-application-api/trunk/src/main/java/org/cytoscape/application/swing/ViewUpdater.java
===================================================================
---
core3/swing-application-api/trunk/src/main/java/org/cytoscape/application/swing/ViewUpdater.java
2010-11-14 23:48:03 UTC (rev 22839)
+++
core3/swing-application-api/trunk/src/main/java/org/cytoscape/application/swing/ViewUpdater.java
2010-11-15 00:33:27 UTC (rev 22840)
@@ -40,6 +40,11 @@
import org.cytoscape.model.CyRow;
import org.cytoscape.model.events.RowSetMicroListener;
+/**
+ * A utility class that provides an implementation of
+ * {...@link RowSetMicroListener} for a particular {...@link View}
+ * and {...@link VisualProperty}.
+ */
public class ViewUpdater<T,S> implements RowSetMicroListener {
protected final CyRow row;
@@ -47,6 +52,13 @@
protected final VisualProperty<S> vp;
protected final String columnName;
+ /**
+ * Constructor.
+ * @param view The view that the visual property should be set whne the
row is changed.
+ * @param vp The visual property that should be set on the view when
the row is changed.
+ * @param row The row that is being listened to.
+ * @param columnName The name of the column within the row that is
being listened to.
+ */
public ViewUpdater(View<T> view, VisualProperty<S> vp, CyRow row,
String columnName) {
this.view = view;
this.vp = vp;
@@ -54,10 +66,20 @@
this.columnName = columnName;
}
+ /**
+ * @inheritdoc
+ */
public Object getEventSource() {
return row;
}
+ /**
+ * Called whenever the {...@link CyRow} is changed. Will attempt to set
+ * the visual property on the view with the new value that has been
+ * set in the row.
+ * @param columnName The name of the column with the row that was
changed.
+ * @param value The new value that the row has been set to.
+ */
@SuppressWarnings("unchecked")
public void handleRowSet(final String columnName, final Object value) {
if ( columnName == null || !columnName.equals(this.columnName) )
Modified:
core3/swing-application-api/trunk/src/main/java/org/cytoscape/application/swing/events/CytoscapeShutdownEvent.java
===================================================================
---
core3/swing-application-api/trunk/src/main/java/org/cytoscape/application/swing/events/CytoscapeShutdownEvent.java
2010-11-14 23:48:03 UTC (rev 22839)
+++
core3/swing-application-api/trunk/src/main/java/org/cytoscape/application/swing/events/CytoscapeShutdownEvent.java
2010-11-15 00:33:27 UTC (rev 22840)
@@ -4,12 +4,19 @@
import org.cytoscape.event.AbstractCyEvent;
/**
- * An event fired immediately before Cytoscape will be shutdown.
+ * An event fired immediately before Cytoscape will be shutdown. This
+ * event provides methods for listeners processing this event to
+ * abort the shutdown. This event should only be fired synchronously
+ * to allow all listeners time to clean up.
*/
public final class CytoscapeShutdownEvent extends AbstractCyEvent<Object> {
private String reason;
+ /**
+ * Constructor.
+ * @param source The object firing this event.
+ */
public CytoscapeShutdownEvent(final Object source) {
super(source, CytoscapeShutdownListener.class);
reason = null;
@@ -28,10 +35,20 @@
reason = why;
}
+ /**
+ * Returns the reason that the application should not be shut down.
+ * @return The reason that the application should not be shut down.
+ */
public String whyNot() {
return reason;
}
+ /**
+ * Returns true if no reason is provided to abort the shutdown and false
+ * if anyone processing this event wants to prevent shutdown.
+ * @return true if no reason is provided to abort the shutdown and false
+ * if anyone processing this event wants to prevent shutdown.
+ */
public boolean actuallyShutdown() {
return (reason == null || reason.length() <= 0);
}
Modified:
core3/swing-application-api/trunk/src/main/java/org/cytoscape/application/swing/events/CytoscapeShutdownListener.java
===================================================================
---
core3/swing-application-api/trunk/src/main/java/org/cytoscape/application/swing/events/CytoscapeShutdownListener.java
2010-11-14 23:48:03 UTC (rev 22839)
+++
core3/swing-application-api/trunk/src/main/java/org/cytoscape/application/swing/events/CytoscapeShutdownListener.java
2010-11-15 00:33:27 UTC (rev 22840)
@@ -4,8 +4,13 @@
import org.cytoscape.event.CyListener;
/**
- *
+ * The listener for the CytoscapeShutdownEvent.
*/
public interface CytoscapeShutdownListener extends CyListener {
+
+ /**
+ * Process the specified event.
+ * @param e The event being processed.
+ */
public void handleEvent(CytoscapeShutdownEvent e);
}
Modified:
core3/swing-application-api/trunk/src/main/java/org/cytoscape/application/swing/events/PreferencesUpdatedEvent.java
===================================================================
---
core3/swing-application-api/trunk/src/main/java/org/cytoscape/application/swing/events/PreferencesUpdatedEvent.java
2010-11-14 23:48:03 UTC (rev 22839)
+++
core3/swing-application-api/trunk/src/main/java/org/cytoscape/application/swing/events/PreferencesUpdatedEvent.java
2010-11-15 00:33:27 UTC (rev 22840)
@@ -3,23 +3,38 @@
import org.cytoscape.event.AbstractCyEvent;
import java.util.Properties;
+
/**
- *
+ * An event indicating that system preferences have been updated.
*/
public final class PreferencesUpdatedEvent extends AbstractCyEvent<Object> {
private final Properties oldProps;
private final Properties newProps;
+ /**
+ * Constructor.
+ * @param source The object firing this event.
+ * @param oldProps The old properties.
+ * @param newProps The new properties.
+ */
public PreferencesUpdatedEvent(final Object source, final Properties
oldProps, final Properties newProps) {
super(source, PreferencesUpdatedListener.class);
this.oldProps = oldProps;
this.newProps = newProps;
}
+ /**
+ * The old properties before they were modified.
+ * @return the old properties before they were modified.
+ */
public Properties getOldProperties() {
return oldProps;
}
+ /**
+ * The new properties after being modified.
+ * @return the new properties after being modified.
+ */
public Properties getNewProperties() {
return newProps;
}
Modified:
core3/swing-application-api/trunk/src/main/java/org/cytoscape/application/swing/events/PreferencesUpdatedListener.java
===================================================================
---
core3/swing-application-api/trunk/src/main/java/org/cytoscape/application/swing/events/PreferencesUpdatedListener.java
2010-11-14 23:48:03 UTC (rev 22839)
+++
core3/swing-application-api/trunk/src/main/java/org/cytoscape/application/swing/events/PreferencesUpdatedListener.java
2010-11-15 00:33:27 UTC (rev 22840)
@@ -4,8 +4,13 @@
import org.cytoscape.event.CyListener;
/**
- *
+ * A listener for the PreferencesUpdatedEvent.
*/
public interface PreferencesUpdatedListener extends CyListener {
+
+ /**
+ * Proces the specified event.
+ * @param e The even to be processed.
+ */
public void handleEvent(PreferencesUpdatedEvent e);
}
Modified:
core3/swing-application-api/trunk/src/main/java/org/cytoscape/application/swing/util/OpenBrowser.java
===================================================================
---
core3/swing-application-api/trunk/src/main/java/org/cytoscape/application/swing/util/OpenBrowser.java
2010-11-14 23:48:03 UTC (rev 22839)
+++
core3/swing-application-api/trunk/src/main/java/org/cytoscape/application/swing/util/OpenBrowser.java
2010-11-15 00:33:27 UTC (rev 22840)
@@ -40,18 +40,22 @@
/**
- *
+ * A utility provided as an OSGi service for opening
+ * a web browser. The Cytoscape property "defaultWebBrowser"
+ * may be set with an alternative command for opening
+ * a different web browser than default.
*/
public interface OpenBrowser {
- String UNIX_PATH = "htmlview";
- String MAC_PATH = "open";
- String WIN_PATH = "rundll32 url.dll,FileProtocolHandler";
+ /**
+ * The name of a property for a Properties object used to define an
alternative
+ * web browser command.
+ */
+ String DEF_WEB_BROWSER_PROP_NAME = "defaultWebBrowser";
/**
- * DOCUMENT ME!
- *
- * @param url DOCUMENT ME!
+ * Opens a web browser pointing to the specified URL.
+ * @param url A string URL that should be opened in the web browser.
*/
void openURL(String url);
}
--
You received this message because you are subscribed to the Google Groups
"cytoscape-cvs" group.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/cytoscape-cvs?hl=en.
