examples/Interactive Widgets/Widget Styles.ipynb

{
 "metadata": {
  "cell_tags": [
   [
    "<None>",
    null
   ]
  ],
  "name": "",
  "signature": "sha256:cd7d3d42126bdbf20c087014460779dfbdb0a63dcb8f489ba7ebfc230a685edd"
 },
 "nbformat": 3,
 "nbformat_minor": 0,
 "worksheets": [
  {
   "cells": [
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "from IPython.html import widgets # Widget definitions\n",
      "from IPython.display import display # Used to display widgets in the notebook"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 1
    },
    {
     "cell_type": "heading",
     "level": 1,
     "metadata": {},
     "source": [
      "CSS"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "When trying to design an attractive widget GUI, styling becomes important.\n",
      "Most widget views are DOM (document object model) elements that can be controlled with CSS.\n",
      "There are two helper methods that allow the manipulation of the widget's CSS.\n",
      "The first is the `Widget.set_css` method.\n",
      "This method allows one or more CSS attributes to be set at once.  "
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "print(widgets.DOMWidget.set_css.__doc__)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "Set one or more CSS properties of the widget.\n",
        "\n",
        "        This function has two signatures:\n",
        "        - set_css(css_dict, selector='')\n",
        "        - set_css(key, value, selector='')\n",
        "\n",
        "        Parameters\n",
        "        ----------\n",
        "        css_dict : dict\n",
        "            CSS key/value pairs to apply\n",
        "        key: unicode\n",
        "            CSS key\n",
        "        value:\n",
        "            CSS value\n",
        "        selector: unicode (optional, kwarg only)\n",
        "            JQuery selector to use to apply the CSS key/value.  If no selector \n",
        "            is provided, an empty selector is used.  An empty selector makes the \n",
        "            front-end try to apply the css to a default element.  The default\n",
        "            element is an attribute unique to each view, which is a DOM element\n",
        "            of the view that should be styled with common CSS (see \n",
        "            `$el_to_style` in the Javascript code).\n",
        "        \n"
       ]
      }
     ],
     "prompt_number": 2
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "The second is `get_css` which allows CSS attributesto be read.\n",
      "Note that this method will only read CSS attributes that have been set using the `set_css` method."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "print(widgets.DOMWidget.get_css.__doc__)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "Get a CSS property of the widget.\n",
        "\n",
        "        Note: This function does not actually request the CSS from the \n",
        "        front-end;  Only properties that have been set with set_css can be read.\n",
        "\n",
        "        Parameters\n",
        "        ----------\n",
        "        key: unicode\n",
        "            CSS key\n",
        "        selector: unicode (optional)\n",
        "            JQuery selector used when the CSS key/value was set.\n",
        "        \n"
       ]
      }
     ],
     "prompt_number": 3
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Below is an example that applies CSS attributes to a container to emphasize text."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "label = widgets.LatexWidget()\n",
      "label.value = \"$\\\\textbf{ALERT:} Hello World!$\"\n",
      "container = widgets.ContainerWidget(children=[label])\n",
      "\n",
      "# set_css used to set a single CSS attribute.\n",
      "container.set_css('border', '3px solid black') # Border the container\n",
      "\n",
      "# set_css used to set multiple CSS attributes.\n",
      "container.set_css({'padding': '6px', # Add padding to the container\n",
      "                   'background': 'yellow'}) # Fill the container yellow\n",
      "\n",
      "display(container)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 4
    },
    {
     "cell_type": "heading",
     "level": 1,
     "metadata": {},
     "source": [
      "CSS Classes"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "In some cases, it is necessary to apply CSS classes to your widgets.\n",
      "CSS classes allow DOM elements to be indentified in Javascript and CSS.\n",
      "The notebook defines its own set of classes to stylize its elements.\n",
      "The `add_class` widget method allows you to add CSS classes to your widget."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "print(widgets.DOMWidget.add_class.__doc__)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "Add class[es] to a DOM element.\n",
        "\n",
        "        Parameters\n",
        "        ----------\n",
        "        class_names: unicode or list\n",
        "            Class name(s) to add to the DOM element(s).\n",
        "        selector: unicode (optional)\n",
        "            JQuery selector to select the DOM element(s) that the class(es) will\n",
        "            be added to.\n",
        "        \n"
       ]
      }
     ],
     "prompt_number": 5
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Since `add_class` is a DOM operation, **it will only affect widgets that have already been displayed**.\n",
      "`add_class` must be called after the widget has been displayed.\n",
      "Extending the example above, the corners of the container can be rounded by adding the `corner-all` CSS class to the container."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "container = widgets.ContainerWidget()\n",
      "container.set_css({'border': '3px solid black',\n",
      "                   'padding': '6px', \n",
      "                   'background': 'yellow'}) \n",
      "\n",
      "label = widgets.LatexWidget()\n",
      "label.value = \"$\\\\textbf{ALERT:} Hello World!$\"\n",
      "container.children = [label]\n",
      "display(container)\n",
      "container.add_class('corner-all') # Must be called AFTER display"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 6
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "The IPython notebook uses [bootstrap](http://getbootstrap.com/\u200e) for styling.\n",
      "The example above can be simplified by using a bootstrap class:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "label = widgets.LatexWidget(value = \"$\\\\textbf{ALERT:} Hello World!$\")\n",
      "display(label)\n",
      "\n",
      "# Apply twitter bootstrap alert class to the label.\n",
      "label.add_class(\"alert\")"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 7
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "The example below shows how bootstrap classes can be used to change button apearance."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "# List of the bootstrap button styles\n",
      "button_classes = ['Default', 'btn-primary', 'btn-info', 'btn-success', \n",
      "                  'btn-warning', 'btn-danger', 'btn-inverse', 'btn-link']\n",
      "\n",
      "# Create each button and apply the style.  Also add margin to the buttons so they space\n",
      "# themselves nicely.\n",
      "for i in range(8):\n",
      "    button = widgets.ButtonWidget(description=button_classes[i])\n",
      "    button.set_css(\"margin\", \"5px\")\n",
      "    display(button)\n",
      "    if i > 0: # Don't add a class the first button.\n",
      "        button.add_class(button_classes[i])\n",
      "    "
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 8
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "It is also useful to be able to remove CSS classes from widgets.\n",
      "The `remove_class` method allows you to remove classes from widgets that have been displayed.\n",
      "Like `add_class`, it must be called after the widget has been displayed."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "print(widgets.DOMWidget.remove_class.__doc__)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "Remove class[es] from a DOM element.\n",
        "\n",
        "        Parameters\n",
        "        ----------\n",
        "        class_names: unicode or list\n",
        "            Class name(s) to remove from  the DOM element(s).\n",
        "        selector: unicode (optional)\n",
        "            JQuery selector to select the DOM element(s) that the class(es) will\n",
        "            be removed from.\n",
        "        \n"
       ]
      }
     ],
     "prompt_number": 9
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "The example below animates an alert using different bootstrap styles."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "import time\n",
      "label = widgets.LatexWidget(value = \"$\\\\textbf{ALERT:} Hello World!$\")\n",
      "display(label)\n",
      "\n",
      "# Apply twitter bootstrap alert class to the label.\n",
      "label.add_class(\"alert\")\n",
      "\n",
      "# Animate through additional bootstrap label styles 3 times\n",
      "additional_alert_styles = ['alert-error', 'alert-info', 'alert-success']\n",
      "for i in range(3 * len(additional_alert_styles)):\n",
      "    label.add_class(additional_alert_styles[i % 3])\n",
      "    label.remove_class(additional_alert_styles[(i-1) % 3])\n",
      "    time.sleep(1)\n",
      "        "
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": 10
    }
   ],
   "metadata": {}
  }
 ]
}