org.cytoscape.work

Annotation Type Tunable

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

An annotation type that can be applied to public fields or a methods in a Task object that allows the Task to be configured with user supplied information. Tunable annotations allow Tasks to be configured with specific, user supplied data, without needing to produce a user interface. The TaskManager is responsible for inferring a user interface from the types of the fields or methods being annotated.
Tunable annotations are suitable only for information that must be supplied by the user. For instance, the name of a file to load can only be known by the user, so is appropriate to be specified by the user. Other information necessary for the Task to execute should be provided as constructor arguments to the Task.
Tunable annotations provide several parameters that can be used to control the display of Tunables in the eventual user interface. These parameters are documented below.
Here is an example of how to use a Tunable annotation for a field annotation:

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

This tunable will be grouped in the user interface first within the "Human" group, then within the "pupil" group. How this grouping is displayed to users is a function of which TaskManager is used. Likewise, if supported by the TaskManager, the display state of the Tunable will initially be collapsed.
Here is an example of how to use a Tunable annotation for method annotation. Method annotations require both a getter and a setter method to get and set a value. Only the getter method needs to be annotated. The getter method must take no arguments and return a value and be named with the prefix "get". The setter method does not need a Tunable annotation, however the method must take a single argument of the same type as the getter method, it must return void, it must be named with the prefix "set", and the rest of the name must match that of the getter method. If the group name begins with underscore (_) then the display of the group name will be suppressed.

        @Tunable(description="your last name", group={"Human","pupil"}, params="displayState=collapsed")
        public String getLastName() {
       return lastName;
  }
 
  // NO Tunable annotation for the setter method. 
        public void setLastName(String newLastName) {
       lastName = newLastName;
  }
 

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.

Module: work-api

To use this in your app, include the following dependency in your POM:

<dependency>
    <groupId>org.cytoscape</groupId>
    <artifactId>work-api</artifactId>
</dependency>

Field Summary

Fields

Modifier and Type	Fields and Description
static String	BOTH_CONTEXT
static String	GUI_CONTEXT
static String	NOGUI_CONTEXT

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
String	context Returns the context that this Tunable is meant for.
String	dependsOn To add a dependency between two or more Tunables, where the display of one Tunable depends on the the state of another.
String	description Mandatory, human-readable label identifying the Tunable as displayed to a user.
String	exampleStringValue Optional example string for use in scripting environments.
String	format Provides a decimal format string suitable for DecimalFormat.
double	gravity Returns the gravity used to place the tunable in the panel.
String[]	groups Used to define the presentation grouping of the Tunable.
String[]	listenForChange Returns a list of Tunable field/method names that will trigger this Tunable to be updated.
String	longDescription Optional human-readable description that can provide more complete description of that the Tunable does and the implication of various settings.
String	params Returns a key1=value1;key2=value2;...;keyN=valueN type string.
boolean	required If this parameter is required, return true, otherwise it is assumed that a null (or empty) value is properly handled by the Task.
String	tooltip Optional human-readable description that can provide more complete description of that the Tunable does and the implication of various settings.
boolean	xorChildren Returns true if this field or method is used to control the display of other Tunables.
String	xorKey Returns a value that matches one of the values found in a different Tunable annotated field or method that returns true for the xorChildren() method.

Field Detail

GUI_CONTEXT

public static final String GUI_CONTEXT

NOGUI_CONTEXT

public static final String NOGUI_CONTEXT

BOTH_CONTEXT

public static final String BOTH_CONTEXT

Element Detail

description

public abstract String description

Mandatory, human-readable label identifying the Tunable as displayed to a user.

Default:

""

longDescription

public abstract String longDescription

Optional human-readable description that can provide more complete description of that the Tunable does and the implication of various settings. This is intended for scripting use.

Default:

""

tooltip

public abstract String tooltip

Optional human-readable description that can provide more complete description of that the Tunable does and the implication of various settings. In general, this might be implemented in a GUI as a tooltip, but might also be used for other purposes.

Default:

""

exampleStringValue

public abstract String exampleStringValue

Optional example string for use in scripting environments. This string should be valid according to any formatting rules for this Tunable, and ideally should represent a usable value at execution time, though the latter is not a requirement.

Default:

""

groups

public abstract String[] groups

Used to define the presentation grouping of the Tunable. By default a Tunable belongs to the top level group. Example:

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

The lastName Tunable will be nested within the "Company", "Department", "Office", and "Identity" groups. The order of groups defines their nesting. 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 = "Cytoscape Development";
        

Here we add a second item (firstName) to the "Identity" group and then add the officeName Tunable to "Office" group. The "Identity" group will appear with officeName within the "Office" group.

Default:

{}

gravity

public abstract double gravity

Returns the gravity used to place the tunable in the panel. Gravity is a numeric value associated with each tunable item. Tunables are sorted in ascending order based on their gravity values. The first Tunable to show will be the one with lowest value.

Returns:

The gravity of the Tunable

Default:

999.0

xorChildren

public abstract boolean xorChildren

Returns true if this field or method is used to control the display of other Tunables. The other Tunables in question are matched according the groups() value and the xorKey() of the other Tunables. See xorKey() for a full example.

Returns:

true if this field or method is used to control the display of other Tunables.

Default:

false

xorKey

public abstract String xorKey

Returns a value that matches one of the values found in a different Tunable annotated field or method that returns true for the xorChildren() method. Example :

        @Tunable(description="Distance measure", group={"Measure"}, xorChildren=true)
        public ListSingleSelection chooser = new ListSingleSelection("Metric","English");
        
        @Tunable(description="Metric distances", group={"Measure","Metric"}, xorKey="Metric")
        public ListSingleSelection metric = new ListSingleSelection("millimeter","meter","kilometer");
 
        @Tunable(description="English distances", group={"Measure","English"}, xorKey="English")
        public ListSingleSelection english = new ListSingleSelection("inch","yard","mile");
 

Based on the selection made in the "chooser" Tunable, either the "metric" or the "english" Tunable will be displayed, not both. The xorKey value must match one of the values specified in the xorChildren Tunable.

Default:

""

dependsOn

public abstract String dependsOn

To add a dependency between two or more Tunables, where the display of one Tunable depends on the the state of another.

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 only be displayed 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 can be used by BoundedDouble, BoundedFloat, and similar classes.
• 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:

{}

context

public abstract String context

Returns the context that this Tunable is meant for. Must be one of "gui", "nogui", or "both". If no value is provided, "both" is assumed. If the context is set to "gui", then this Tunable will only be available through GUI implementations, and will not be made available to command-line or headless implementations. If the context is set to "nogui", then this Tunable will not be available through the GUI.

Default:

"both"

required

public abstract boolean required

If this parameter is required, return true, otherwise it is assumed that a null (or empty) value is properly handled by the Task.

Returns:

true if required

Default:

false

format

public abstract String format

Provides a decimal format string suitable for DecimalFormat. This allows default values and ranges to be rationally presented to users. Note that this is only for presentation purposes and does not effect the underlying values. Also, not all Tunables will respect format. At this point, only numeric and bounded numeric tunables respect format.

Returns:

the string to use for the format

Default:

""