examples/Notebook/Custom Keyboard Shortcuts.ipynb

{
 "metadata": {
  "name": ""
 },
 "nbformat": 3,
 "nbformat_minor": 0,
 "worksheets": [
  {
   "cells": [
    {
     "cell_type": "heading",
     "level": 1,
     "metadata": {},
     "source": [
      "Keyboard Shortcut Customization"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Starting with IPython 2.0 keyboard shortcuts in command and edit mode are fully customizable. These customizations are made using the IPython JavaScript API. Here is an example that makes the `r` key available for running a cell:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%%javascript\n",
      "\n",
      "IPython.keyboard_manager.command_shortcuts.add_shortcut('r', {\n",
      "    help : 'run cell',\n",
      "    help_index : 'zz',\n",
      "    handler : function (event) {\n",
      "        IPython.notebook.execute_cell();\n",
      "        return false;\n",
      "    }}\n",
      ");"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "javascript": [
        "\n",
        "IPython.keyboard_manager.command_shortcuts.add_shortcut('r', {\n",
        "    help : 'run cell',\n",
        "    help_index : 'zz',\n",
        "    handler : function (event) {\n",
        "        IPython.notebook.execute_cell();\n",
        "        return false;\n",
        "    }}\n",
        ");"
       ],
       "metadata": {},
       "output_type": "display_data",
       "text": [
        "<IPython.core.display.Javascript at 0x10e8d1890>"
       ]
      }
     ],
     "prompt_number": 7
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "There are a couple of points to mention about this API:\n",
      "\n",
      "* The `help_index` field is used to sort the shortcuts in the Keyboard Shortcuts help dialog. It defaults to `zz`.\n",
      "* When a handler returns `false` it indicates that the event should stop propagating and the default action should not be performed. For further details about the `event` object or event handling, see the jQuery docs.\n",
      "* If you don't need a `help` or `help_index` field, you can simply pass a function as the second argument to `add_shortcut`."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%%javascript\n",
      "\n",
      "IPython.keyboard_manager.command_shortcuts.add_shortcut('r', function (event) {\n",
      "    IPython.notebook.execute_cell();\n",
      "    return false;\n",
      "});"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "javascript": [
        "\n",
        "IPython.keyboard_manager.command_shortcuts.add_shortcut('r', function (event) {\n",
        "    IPython.notebook.execute_cell();\n",
        "    return false;\n",
        "});"
       ],
       "metadata": {},
       "output_type": "display_data",
       "text": [
        "<IPython.core.display.Javascript at 0x1019baf90>"
       ]
      }
     ],
     "prompt_number": 11
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Likewise, to remove a shortcut, use `remove_shortcut`:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%%javascript\n",
      "\n",
      "IPython.keyboard_manager.command_shortcuts.remove_shortcut('r');"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "javascript": [
        "\n",
        "IPython.keyboard_manager.command_shortcuts.remove_shortcut('r');"
       ],
       "metadata": {},
       "output_type": "display_data",
       "text": [
        "<IPython.core.display.Javascript at 0x10e8d1950>"
       ]
      }
     ],
     "prompt_number": 8
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "If you want your keyboard shortcuts to be active for all of your notebooks, put the above API calls into your `<profile>/static/custom/custom.js` file."
     ]
    }
   ],
   "metadata": {}
  }
 ]
}