Package org.cytoscape.work

Annotation Type 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 Detail

      • GUI_CONTEXT

        static final String GUI_CONTEXT

      • NOGUI_CONTEXT

        static final String NOGUI_CONTEXT

      • BOTH_CONTEXT

        static final String BOTH_CONTEXT

    • Element Detail

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