single-select-generics {iSEE} | R Documentation |
A panel can create a single selection on either the rows or columns and transmit this selection to another panel for use as an aesthetic parameter. For example, users can click on a RowTable to select a gene of interest, and then the panel can transmit the identities of that row to another panel for coloring by that selected gene's expression. This suite of generics controls the behavior of these single selections.
Given an instance of the Panel class x
, .singleSelectionDimension(x)
should return a string
specifying whether the selection contains a single "feature"
,
"sample"
, or if the Panel in x
does not perform single selections at all ("none"
).
The output should be constant for all instances of x
.
.singleSelectionValue(x, contents)
should return a string specifying the selected row or column.
If no row or column is selected, it should return NULL
.
contents
is any arbitrary structure set by the rendering expression in .renderOutput
for x
.
This should contain all of the information necessary to determine the name of the selected row/column.
For example, a data.frame of coordinates is stored by DotPlots to identify the point selected by a brush/lasso.
.singleSelectionSlots(x)
should return a list with one internal list for each slot in x
that might respond to a single selection from a transmitting panel.
This internal list should contain at least entries with the following names:
param
, the name of the slot of x
that can potentially respond to a single selection in a transmitting panel,
e.g., ColorByFeatureName
in DotPlots.
source
, the name of the slot of x
that indicates which transmitting panel to respond to,
e.g., ColorByFeatureSource
in DotPlots.
The paradigm here is that the interface will contain two selectInput
elements, one for each of the param
and source
slots.
It is possible for users to manually alter the choice in the param
's selectInput
;
it is also possible for users to specify a transmitting panel via the source
's selectInput
,
which will then trigger automatic updates to the chosen entry in the param
's selectInput
when the transmitter's single selection changes.
Developers are strongly recommended to follow the above paradigm.
In fact, the observers to perform these updates are automatically set up by .createObservers,Panel-method
if the internal list also contains the following named entries:
dimension
, a string set to either "feature"
or "sample"
.
This specifies whether the slot specified by param
contains the identity of a single feature or a single sample.
If this is not present, no observers will be set up.
dynamic
, the name of the slot indicating whether the choice of transmitting panel should change dynamically.
One example would be "ColorByFeatureDynamicSource"
for DotPlots.
This can be missing if the current panel does not support dynamic selection sources.
use_mode
, the name of the slot of x
containing the current usage mode,
in cases where there are multiple choices of which only one involves using information held in source
.
An example would be ColorBy
in DotPlots where coloring by feature name is only one of many options,
such that the panel should only respond to transmitted single selections when the user intends to color by feature name.
If this is NA
, the usage mode is assumed to be such that the panel should always respond to transmissions.
use_value
, a string containing the relevant value of the slot specified by use_mode
in order for the panel to respond to transmitted single selections.
An example would be "Feature name"
in DotPlots.
protected
, a logical scalar indicating whether the slot specified by param
is “protected”,
i.e., changing this value will cause all existing selections to be invalidated
and will trigger re-rendering of the children receiving multiple selections.
This is FALSE
for purely aesthetic parameters (e.g., coloring) and TRUE
for data-related parameters
(e.g., XAxisFeatureName
in FeatureAssayPlot).
Aaron Lun