Merge pull request #133 from bmorris3/set-ref-widget

enable: anchor new Sidecar relative to a reference widget

Author: martinRenou

README.md

@@ -57,6 +57,17 @@ new JupyterLab window which can be re-arranged as desired.
 
 ![sidecar in main work area](sidecar-main-area.gif)
 
+### Arrange a new sidecar with respect to another sidecar
+
+The `anchor` parameter sets the position of the new sidecar relative to the
+notebook that opens the sidecar, by default. To open a new sidecar whose `anchor`
+is defined relative to another sidecar output, set the `ref` parameter with
+the instance of the reference sidecar.
+
+For example:
+
+![sidecar arranged with respect to another sidecar](sidecar-ref-anchor.png)
+
 ## Development
 
 ```bash

sidecar-ref-anchor.png

@@ -7,9 +7,9 @@
 """
 TODO: Add module docstring
 """
-
-from ipywidgets import Output
-from traitlets import Unicode, CaselessStrEnum
+import warnings
+from ipywidgets import Output, widget_serialization
+from traitlets import Unicode, CaselessStrEnum, Any, Instance, observe
 from ._frontend import EXTENSION_SPEC_VERSION
 
 module_name = "@jupyter-widgets/jupyterlab-sidecar"
@@ -28,3 +28,13 @@ class Sidecar(Output):
         default_value='right',
         allow_none=True
     ).tag(sync=True)
+    ref = Instance('sidecar.Sidecar', allow_none=True).tag(sync=True, **widget_serialization)
+    _widget_id = Any().tag(sync=True)
+
+    @observe('ref')
+    def _validate_ref_anchor(self, *args):
+        if self.ref.anchor == 'right':
+            warnings.warn(
+                "`ref` cannot be set when `ref.anchor == 'right'`. "
+                "Proceeding with `ref = None`.", UserWarning
+            )

sidecar/sidecar.py

@@ -25,7 +25,7 @@ const sidecarPlugin: JupyterFrontEndPlugin<void> = {
     const SidecarView = class extends output.OutputView {
       model: SidecarModel;
 
-      render() {
+      async render() {
         if (!this.model.rendered) {
           super.render();
 
@@ -42,7 +42,7 @@ const sidecarPlugin: JupyterFrontEndPlugin<void> = {
             }
           );
           w.id = UUID.uuid4();
-
+          this.model.set('_widget_id', w.id);
           if (this.model.views && Object.keys(this.model.views).length > 1) {
             w.node.style.display = 'none';
             const key = Object.keys(this.model.views)[0];
@@ -53,12 +53,19 @@ const sidecarPlugin: JupyterFrontEndPlugin<void> = {
             });
           } else {
             const anchor = this.model.get('anchor') || 'right';
+            const ref = this.model.get('ref');
+            let widget_id: string | null = null;
+            if (ref) {
+              await ref.created;
+              widget_id = ref.get('_widget_id');
+            }
             if (anchor === 'right') {
               app.shell.add(w, 'right');
             } else {
-              app.shell.add(w, 'main', { mode: anchor });
+              app.shell.add(w, 'main', { ref: widget_id, mode: anchor });
             }
             app.shell.activateById(w.id);
+            this.model.resolveCreated();
           }
         }
       }

src/index.ts

@@ -3,7 +3,8 @@
 
 import { DOMWidgetModel } from '@jupyter-widgets/base';
 import { output } from '@jupyter-widgets/jupyterlab-manager';
-
+import { PromiseDelegate } from '@lumino/coreutils';
+import { unpack_models } from '@jupyter-widgets/base';
 import { EXTENSION_SPEC_VERSION } from './version';
 
 export class SidecarModel extends output.OutputModel {
@@ -19,10 +20,28 @@ export class SidecarModel extends output.OutputModel {
       _view_module: SidecarModel.view_module,
       _view_module_version: SidecarModel.view_module_version,
       title: 'Sidecar',
-      anchor: 'right'
+      anchor: 'right',
+      ref: null,
+      _widget_id: null
     };
   }
 
+  get created(): Promise<void> {
+    return this._viewCreated.promise;
+  }
+
+  public resolveCreated() {
+    this._viewCreated.resolve();
+  }
+
+  private _viewCreated: PromiseDelegate<void> = new PromiseDelegate<void>();
+
+  // deserialize the ref property
+  static serializers = {
+    ...DOMWidgetModel.serializers,
+    ref: { deserialize: unpack_models as any }
+  };
+
   initialize(attributes: any, options: any) {
     super.initialize(attributes, options);