Add examples for asynchronous display and interactive_output

jupyter-widgets · Nov 3, 2017 · 338eba2 · 338eba2
1 parent f800c95
commit 338eba2
Show file tree

Hide file tree

Showing 2 changed files with 154 additions and 0 deletions.
diff --git a/docs/source/examples/Using Interact.ipynb b/docs/source/examples/Using Interact.ipynb
@@ -894,6 +894,96 @@
     "interact(slow_function,i=FloatSlider(min=1e5, max=1e7, step=1e5, continuous_update=False));"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### `interactive_output`\n",
+    "\n",
+    "The `interactive_output` function provides maximum flexibility at the cost of a bit more code.\n",
+    "\n",
+    "It does not generate a user interface for the widgets, like `interact`, `interactive`, and `interact_manual` do. This is powerful, because it means you can create a widget, put it in box, and then pass the widget to `interactive_output`, and have control over the widget and its layout."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 29,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "e6e8696551f64c45a73ef7cb61af3c08",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/html": [
+       "<p>Failed to display Jupyter Widget of type <code>VBox</code>.</p>\n",
+       "<p>\n",
+       "  If you're reading this message in Jupyter Notebook or JupyterLab, it may mean\n",
+       "  that the widgets JavaScript is still loading. If this message persists, it\n",
+       "  likely means that the widgets JavaScript library is either not installed or\n",
+       "  not enabled. See the <a href=\"https://ipywidgets.readthedocs.io/en/stable/user_install.html\">Jupyter\n",
+       "  Widgets Documentation</a> for setup instructions.\n",
+       "</p>\n",
+       "<p>\n",
+       "  If you're reading this message in another notebook frontend (for example, a static\n",
+       "  rendering on GitHub or <a href=\"https://nbviewer.jupyter.org/\">NBViewer</a>),\n",
+       "  it may mean that your frontend doesn't currently support widgets.\n",
+       "</p>\n"
+      ],
+      "text/plain": [
+       "VBox(children=(HBox(children=(IntSlider(value=0), IntSlider(value=0), IntSlider(value=0))),))"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "597c952b0a5b43248e25011e2d6bbfed",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/html": [
+       "<p>Failed to display Jupyter Widget of type <code>Output</code>.</p>\n",
+       "<p>\n",
+       "  If you're reading this message in Jupyter Notebook or JupyterLab, it may mean\n",
+       "  that the widgets JavaScript is still loading. If this message persists, it\n",
+       "  likely means that the widgets JavaScript library is either not installed or\n",
+       "  not enabled. See the <a href=\"https://ipywidgets.readthedocs.io/en/stable/user_install.html\">Jupyter\n",
+       "  Widgets Documentation</a> for setup instructions.\n",
+       "</p>\n",
+       "<p>\n",
+       "  If you're reading this message in another notebook frontend (for example, a static\n",
+       "  rendering on GitHub or <a href=\"https://nbviewer.jupyter.org/\">NBViewer</a>),\n",
+       "  it may mean that your frontend doesn't currently support widgets.\n",
+       "</p>\n"
+      ],
+      "text/plain": [
+       "Output()"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "source": [
+    "from ipywidgets import *\n",
+    "\n",
+    "a=IntSlider()\n",
+    "b=IntSlider()\n",
+    "c=IntSlider()\n",
+    "ui=HBox([a,b,c])\n",
+    "def f(a,b,c):\n",
+    "    print((a,b,c))\n",
+    "\n",
+    "out = interactive_output(f, {'a': a, 'b': b, 'c': c})\n",
+    "\n",
+    "display(VBox([HBox([a,b,c])]), out)"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},

diff --git a/docs/source/examples/Widget Asynchronous.ipynb b/docs/source/examples/Widget Asynchronous.ipynb
@@ -280,6 +280,70 @@
     "thread.start()"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Displaying a widget in the background\n",
+    "\n",
+    "While a widget's _value_ can be updated from a background thread, note that a widget cannot be (reliably) _displayed_ from a background thread.\n",
+    "\n",
+    "This is because output widgets are capturing based on the thread in which they were invoked. In other words, in the thread where the output is invoked, there is a context manager which starts and then stops the output capturing. If the threaded displays happen to occur during this time frame, they'll also be captured. However, if the threaded displays happen to occur after the main thread stops capturing output, those displays will not be put in that output widget.\n",
+    "\n",
+    "This means that sometimes trying to display a widget from a background thread will appear to work fine, and sometimes one or more widgets that were supposed to be displayed will be simply missing.\n",
+    "\n",
+    "Instead, we can define and display a box widget in the main thread, and add children to it in the secondary worker thread. This does not break the context manager that handles communication between the kernel and the frontend, and it will work reliably every time. It operates on a similar concept to the previously discussed task of modifying a widget's `value` in the background."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 33,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "6f19432afe8d4fd0be1bf129ff7a33d2",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/plain": [
+       "A Jupyter Widget"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "source": [
+    "import threading\n",
+    "from IPython.display import display, HTML\n",
+    "import ipywidgets\n",
+    "\n",
+    "def alpha(textvalue):\n",
+    "    def beta(something, container):\n",
+    "        output = ipywidgets.Output()\n",
+    "        # Using 'with output:' here means that all widgets and display() calls\n",
+    "        # calls will direct their output to our Output() area, instead of being\n",
+    "        # displayed in the notebook directly\n",
+    "        with output:\n",
+    "            for i in range(1,10):\n",
+    "                display('%d'%i + '**'*i + something)\n",
+    "        container.children += (output,)\n",
+    "\n",
+    "    display('Display in main thread: ' + textvalue)\n",
+    "    container = ipywidgets.VBox()\n",
+    "    # Now the key: the container is displayed (while empty) in the main thread\n",
+    "    display(container)\n",
+    "\n",
+    "    mapthread = threading.Thread(\n",
+    "        target=beta,\n",
+    "        args=(textvalue, container))\n",
+    "    mapthread.start()\n",
+    "\n",
+    "ipywidgets.interact(alpha, textvalue='A String');"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {