Package org.cytoscape.work

Annotation Interface Tunable

@Retention(RUNTIME) @Target({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;
  }

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>

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

    Optional Elements
    Modifier and Type
    Optional Element
    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 Summary

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

  • Field Details

  • Element Details

    • description

      String description
      Mandatory, human-readable label identifying the Tunable as displayed to a user.
      Default:
      ""

    • longDescription

      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

      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

      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

      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

      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

      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

      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

      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

      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.
      • lookup: if present and the Tunable is a ListSingleSelection Tunable then provide a lookup capability to the JComboBox that allows users to type in values. If the value of this parameter is "contains" then any matching text will be searched. If the value is "begins" then only the beginning of the string will be searched.
      • password: This is used for String tunables. If set to "true" then the input field will be masked by displaying '*' characters instead of the actual characters that the user types. WARNING: This parameter is only supported by Cytoscape 3.10 or later. If an App that uses this parameter is run on an earlier version of Cytoscape then the password will be visible. Please set your App's minimum Cytoscape version to 3.10 or later to ensure the password field is masked.
      Note: Blanks/spaces in values are significant!
      Default:
      ""

    • listenForChange

      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

      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

      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

      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:
      ""