feat(gridView): merge pull request #25 from swsoyee/grid-view

feat(gridView): implement feature (#24)

NAMESPACE

@@ -30,6 +30,7 @@ export(m_enable_fog)
 export(m_fetch_pdb)
 export(m_get_model)
 export(m_glimpse)
+export(m_grid)
 export(m_is_animated)
 export(m_multi_resi_sel)
 export(m_remove_all_labels)

NEWS.md

@@ -2,19 +2,17 @@
 
 ### Features
 
+* Add `m_grid()` to support multiple viewers ([#25](https://github.com/swsoyee/r3dmol/pull/25)).
 * Quickly look at structures with `m_glimpse()`. Initializes the viewer with 
 a range of useful defaults. Allows for quickly visually inspecting the structure
 and further customization of the viewer to speed up setup.
 * Add multiple lines and cylinders in one function call are supported ([#17](https://github.com/swsoyee/r3dmol/pull/17)). Refer to [this article](https://swsoyee.github.io/r3dmol/articles/multi-selections.html) for 
 more information.
 * Add `speed` option for `m_spin()` and option for `keepH` in `m_add_model()` ([#13](https://github.com/swsoyee/r3dmol/pull/13)).
 
-### Documentation
-
-* Add logo for `{r3dmol}` ([#16](https://github.com/swsoyee/r3dmol/pull/16)).
-
 ### Others
 
+* Add logo for `{r3dmol}` ([#16](https://github.com/swsoyee/r3dmol/pull/16)).
 * Function `m_set_view_style()` is deprecated and replaced by `m_add_outline()`.
 * Upgrade `3Dmol.js` to the latest version (v1.6.2) ([#12](https://github.com/swsoyee/r3dmol/pull/12)).
 

R/grid.R

@@ -0,0 +1,100 @@
+#' Create a grid of viewers that share a WebGL canvas
+#'
+#' @param viewer A list contains sub-viewers.
+#' @param element_id HTML string identifier.
+#' @param rows Number of rows in viewer grid.
+#' @param cols Number of columns in viewer grid.
+#' @param control_all Logical, simaultaneous mouse control of all windows in the
+#'  grid.
+#' @param viewer_config Viewer specification to apply to all subviewers.
+#' @param width Fixed width for combined viewer (in css units). Ignored when
+#' used in a Shiny app -- use the \code{width} parameter in
+#' \code{\link[r3dmol]{r3dmolOutput}}.
+#' It is not recommended to use this parameter because the widget knows how to
+#' adjust its width automatically.
+#' @param height Fixed height for combined viewer (in css units). It is
+#' recommended to not use this parameter since the widget knows how to adjust
+#' its height automatically.
+#'
+#' @return An \code{r3dmol} object (the output from \code{r3dmol()}).
+#' @export
+#'
+#' @examples
+#' library(r3dmol)
+#'
+#' m1 <- r3dmol() %>%
+#'   m_add_model(data = pdb_6zsl, format = "pdb") %>%
+#'   m_zoom_to()
+#'
+#' m2 <- m1 %>%
+#'   m_set_style(style = m_style_cartoon(color = "spectrum"))
+#'
+#' m3 <- m1 %>%
+#'   m_set_style(style = m_style_stick())
+#'
+#' m4 <- m1 %>%
+#'   m_set_style(style = m_style_sphere())
+#'
+#' m_grid(
+#'   viewer = list(m1, m2, m3, m4),
+#'   control_all = TRUE,
+#'   viewer_config = m_viewer_spec(
+#'     backgroundColor = "black"
+#'   )
+#' )
+m_grid <- function(viewer,
+                   element_id,
+                   rows = NULL,
+                   cols = NULL,
+                   control_all = TRUE,
+                   viewer_config = m_viewer_spec(),
+                   width = NULL,
+                   height = NULL) {
+  # TODO move it to utils and add test
+  if (missing(element_id)) {
+    element_id <- (sample(256, 10, replace = TRUE) - 1) %>%
+      as.hexmode() %>%
+      format(width = 2) %>%
+      paste(collapse = "")
+  }
+
+  # TODO move it to utils and add test
+  if (is.null(rows)) {
+    rows <- ceiling(sqrt(length(viewer)))
+  }
+
+  if (is.null(cols)) {
+    cols <- ceiling(length(viewer) / rows)
+  }
+
+  configs <- list(
+    rows = rows,
+    cols = cols,
+    control_all = control_all
+  )
+
+  x <- list(
+    viewer = viewer,
+    element_id = element_id,
+    configs = configs,
+    viewer_config = viewer_config,
+    api = "grid"
+  )
+
+  widget <- htmlwidgets::createWidget(
+    name = "r3dmol",
+    x,
+    width = width,
+    height = height,
+    package = "r3dmol",
+    elementId = element_id,
+    sizingPolicy = htmlwidgets::sizingPolicy(
+      defaultWidth = "100%",
+      knitr.figure = FALSE,
+      browser.fill = TRUE,
+      padding = 0
+    )
+  )
+
+  return(widget)
+}

R/r3dmol.R

@@ -45,6 +45,7 @@ r3dmol <- function(id = NULL,
                    width = NULL,
                    height = NULL,
                    elementId = NULL) {
+  # TODO move it to utils and add test
   if (missing(id)) {
     id <- (sample(256, 10, replace = TRUE) - 1) %>%
       as.hexmode() %>%

inst/htmlwidgets/r3dmol.js

@@ -52,6 +52,11 @@ HTMLWidgets.widget({
       renderValue(x) {
         // alias this
         const that = this;
+
+        if (x.viewer) {
+          viewer = x.viewer;
+        }
+
         if (!initialized) {
           initialized = true;
           // attach the widget to the DOM
@@ -60,7 +65,22 @@ HTMLWidgets.widget({
           $(el).css({
             position: x.position || 'relative',
           });
-          viewer = $3Dmol.createViewer($(container), x.configs);
+          if (x.api === 'grid') {
+            const viewers = $3Dmol.createViewerGrid($(container), x.configs, x.viewer_config);
+            let index = 0;
+            for (let i = 0; i < x.configs.rows; i += 1) {
+              for (let j = 0; j < x.configs.cols; j += 1) {
+                x.viewer[index].x.viewer = viewers[i][j];
+                that.renderValue(x.viewer[index].x);
+                index += 1;
+              }
+            }
+          }
+          if (x.viewer) {
+            viewer = x.viewer;
+          } else {
+            viewer = $3Dmol.createViewer($(container), x.configs);
+          }
         }
         // set listeners to events and pass data back to Shiny
         if (HTMLWidgets.shinyMode) {
@@ -89,7 +109,11 @@ HTMLWidgets.widget({
         }
         // Auto render
         if (isAutoRenderFunction.findIndex((element) => element === lastCallFunction) > -1) {
-          viewer.render();
+          if (x.viewer) {
+            x.viewer.render();
+          } else {
+            viewer.render();
+          }
         }
       },