Report Chart Interactions and Completed Updates

Makes a chart report clicks to Shiny, so an app can react to the part of the chart that was clicked: show the details of a gene, open the settings of the clicked part, and so on. Charts are not clickable unless this is set, and click reporting has no effect outside Shiny.

Usage

GC_events(
  GC_chart,
  click = TRUE,
  highlight = FALSE,
  rendered = FALSE,
  render_id = NULL,
  dblclick = FALSE,
  select = FALSE,
  legend_click = TRUE,
  drag = FALSE,
  zoom = FALSE
)

Arguments

GC_chart: A GC chart object.
click: Logical, whether to report clicks to Shiny.
highlight: Logical, whether to outline the part of the chart under the mouse, to show what a click selects.
rendered: Logical, whether to report successful chart updates.
render_id: Optional single character string or finite number returned with the rendered event, to identify the update. The default, NULL, generates a unique ID for each update in the browser. It is not a DOM element ID; the event's chartId identifies the chart itself. A new render_id also marks a new load for GC_zoom(), which then starts at its range again, also when rendered is FALSE.
dblclick: Logical, whether to report double-clicks for editing.
select: Logical, whether to enable individual element selection.
legend_click: Logical, whether legend clicks are reported to Shiny.
drag: Logical, enable dragging gene labels, chart titles and cluster titles, footers, labels, whole scale bars and axes, and legend labels and markers, each on its own. Off by default. Releasing a drag reports input$<outputId>_drag and geneviewer:drag, with position containing moveX and moveY offsets in whole SVG pixels and action set to "drag". Apply them with GC_element_style() to preserve the position on redraw. Escape cancels an active drag. Moves can be undone and redone, see Details.
zoom: Logical, whether to report the window of the zoom slider of GC_zoom() as input$<outputId>_zoom and geneviewer:zoom: mode, start and end of the window in the units of the mode (whole base pairs, or shares to 0.0001), zoomed (FALSE when everything shows), range, the window to pass to GC_zoom(range = ) (NULL when everything shows), clusters, the cluster and the first and last base pair it shows, and action: "drag", "keyboard" or "reset" by the user, "set" by GC_zoom_to(), or "render" when a render changed the window, e.g. new data. It is reported on the first render and after every change, so an app always knows the window.

Value

The GC chart object with the event settings.

Details

Each click sets input$<outputId>_click, e.g. input$chart_click for GC_chartOutput("chart"), to a list with:

component: The part of the chart that was clicked: "genes", "transcript", "labels", "coordinates", "links", "legend", "scale", "scaleBar", "sequence", "title" (the chart title), "clusterTitle", "clusterFooter", "clusterLabel" or "annotations".
cluster: The cluster that was clicked, or NULL for the chart title, the legend and links between clusters.
data: The data of the clicked element, or NULL: the row of the gene for genes, transcripts and labels, the row of the link for links, and the group for the legend.

Every part of the chart is marked with a data-component attribute and each cluster with data-cluster, also without this function, so they can be selected with CSS or JavaScript.

With dblclick = TRUE, double-clicks independently report the same payload to input$<outputId>_dblclick and the bubbling browser event geneviewer:dblclick. Browsers also send clicks during a double-click: use clicks for selection, and double-clicks for editing, rather than opening different settings panels on each event.

With select = TRUE, a click selects an individual editable element and outlines it. Clicking it again, empty chart space or a noneditable part of the chart, or pressing Escape, clears selection. Shift-, Ctrl- or Cmd-click adds an element to the selection or takes it out, and dragging on empty chart space draws a box that selects the elements entirely inside it (with Shift, Ctrl or Cmd, in addition to the selection). With drag = TRUE as well, dragging one of the selected elements moves all of them that can be moved, and the arrow keys move them together; such a move of several elements is one step to undo, reported as input$<outputId>_moves. Selection reports the payload of the element selected last (or NULL when cleared) to input$<outputId>_select and geneviewer:select, and a list of the payloads of all selected elements, in the order they were selected, to input$<outputId>_selection and geneviewer:selection. It survives redraws of the same data and resize. When a redraw changes the selected element's style, its updated payload is reported again. Selected items can be opened with Enter when dblclick = TRUE; items are keyboard focusable in selection mode. Use click = FALSE to avoid legacy single-click settings handlers. legend_click = FALSE excludes legend clicks from click reporting without enabling legend click editing. Legend labels and patches are individually selectable, with part set to "label" or "marker" and data set to the original group value. Legend clicks edit instead of toggling visibility when selection or double-click events are enabled, or when click reporting is enabled with legend_click = TRUE. Otherwise they hide/show genes. Double-click and selection browser events also work outside Shiny.

Click, double-click and selection payloads of editable elements also contain style: how it is drawn, with the names of GC_element_style() options, so an editor can show the current values. For a gene these are fill, opacity, stroke, strokeWidth, strokeDasharray, marker, markerSize, markerHeight, arrowheadWidth, arrowheadHeight, cornerRadius and y; for a label fill, opacity, text, fontSize (in pixels), fontWeight, fontStyle and fontFamily. Colours are hex codes, except transparent colours, "none" and patterns. Legend labels report the same text options; legend markers report fill, opacity, stroke, strokeWidth and strokeDasharray.

With drag = TRUE, the undo, redo and reset icons next to the download icon undo and redo moves, and move every element back to where it was first drawn, so positions set with GC_element_style() are kept. They show while the mouse is over the chart, once there is a move. After clicking the chart, Ctrl+Z (Cmd+Z on a Mac) undoes and Ctrl+Shift+Z or Ctrl+Y redoes. With select = TRUE as well, the arrow keys move the selected text or scale by a pixel, or 10 pixels with Shift. Each drag is one step to undo, arrow-key moves of one element within a second are one step, and a reset is one step. A step that moves one element reports it like a drag, with action set to "undo", "redo" or "nudge". A step that moves more, such as a reset, reports input$<outputId>_moves and geneviewer:moves once, with action ("reset", "undo" or "redo") and moves, a list of drag payloads, so an app that keeps drags keeps these too. Steps whose element was since moved by something else are dropped. Outside Shiny, moves are kept when the chart is resized.

With rendered = TRUE, each successful update also sets input$<outputId>_rendered to a list containing id (the supplied render_id, or a generated ID), chartId (the chart's DOM element ID), width and height (the widget size in pixels). When render_id is NULL, a new ID is generated in the browser for each successful update, unique across charts on the page. chartId stays the same when that chart updates; generated render IDs change. Explicit IDs, including 0 and "", are kept. It fires after the chart, legend, links and click handlers have been built, once per data update, including repeated identifiers, but not on resize or a failed draw. It does not wait for browser paint or external image loading.

The widget also dispatches a bubbling geneviewer:rendered browser event with the same fields in event.detail, including outside Shiny. A loading indicator can listen to it without inspecting the widget payload. Use a different render_id for each load and ignore events for older loads.

Examples

genes_data <- data.frame(
  start = c(10, 50, 90, 130),
  end = c(40, 80, 120, 160),
  name = c("Gene 1", "Gene 2", "Gene 3", "Gene 4"),
  group = c("A", "A", "B", "C")
)

if (interactive()) {
  library(shiny)
  ui <- fluidPage(
    GC_chartOutput("chart", height = "200px"),
    verbatimTextOutput("clicked")
  )
  server <- function(input, output, session) {
    output$chart <- renderGC_chart(
      GC_chart(genes_data, group = "group") %>%
        GC_labels("name") %>%
        GC_events(highlight = TRUE)
    )
    output$clicked <- renderPrint(str(input$chart_click))
  }
  shinyApp(ui, server)
}