Author: ruschein
Date: 2010-11-04 10:27:31 -0700 (Thu, 04 Nov 2010)
New Revision: 22717
Modified:
core3/work-swing-api/trunk/src/main/java/org/cytoscape/work/swing/AbstractGUITunableHandler.java
core3/work-swing-api/trunk/src/main/java/org/cytoscape/work/swing/AbstractGUITunableInterceptor.java
core3/work-swing-api/trunk/src/main/java/org/cytoscape/work/swing/GUITaskManager.java
core3/work-swing-api/trunk/src/main/java/org/cytoscape/work/swing/GUITunableHandler.java
core3/work-swing-api/trunk/src/main/java/org/cytoscape/work/swing/GUITunableInterceptor.java
Log:
Updated JavaDoc.
Modified:
core3/work-swing-api/trunk/src/main/java/org/cytoscape/work/swing/AbstractGUITunableHandler.java
===================================================================
---
core3/work-swing-api/trunk/src/main/java/org/cytoscape/work/swing/AbstractGUITunableHandler.java
2010-11-04 17:08:36 UTC (rev 22716)
+++
core3/work-swing-api/trunk/src/main/java/org/cytoscape/work/swing/AbstractGUITunableHandler.java
2010-11-04 17:27:31 UTC (rev 22717)
@@ -20,22 +20,17 @@
import org.cytoscape.work.Tunable;
-/**
- * Abstract handler for the creation of the GUI.
- * <br>
- * It provides the functions that are common to all types of Handlers
- */
+/** Base class for the various Swing implementations of
<code>TunableHandler</code>. */
public abstract class AbstractGUITunableHandler
extends AbstractTunableHandler implements GUITunableHandler,
ActionListener, ChangeListener, ListSelectionListener
{
/**
- * If true the associated GUI element should be layed out next to
others in the same group.
+ * If true, the associated GUI element should be layed out next to
others in the same group,
+ * if false, it should be vertically stacked relative to the others.
*/
protected boolean horizontal;
- /**
- * <code>JPanel</code> that will contain the GUI object that represents
in the best way the <code>Tunable</code> to the user
- */
+ /** <code>JPanel</code> that will contain the GUI representation of the
<code>TunableHandler</code>. */
protected JPanel panel;
/**
@@ -47,13 +42,14 @@
private String dependencyName;
/**
- * <pre>
- * Represents the state of the dependency :
- * could be : "true, false, an item of a <code>ListSelection</code>, a
value ..."
- * </pre>
+ * <pre>
+ * Represents the value of the dependency.
+ * Could be : "true, false, an item of a <code>ListSelection</code>, a
value ..."
+ * </pre>
+ * Either mustMatch is non-empty and mustNotMatch, or vice versa, or
both are null if there is no dependency.
*/
- private String dependencyState;
- private String dependencyUnState;
+ private String mustMatch;
+ private String mustNotMatch;
/**
* The list of dependencies between the <code>GUITunableHandlers</code>
@@ -94,15 +90,15 @@
System.err.println("*** In AbstractGUITunableHandler:
\"alignments\" was specified but is neither \"horizontal\" nor \"vertical\"!");
String s = dependsOn();
- if (!s.equals("")) {
+ if (!s.isEmpty()) {
if (!s.contains("!=")) {
dependencyName = s.substring(0, s.indexOf("="));
- dependencyState = s.substring(s.indexOf("=") +
1);
- dependencyUnState = "";
+ mustMatch = s.substring(s.indexOf("=") + 1);
+ mustNotMatch = "";
} else {
dependencyName = s.substring(0, s.indexOf("!"));
- dependencyUnState = s.substring(s.indexOf("=")
+ 1);
- dependencyState = "";
+ mustNotMatch = s.substring(s.indexOf("=") + 1);
+ mustMatch = "";
}
}
@@ -120,9 +116,9 @@
}
/**
- * Notify a change of state of a <code>GUITunableHandler</code>
+ * Notification of a state change of a <code>GUITunableHandler</code>
*
- * @param e a modification that happened to this <code>handler</code>
+ * @param e the details of the state change
*/
public void stateChanged(ChangeEvent e) {
notifyDependents();
@@ -131,7 +127,7 @@
/**
* Notify a change during the selection of an item in the
<code>ListSelection</code> objects
*
- * @param le change in the selection of an item in a list
+ * @param le the specifics of the list selection change
*/
public void valueChanged(ListSelectionEvent le) {
boolean ok = le.getValueIsAdjusting();
@@ -139,75 +135,54 @@
notifyDependents();
}
-
/**
- * Notify dependencies that this object is changing
+ * Notifies all dependents that this object has changed.
*/
public void notifyDependents() {
String state = getState();
String name = getName();
- for ( GUITunableHandler gh : dependencies )
- gh.checkDependency( name, state );
+ for (GUITunableHandler gh : dependencies)
+ gh.checkDependency(name, state);
}
/**
- * Add a dependency on this <code>GUITunableHandler</code> to another
<code>Tunable</code>
- * While the dependency rule to this other
<code>GUITunableHandler</code> doesn't match, this one won't be available
- *
- * @param gh <code>Handler</code> on which this one depends on.
+ * Adds the argument as a new dependency to this
<code>GUITunableHandler</code>.
+ * @param gh <code>Handler</code> on which this one will depend on
*/
public void addDependent(GUITunableHandler gh) {
- //System.out.println("adding " + gh.getName() + " dependent to
" + this.getName() );
- if ( !dependencies.contains(gh) )
+ if (!dependencies.contains(gh))
dependencies.add(gh);
}
-
- /**
- * To get the name of the dependency of this
<code>GUITunableHandler</code>
- * @return the name of the dependency
- */
+ /** {...@inheritdoc} */
public String getDependency() {
return dependencyName;
}
- /**
- * Get the new "values" for the <code>Tunables</code> object that have
been modified if their JPanel is enabled
- */
- public void handleDependents(){
+ /** {...@inheritdoc} */
+ public void handleDependents() {
if (panel.isEnabled())
handle();
}
- /**
- * To check the dependencies of this <code>GUITunableHandler</code>
with the others.
- *
- *
- * <p><pre>
- * Check the dependencies :
- *
- * - if there isn't any dependency, the JPanel container is enabled
- * - if there is, enable or not the JPanel, depending on the name
(<code>depName</code>) and the state(<code>depState</code>)
- * of the dependencies of this <code>GUITunableHandler</code>
- * </pre></p>
- */
- public void checkDependency(String name, String state) {
+ /** {...@inheritdoc} */
+ final public void checkDependency(final String depName, final String
depState) {
// if we don't depend on anything, then we should be enabled
- if (dependencyName == null || dependencyState == null) {
+ if (dependencyName == null || mustMatch == null) {
setEnabledContainer(true, panel);
return;
}
// if the dependency name matches ...
- if (dependencyName.equals(name)) {
+ if (dependencyName.equals(depName)) {
// ... and the state matches, then enable
- if (!dependencyState.isEmpty()) {
- if (dependencyState.equals(state))
+ if (!mustMatch.isEmpty()) {
+ if (mustMatch.equals(depState))
setEnabledContainer(true, panel);
else // ... and the state doesn't match, then
disable
setEnabledContainer(false, panel);
} else {
- if (!dependencyUnState.equals(state))
+ if (!mustNotMatch.equals(depState))
setEnabledContainer(true, panel);
else // ... and the state doesn't match, then
disable
setEnabledContainer(false, panel);
@@ -218,34 +193,35 @@
}
/**
- * Set enable or not a container and all the components that are in it
+ * Enables or disables a container and all its children.
*
- * @param enable if we enable or not the container
- * @param container the container that will be enabled or not
+ * @param enable whether to enable the container or not
+ * @param container the container that will be enabled or not
*/
private void setEnabledContainer(final boolean enable, final Container
container) {
container.setEnabled(enable);
for (final Component child : container.getComponents()) {
if (child instanceof Container)
- setEnabledContainer(enable,(Container)child);
+ setEnabledContainer(enable, (Container)child);
else
child.setEnabled(enable);
}
}
/**
- * To get the <code>JPanel</code> container
- * @return the <code>JPanel</code> container of the
<code>GUITunableHandler</code>
+ * Returns the panel associated with this
<code>GUITunableHandler</code>.
+ * @return the <code>JPanel</code> container of this
<code>GUITunableHandler</code>
*/
public JPanel getJPanel() {
return panel;
}
- /** Update the state of the associated <code>Tunable</code>
- */
+ /** Updates the state of the associated <code>Tunable</code>. */
public abstract void handle();
- /**
+ /** Returns a string representation of the value of the
<code>Tunable</code> associated with
+ * this <code>GUITunableHandler</code>.
+ *
* @return the current value of the associated <code>Tunable</code>
represented as a string
*/
public String getState() {
Modified:
core3/work-swing-api/trunk/src/main/java/org/cytoscape/work/swing/AbstractGUITunableInterceptor.java
===================================================================
---
core3/work-swing-api/trunk/src/main/java/org/cytoscape/work/swing/AbstractGUITunableInterceptor.java
2010-11-04 17:08:36 UTC (rev 22716)
+++
core3/work-swing-api/trunk/src/main/java/org/cytoscape/work/swing/AbstractGUITunableInterceptor.java
2010-11-04 17:27:31 UTC (rev 22717)
@@ -18,16 +18,16 @@
/**
- * Interceptor of <code>Tunable</code> that will be applied on
<code>GUITunableHandlers</code>.
+ * Interceptor of <code>Tunable</code>s that will be applied on
<code>GUITunableHandlers</code>.
*
* <p><pre>
* To set the new value to the original objects contained in the
<code>GUITunableHandlers</code>:
* <ul>
- * <li>Creates the parent container for the GUI, or use the one that is
specified </li>
- * <li>Creates a GUI with swing components for each intercepted
<code>Tunable</code> </li>
+ * <li>Creates the parent container for the GUI, or uses the one that has
been specified</li>
+ * <li>Creates a GUI with Swing components for each intercepted
<code>Tunable</code></li>
* <li>
* Displays the GUI to the user, following the layout construction rule
specified in the <code>Tunable</code>
- * annotations, and the dependencies to enable or not the graphic
components
+ * annotations, and the dependencies to enable or disable the graphic
components
* </li>
* <li>
* Applies the new <i>value,item,string,state...</i> to the object
contained in the <code>GUITunableHandler</code>,
@@ -39,9 +39,16 @@
* @author pasteur
*/
public abstract class AbstractGUITunableInterceptor extends
SpringTunableInterceptor<GUITunableHandler> implements
GUITunableInterceptor<GUITunableHandler> {
+ /** A reference to the parent <code>JPanel</code>, if any. */
protected JPanel parentPanel = null;
+
+ /** The list of handlers associated with this interceptor. */
protected List<GUITunableHandler> handlers;
+
+ /** The actual/original objects whose tunables this interceptor
manages. */
protected Object[] objectsWithTunables;
+
+ /** Provides an initialised logger. */
protected Logger logger;
/**
@@ -54,22 +61,20 @@
logger = LoggerFactory.getLogger(getClass());
}
- /**
- * set the parent JPanel that will contain the GUI
- * If no parent JPanel is specified, the GUI will be made using a
JOptionPane
- *
- * @param parent component for the <code>GUITunableHandlers</code>'s
panels
- */
+ /** {...@inheritdoc} */
final public void setParent(final JPanel parent) {
this.parentPanel = (JPanel)parent;
}
+ /** {...@inheritdoc} */
final public JPanel getUI(final Object... proxyObjs) {
this.objectsWithTunables = convertSpringProxyObjs(proxyObjs);
handlers = new ArrayList<GUITunableHandler>();
return constructUI();
}
+ /** This is the final action in getUI() after the translating the
arguments to the original/actual annotated objects.
+ */
abstract protected JPanel constructUI();
/**
@@ -90,10 +95,15 @@
return displayGUI(panel, proxyObjs);
}
+ /** {...@inhertdoc} */
final public boolean hasTunables(final Object o) {
return super.hasTunables(convertSpringProxyObj(o));
}
+ /** This implements the final action in execUI() and executes the UI.
+ * @param optionPanel the panel containing the various UI elements
corresponding to individual tunables
+ * @param proxyObjs represents the objects annotated with tunables
+ */
protected boolean displayGUI(final JPanel optionPanel, Object...
proxyObjs) {
Object[] buttons = { "OK", "Cancel" };
int result = JOptionPane.showOptionDialog(parentPanel,
optionPanel,
Modified:
core3/work-swing-api/trunk/src/main/java/org/cytoscape/work/swing/GUITaskManager.java
===================================================================
---
core3/work-swing-api/trunk/src/main/java/org/cytoscape/work/swing/GUITaskManager.java
2010-11-04 17:08:36 UTC (rev 22716)
+++
core3/work-swing-api/trunk/src/main/java/org/cytoscape/work/swing/GUITaskManager.java
2010-11-04 17:27:31 UTC (rev 22717)
@@ -9,7 +9,7 @@
/**
* A Swing specific extension of {...@link TaskManager} that allows a
- * JPanels to be used to present the {...@link org.cytoscape.work.Tunable}s.
+ * JPanel to be used to present the {...@link org.cytoscape.work.Tunable}s.
*/
public interface GUITaskManager extends TaskManager {
/**
Modified:
core3/work-swing-api/trunk/src/main/java/org/cytoscape/work/swing/GUITunableHandler.java
===================================================================
---
core3/work-swing-api/trunk/src/main/java/org/cytoscape/work/swing/GUITunableHandler.java
2010-11-04 17:08:36 UTC (rev 22716)
+++
core3/work-swing-api/trunk/src/main/java/org/cytoscape/work/swing/GUITunableHandler.java
2010-11-04 17:27:31 UTC (rev 22717)
@@ -7,21 +7,19 @@
/**
- * Specific <code>Handler</code> for construction of GUI.
- * Access to the <code>Handler</code> for any type of <code>Tunable</code>
- * will be provided by using this interface
+ * An extension of <code>TunableHandler</code> with added functionality to
support the construction of a Swing-based UI.
*/
public interface GUITunableHandler extends TunableHandler {
/**
- * to get the panel that contains the GUI representation
+ * to get the panel that contains the GUI representation
* (<code>JTextField, JFileChooser, JLabel, JList ...</code>)
- *
+ *
* @return the panel containing GUI
*/
JPanel getJPanel();
-
+
/**
- * To get the current value of a <code>Handler</code>
+ * To get the current value of a <code>Handler</code>
* (or path for a <code>FileHandler</code>, or selected item(s)
* for <code>ListMultipleSelection ListSingleSelection</code>, ...)
*
@@ -29,53 +27,47 @@
*/
String getState();
-
/**
- * Use to set the intercepted object (with <code>Tunable</code>
annotation)
- * with the new <i>"value"</i> that has been chosen or entered by the
user through GUI.
+ * Updates an annotated object with the current value as retrieved from
the GUI.
*/
void handle();
-
-
+
/**
- * Notify dependents that this object is changing, i.e. an event
occured.
+ * Notify dependents that this object has changed, i.e. an event
occured.
*/
void notifyDependents();
-
+
/**
- * add a dependency to this <code>GUITunableHandler</code> on another
one
- *
+ * Adds a dependency to this <code>GUITunableHandler</code> on another
one.
+ *
* @param gh the <code>GUITunableHandler</code> it will depend on
*/
void addDependent(GUITunableHandler gh);
-
+
/**
- * Check if the dependency matches with the rule provided on the
- * other <code>GUITunableHandler</code>
- * <p>
- * The checking is done dynamically.
- * <p>
- *
- * If it matches : the GUI for this <code>GUITunableHandler</code> is
available,
- * or not if it doesn't match the dependency can me made on String,
- * a boolean value, a specific value for
- * an Integer,Double..., a selected item of a list ...
- * </p>
- *
- * @param name of the <code>GUITunableHandler</code> on which it depends
- * @param state of the <code>GUITunableHandler</code> that is needed to
make the GUI available
+ * To check the dependencies of this <code>GUITunableHandler</code>
with the others.
+ *
+ * <p><pre>
+ * Check the dependencies :
+ *
+ * - if there isn't any dependency, this handler's JPanel container is
enabled
+ * - if there is, enable or not the JPanel, depending on the name
(<code>depName</code>) and the state(<code>depState</code>)
+ * of the dependencies of this <code>GUITunableHandler</code>
+ * </pre></p>
+ *
+ * @param depName if this handler has a dependency, it must match
this in order for the associated <code>JPanel</code> to be enabled
+ * @param depState if this handler has a dependency, this must match
the condition in order for the associated <code>JPanel</code> to be enabled
*/
- void checkDependency(String name, String state);
-
+ void checkDependency(String depName, String depState);
+
/**
- * Get the new "values" for the <code>Tunables</code> object that have
- * been modified if their JPanel is enabled : if the dependencies are
matching
+ * Retrieves the settings for the <code>Tunables</code> object that
have been modified if their JPanel is enabled.
*/
void handleDependents();
-
+
/**
- * To get the name of the dependency of this
<code>GUITunableHandler</code>
- * @return the name of the dependency
+ * Provides the name of the dependency of this
<code>GUITunableHandler</code>.
+ * @return the name of the dependency, if any
*/
String getDependency();
}
Modified:
core3/work-swing-api/trunk/src/main/java/org/cytoscape/work/swing/GUITunableInterceptor.java
===================================================================
---
core3/work-swing-api/trunk/src/main/java/org/cytoscape/work/swing/GUITunableInterceptor.java
2010-11-04 17:08:36 UTC (rev 22716)
+++
core3/work-swing-api/trunk/src/main/java/org/cytoscape/work/swing/GUITunableInterceptor.java
2010-11-04 17:27:31 UTC (rev 22717)
@@ -19,7 +19,7 @@
*/
public interface GUITunableInterceptor<TH extends TunableHandler> extends
TunableInterceptor<TH> {
/**
- * Identify Tunables of an Object o and assign a <code>Handler</code>
to
+ * Identify Tunables of an Object o and assign a
<code>TunableHandler</code> to
* each <code>Tunable</code>.
*
* This method detects the fields and the methods of the object o, then
searches
@@ -34,10 +34,10 @@
void loadTunables(Object o);
/**
- * Returns the Map that contains all the <code>Handler</code>s for the
Object <code>o</code>.
+ * Returns the Map that contains all the <code>TunableHandler</code>s
for an object <code>o</code>.
*
* @param o An Object on which the loadTunable() method has previously
been executed.
- * @return The Map with all the <code>Handlers</code> that have been
previously assigned
+ * @return the map with all the <code>Handlers</code> that have been
previously assigned
* to <code>o</code>.
*/
Map<String, TH> getHandlers(Object o);
@@ -88,9 +88,8 @@
*/
boolean validateAndWriteBackTunables(Object... objs);
- /** Tests an object for having tunable annotations.
- *
- * @return true if "o" has tunable annotations and else false.
+ /** Tests an object for whether it has been annotated with
<code>@Tunable</code> or not.
+ * @return true if <code>o</code> has been annoated with
<code>@Tunable</code>, otherwise false
*/
boolean hasTunables(final Object o);
}
--
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.
