docs/source/examples/Notebook/Custom Keyboard Shortcuts.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Keyboard Shortcut Customization"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Starting with Jupyter Notebook 5.0, you can customize the `command` mode shortcuts from within the Notebook Application itself. \n",
    "\n",
    "Head to the **`Help`** menu and select the **`Edit keyboard Shortcuts`** item.\n",
    "A dialog will guide you through the process of adding custom keyboard shortcuts.\n",
    "\n",
    "Keyboard shortcut set from within the Notebook Application will be persisted to your configuration file. \n",
    "A single action may have several shortcuts attached to it."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Keyboard Shortcut Customization (Pre Notebook 5.0)"
   ]
  },
  {
   "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 Jupyter JavaScript API. Here is an example that makes the `r` key available for running a cell:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%javascript\n",
    "\n",
    "Jupyter.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",
    ");"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\"By default the keypress `r`, while in command mode, changes the type of the selected cell to `raw`.  This shortcut is overridden by the code in the previous cell, and thus the action no longer be available via the keypress `r`.\""
   ]
  },
  {
   "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",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%javascript\n",
    "\n",
    "Jupyter.keyboard_manager.command_shortcuts.add_shortcut('r', function (event) {\n",
    "    IPython.notebook.execute_cell();\n",
    "    return false;\n",
    "});"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Likewise, to remove a shortcut, use `remove_shortcut`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%javascript\n",
    "\n",
    "Jupyter.keyboard_manager.command_shortcuts.remove_shortcut('r');"
   ]
  },
  {
   "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 `custom.js` file."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "Of course we provide name for majority of existing action so that you do not have to re-write everything, here is for example how to bind `r` back to it's initial behavior:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%javascript\n",
    "\n",
    "Jupyter.keyboard_manager.command_shortcuts.add_shortcut('r', 'jupyter-notebook:change-cell-to-raw');"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.5.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}