org.cytoscape.work
Annotation Type Tunable

@Retention(value=RUNTIME)
@Target(value={FIELD,METHOD})
public @interface Tunable

An annotation type that can be applied to a field or a method in order to allow TunableInterceptor to catch it, and so to use its members to create a corresponding interface for a user.
This interface describes the different members that can be used in the @Tunable(...) to control the instantiation of user interface to present to a user.
Here is an example of how to use a Tunable annotation:

 
        @Tunable(description="your last name", group={"Human","pupil"}, params="displayState=collapsed")
        public String lastName = "Smith";
 
 

This tunable will be part of a group("pupil"), which is also a part of a metagroup("Human").
If a the user interface auto-generated from this is a GUI, collapsed could indicate that the initial state of the panel that may display the JTextField with the lastName will be collapsed and needs to be expanded in order to see its components.

Cytoscape Backwards Compatibility (API Interface): We expect that this interface will be used but not implemented by developers using this interface. As such, we reserve the right to add methods to the interface as part of minor version upgrades. We will not remove methods for any changes other than major version upgrades.

Optional Element Summary

String	dependsOn To add a dependency between 2 or more Tunables
String	description Human-readable label identifying the tunable as displayed to a user.
String[]	groups Used to define all the groups in which the Tunable takes part (by default, its doesn't belong to any group).
String[]	listenForChange Returns a list of Tunable field/method names that will trigger this Tunable to be updated.
String	params Returns a key1=value1;key2=value2;...;keyN=valueN type string.
boolean	xorChildren Boolean value to choose if the Tunable will control the display of other, nested child tunables.
String	xorKey Key that will refer to the "value" of the Tunable which has xorChildren=true

description

public abstract String description

Human-readable label identifying the tunable as displayed to a user.

Default:

""

groups

public abstract String[] groups

Used to define all the groups in which the Tunable takes part (by default, its doesn't belong to any group).

 Example:
        @Tunable(description="write your last name", group={"Company","Department","office","identity"})
        public String lastName = "Smith";
 

This String Tunable will take part of these 4 groups. warning: Note that they are set in an order of subgroups of a main one.

 Example:
 
        @Tunable(description="write your first name", groups={"Company","Department","office","identity"})
        public String firstName = "John";
 
        @Tunable(description="write the name of your office", groups={"Company","Department","office"})
        public String officeName = "CytoscapeDevelopment's Office";
        
 
 Here we have a second item for the identity of a person(the firstName).So, 
 the 2 Tunable lastName and firstName are in the subgroup 
 identity But, the Tunable String officeName will only take part 
 of the upperGroup office, and so won't be set with these other 2 fields.
 

Default:

{}

xorChildren

public abstract boolean xorChildren

Boolean value to choose if the Tunable will control the display of other, nested child tunables.

Default:

false

xorKey

public abstract String xorKey

Key that will refer to the "value" of the Tunable which has xorChildren=true

 Example : 
        @Tunable(description="Single list", group={"TestGroup"}, xorChildren=true)
        public ListSingleSelection chooser = new ListSingleSelection("Names","FirstNames");
        
        @Tunable(description="Multi list", group={"TestGroup","Names"}, xorKey="Names")
        public ListMultipleSelection names = new ListMultipleSelection("Johnson","Turner","Smith");
 
        @Tunable(description="Multi list", group={"TestGroup","First Names"}, xorKey="FirstNames")
        public ListMultipleSelection firstnames = new ListMultipleSelection("George","Jane","Sarah");
 
 

Here, the 2 ListMultipleSelection won't be displayed in the GUI at the same time : each of them depends on the xorKey(FirstNames or Names) that will match the "value" (i.e item that has been selected) in the ListSingleSelection

Default:

""

dependsOn

public abstract String dependsOn

To add a dependency between 2 or more Tunables

 The JPanel of the Tunable that depends on the 
 other one will be activated only if the value which is required is set.
 
 Here is an example of how to add dependencies between Tunables :
 
 
   @Tunable(description="Type")
   public boolean type = false;

   @Tunable(description="Host name",dependsOn="type=true")
   public String hostname="";
 
  

So hostname will be activated if type is set to "true"

Default:

""

params

public abstract String params

Returns a key1=value1;key2=value2;...;keyN=valueN type string. To include commas, semicolons or backslashes in a value you must escape it with a leading backslash. Possible keys (which must consist of letters only) are

• fileCategory: this is used solely for File tunables and must be one of "network", "table", "image", "attribute", "session", or "unspecified".
• input: this is used solely for File tunables and must be either "true" or "false"
• slider: used when the object's values range should be represented by a slider, the value should always be "true". This is being used by AbstractBounded and AbstractFlexiblyBounded.
• alignments: the value should be a comma-separated list of "horizontal" or "vertical". This controls the arrangement of a Tunable within a group, if nothing has been specified, "vertical" will be the default. These values will be in a 1-to-1 correspondence with the strings in the "group" array. Excess values will be ignored.
• groupTitles: the value should be a comma-separated list of "hidden" and/or "displayed" indicating whether the name of a Tunable's group has to be displayed or not in the titleBorder of the JPanel representing this group.
• displayState: if present, the corresponding Tunable's JPanel will be collapsible. The value must be either "collapsed" or "uncollapsed" indicating the initial display state.

Note: Blanks/spaces in values are significant!

Default:

""

listenForChange

public abstract String[] listenForChange

Returns a list of Tunable field/method names that will trigger this Tunable to be updated. For instance if Tunable B wants to react to a change in Tunable A, then setting the listenForChange parameter is one mechanism for achieving this. The listenForChange parameter will trigger the update method on the TunableHandler to be called, which will cause B to be updated. Here is an example:

 @Tunable(description="A")
 public String getA() {
    return a;   
 }
 
 public void setA(String a) {
    this.a = a;
 }

 // listenForChange="A" means that the value of this 
 // Tunable will be updated every time A is changed.
 @Tunable(description="B",listenForChange="A")
 public String getB() {
    if ( a.equals("somethingSpecial") )
        return "hooray!";
    else
        return b;       
 }
 
 public void setB(String b) {
    this.b = b;
 }
 

Returns:

a list of Tunable field/method names that will trigger this Tunable to be updated.

Default:

{}