Author: mmichaud
Date: 2009-04-16 10:15:46 -0700 (Thu, 16 Apr 2009)
New Revision: 16602
Modified:
core3/work-api/trunk/src/main/java/org/cytoscape/work/Tunable.java
core3/work-api/trunk/src/main/java/org/cytoscape/work/TunableInterceptor.java
core3/work-api/trunk/src/main/java/org/cytoscape/work/TunableValidator.java
Log:
Modified: core3/work-api/trunk/src/main/java/org/cytoscape/work/Tunable.java
===================================================================
--- core3/work-api/trunk/src/main/java/org/cytoscape/work/Tunable.java
2009-04-16 17:15:07 UTC (rev 16601)
+++ core3/work-api/trunk/src/main/java/org/cytoscape/work/Tunable.java
2009-04-16 17:15:46 UTC (rev 16602)
@@ -5,13 +5,88 @@
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.FIELD,ElementType.TYPE})
+/**
+ * This interface describes the different parameters that can be used in the
<code> @Tunable(...) </code> to display the GUI, add some dependencies...
+ *
+ * Here is an example of how to use it these <code>Tunable's annotation</code>
:
+ *
+ * <br>
+ * <code>
+ * @Tunable(description="your last name", group={"Human","pupil"},
flag={Param.collapsed})<br>
+ * public String lastName = "Smith";<br>
+ * </code>
+ * <br>
+ *
+ * This tunable will take part of a group("<code>pupil</code>"), which is also
a part of a metagroup("<code>Human</code>").<br>
+ * The initial state of the panel that will display the JTextField with the
<code>lastName</code> will be collapsed<code>Param.collapsed</code> : need to
expand it to see its components<br>
+ *
+ * */
+
public @interface Tunable{
+ /**
+ * Description of the Tunable that will be displayed in the panel to
identify it
+ */
public String description();
+
+
+
+ /**
+ * Parameters to interact directly with the way the
<code>Tunable</code> will be represented in its JPanel :<br>
+ * - <code>slider</code> to display a JSlider for the Tunable with
bounds<br>
+ * - <code>horizontal / vertical</code> to display the tunables
that belong to the same group horizontally, or vertically( default
representation is <code> Param.vertical</code> <br>
+ * - <code>uncollapsed / collapsed</code> to allow the tunable's
JPanel to be collapsable, and to define its initial state<br>
+ * - <code>network / session / attributes</code> to add some
filters to the <code>File</code> Tunable.<br>
+ */
Param[] flag() default {};
+
+
+
+ /**
+ * Used to define all the groups in which the Tunable takes part (by
default, its doesn't belong to any group)<br>
+ */
public String[] group() default {};
+
+
+
+ /**
+ * Boolean value to choose if the Tunable will control the display of
other JPanels as children
+ */
boolean xorChildren() default false;
+
+
+ /**
+ * Key that will refer to the value of the Tunable which has
<code>xorChildren=true</code>
+ */
String xorKey() default "";
+
+
+ /**
+ * To add a dependency between Tunables<br>
+ * The JPanel of the Tunable that depends on the other one will be
activated only if the value which is required is set.<br>
+ * Here is an example of how to add dependencies between Tunables :<br>
+ * <code>
+ * @Tunable(description="Type")<br>
+ * public boolean type = false;<br>
+ * <br>
+ * @Tunable(description="Host name",dependsOn="type=true")<br>
+ * public String hostname="";<br>
+ * </code>
+ * <br>
+ * So <code>hostname</code> will be activated if <code>type</code> is
set to "true"
+ */
String dependsOn() default "";
- public enum Param
{slider,nothing,horizontal,vertical,uncollapsed,collapsed,network,session,attributes}
+
+
+
+ /**
+ * Parameters to display the Tunables of a same group horizontally or
vertically inside.
+ */
Param[] alignment() default {};
+
+
+
+ /**
+ * Enumeration that contains the parameters used for
<code>flag{}</code> and <code>alignment{}</code>
+ */
+ public enum Param
{slider,horizontal,vertical,uncollapsed,collapsed,network,session,attributes}
}
Modified:
core3/work-api/trunk/src/main/java/org/cytoscape/work/TunableInterceptor.java
===================================================================
---
core3/work-api/trunk/src/main/java/org/cytoscape/work/TunableInterceptor.java
2009-04-16 17:15:07 UTC (rev 16601)
+++
core3/work-api/trunk/src/main/java/org/cytoscape/work/TunableInterceptor.java
2009-04-16 17:15:46 UTC (rev 16602)
@@ -3,15 +3,70 @@
import java.util.Map;
+
+/**
+ * Provides methods to intercept the Objects annotated as
<code>@Tunable</code>, use, and display them.
+ * @author Mathieu
+ *
+ * @param <T> <code>Handlers</code> that will be detected. They will contain
the informations provided by the <code>@Tunable</code> annotations and the
Object itself.
+ */
public interface TunableInterceptor<T extends Handler> {
+
+
+ /**
+ * Catch the Tunables of the object o
+ *
+ * This method detects the fields of the object o, then search for
<code>@Tunable</code> annotations, and finally create a <code>Handler</code>
for each type of Object by using the <code>HandlerFactory</code> .
+ * The handlers are stocked in a HashMap and can then be retrieved by
their Key(i.e name of the field)
+ *
+ * @param o This has to be a class that contains some
<code>@Tunable</code> annotations.
+ */
public void loadTunables(Object o);
+
+
+ /**
+ * To get the Map that contains all the <code>Handlers</code> for the
Object o
+ *
+ * @param o The Object on which the loadTunable() method has been
executed.
+ * @return The Map with all the <code>Handlers</code> that have been
previously detected.
+ */
public Map<String,T> getHandlers(Object o);
+
+
+ /**
+ * Display the Objects caught to the user in order to modify their
values.
+ *
+ * Create the UI with JPanels for each <code>Guihandler</code>, and
display it to the user :<br>
+ * 1) In a <i>parent</i> JPanel if <code>setParent()</code> method
has been called before<br>
+ * The new values will be applied to the original Objects
depending on the action that has been associated to the Buttons provided by
this panel.<br>
+ *
+ * 2) By default in a JOptionPanel<br>
+ * This method will detect if the Object that contains the
<code>@Tunable</code> annotations is implementing the
<code>TunableValidator</code> interface, and if yes, execute the validation
test.
+ * The new values will be applied to the original Objects if "OK"
is clicked, and if the validation test has succeeded. Either, no modification
will happen.
+ *
+ * @param obs Object[] which contains classes with
<code>Tunables</code> that need to be caught.
+ * @return newValuesSet True if the values has been modified, false if
not.
+ */
public boolean createUI(Object ... obs );
+
+
+ /**
+ * Use to add the Tunables' JPanels to an external JPanel that has been
defined in another class.
+ * @param o An Object that has to be an instance of a
<code>JPanel</code>.
+ * @throws IllegalArgumentException If the Object o is not a JPanel, it
can not be set as the parent for the others : they will be displayed to the
user in a <code>JOptionPanel</code>.
+ */
public void setParent(Object o);
+
+
+ /**
+ * Use to apply the new values that have been modified to the original
Objects.
+ * This method will set the value for the Object of each
<code>Guihandler</code> taken from the <code>Map</code> that is containing the
<code>Handlers</code>.<br>
+ * Important : the value of the <code>Guihandler</code> will be set
only if its JPanel is valid.
+ */
public void handle();
}
Modified:
core3/work-api/trunk/src/main/java/org/cytoscape/work/TunableValidator.java
===================================================================
--- core3/work-api/trunk/src/main/java/org/cytoscape/work/TunableValidator.java
2009-04-16 17:15:07 UTC (rev 16601)
+++ core3/work-api/trunk/src/main/java/org/cytoscape/work/TunableValidator.java
2009-04-16 17:15:46 UTC (rev 16602)
@@ -1,5 +1,18 @@
package org.cytoscape.work;
+
+/**
+ * If implemented, it is used to apply a test to the modified values of the
class.
+ *
+ * @author Mathieu
+ *
+ */
public interface TunableValidator{
+
+ /**
+ * Executes the validation test on the annotated <code>Tunables</code>
present in the class whose Objects have been modified.
+ *
+ * @return The message that will be displayed if the test failed, or
<i>null</i> if the test succeeded.
+ */
public String validate();
}
\ No newline at end of file
--~--~---------~--~----~------------~-------~--~----~
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
-~----------~----~----~----~------~----~------~--~---
