Package org.cytoscape.work
Annotation Interface Tunable
An annotation type that can be applied to public fields or a methods
in a
Here is an example of how to use a
Here is an example of how to use a
Task
object that allows the Task
to be configured
with user supplied information. Tunable
annotations allow Task
s 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 Tunable
s 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
Modifier and TypeOptional ElementDescriptionReturns the context that thisTunable
is meant for.To add a dependency between two or moreTunables
, where the display of oneTunable
depends on the the state of another.Mandatory, human-readable label identifying the Tunable as displayed to a user.Optional example string for use in scripting environments.Provides a decimal format string suitable forDecimalFormat
.double
Returns the gravity used to place the tunable in the panel.String[]
Used to define the presentation grouping of the Tunable.String[]
Returns a list of Tunable field/method names that will trigger this Tunable to be updated.Optional human-readable description that can provide more complete description of that theTunable
does and the implication of various settings.Returns a key1=value1;key2=value2;...;keyN=valueN type string.boolean
If this parameter is required, return true, otherwise it is assumed that a null (or empty) value is properly handled by the Task.Optional human-readable description that can provide more complete description of that theTunable
does and the implication of various settings.boolean
Returns true if this field or method is used to control the display of otherTunable
s.Returns a value that matches one of the values found in a different Tunable annotated field or method that returnstrue
for thexorChildren()
method. -
Field Summary
-
Field Details
-
GUI_CONTEXT
- See Also:
-
NOGUI_CONTEXT
- See Also:
-
BOTH_CONTEXT
- See Also:
-
-
Element Details
-
description
String descriptionMandatory, human-readable label identifying the Tunable as displayed to a user.- Default:
- ""
-
longDescription
String longDescriptionOptional human-readable description that can provide more complete description of that theTunable
does and the implication of various settings. This is intended for scripting use.- Default:
- ""
-
tooltip
String tooltipOptional human-readable description that can provide more complete description of that theTunable
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 exampleStringValueOptional example string for use in scripting environments. This string should be valid according to any formatting rules for thisTunable
, and ideally should represent a usable value at execution time, though the latter is not a requirement.- Default:
- ""
-
groups
String[] groupsUsed 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 lastNameTunable
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 officeNameTunable
to "Office" group. The "Identity" group will appear with officeName within the "Office" group.- Default:
- {}
-
gravity
double gravityReturns the gravity used to place the tunable in the panel. Gravity is a numeric value associated with each tunable item.Tunable
s are sorted in ascending order based on their gravity values. The firstTunable
to show will be the one with lowest value.- Returns:
- The gravity of the
Tunable
- Default:
- 999.0
-
xorChildren
boolean xorChildrenReturns true if this field or method is used to control the display of otherTunable
s. The other Tunables in question are matched according thegroups()
value and thexorKey()
of the other Tunables. SeexorKey()
for a full example.- Returns:
- true if this field or method is used to control the display of other
Tunable
s.
- Default:
- false
-
xorKey
String xorKeyReturns a value that matches one of the values found in a different Tunable annotated field or method that returnstrue
for thexorChildren()
method. Example :@Tunable(description="Distance measure", group={"Measure"}, xorChildren=true) public ListSingleSelection
Based on the selection made in the "chooser"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"); Tunable
, either the "metric" or the "english"Tunable
will be displayed, not both. ThexorKey
value must match one of the values specified in thexorChildren
Tunable
.- Default:
- ""
-
dependsOn
String dependsOnTo add a dependency between two or moreTunables
, where the display of oneTunable
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="";
Sohostname
will only be displayed iftype
is set to "true"- Default:
- ""
-
params
String paramsReturns 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 thetitleBorder
of theJPanel
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 aListSingleSelection
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.
- Default:
- ""
-
listenForChange
String[] listenForChangeReturns 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 contextReturns the context that thisTunable
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 thisTunable
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 thisTunable
will not be available through the GUI.- Default:
- "both"
-
required
boolean requiredIf 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 formatProvides a decimal format string suitable forDecimalFormat
. 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:
- ""
-