"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:"
"<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`:"
"<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."
"This notebook describes the user interface of the IPython Notebook. This includes both mouse and keyboard based navigation and interaction.\n",
"\n",
"<div class=\"alert\" style=\"margin: 10px\">\n",
"This notebook describes the user interface of the IPython Notebook. This includes both mouse and keyboard based navigation and interaction."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"<div class=\"alert\">\n",
"As of IPython 2.0, the user interface has changed significantly. Because of this we highly recommend existing users to review this information after upgrading to IPython 2.0. All new users of IPython should review this information as well.\n",
"</div>"
]
},
{
"cell_type": "heading",
"level": 2,
"metadata": {},
"source": [
"Overview of the UI"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The notebook UI has the following main areas:\n",
"\n",
"* Menu\n",
"* Toolbar\n",
"* Notebook area and cells\n",
"\n",
"IPython 2.0 has an interactive tour of these elements that can be started in the \"Help:User Interface Tour\" menu item."
]
},
{
"cell_type": "heading",
"level": 2,
@ -57,10 +84,15 @@
"\n",
"<img src=\"images/edit_mode.png\">\n",
"\n",
"When a cell is in edit mode, you can type into the cell, like a normal text editor.\n",
"Enter edit mode by pressing `enter` or using the mouse to click on a cell's editor area.\n",
"When a cell is in edit mode, you can type into the cell, like a normal text editor."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"<div class=\"alert alert-success\">\n",
"Enter edit mode by pressing `Enter` or using the mouse to click on a cell's editor area.\n",
"</div>"
]
},
@ -80,14 +112,24 @@
"\n",
"<img src=\"images/command_mode.png\">\n",
"\n",
"When you are in command mode, you are able to edit the notebook as a whole, but not type into individual cells. Most importantly, in command mode, the keyboard is mapped to a set of shortcuts that let you perform notebook and cell actions efficiently. For example, if you are in command mode and you press `c`, you will copy the current cell - no modifier is needed.\n",
"When you are in command mode, you are able to edit the notebook as a whole, but not type into individual cells. Most importantly, in command mode, the keyboard is mapped to a set of shortcuts that let you perform notebook and cell actions efficiently. For example, if you are in command mode and you press `c`, you will copy the current cell - no modifier is needed."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"<div class=\"alert alert-error\">\n",
"Don't try to type into a cell in command mode; unexpected things will happen!\n",
"Enter command mode by pressing `esc` or using the mouse to click *outside* a cell's editor area.\n",
"</div>"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"<div class=\"alert alert-success\">\n",
"Enter command mode by pressing `Esc` or using the mouse to click *outside* a cell's editor area.\n",
"</div>"
]
},
@ -121,9 +163,9 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"The second idea of mouse based navigation is that **cell actions usually apply to the currently selected cell**. Thus if you want to run the code in a cell, you would select it and click the \"Play\" button in the toolbar or the \"Cell:Run\" menu item. Similarly, to copy a cell you would select it and click the \"Copy\" button in the toolbar or the \"Edit:Copy\" menu item. With this simple pattern, you should be able to do most everything you need with the mouse.\n",
"The second idea of mouse based navigation is that **cell actions usually apply to the currently selected cell**. Thus if you want to run the code in a cell, you would select it and click the <button><i class=\"icon-play\"></i></button> button in the toolbar or the \"Cell:Run\" menu item. Similarly, to copy a cell you would select it and click the <button><i class=\"icon-copy\"></i></button> button in the toolbar or the \"Edit:Copy\" menu item. With this simple pattern, you should be able to do most everything you need with the mouse.\n",
"\n",
"Markdown and heading cells have one other state that can be modified with the mouse. These cells can either be rendered or unrendered. When they are rendered, you will see a nice formatted representation of the cell's contents. When they are unrendered, you will see the raw text source of the cell. To render the selected cell with the mouse, click the \"Play\" button in the toolbar or the \"Cell:Run\" menu item. To unrender the selected cell, double click on the cell."
"Markdown and heading cells have one other state that can be modified with the mouse. These cells can either be rendered or unrendered. When they are rendered, you will see a nice formatted representation of the cell's contents. When they are unrendered, you will see the raw text source of the cell. To render the selected cell with the mouse, click the <button><i class=\"icon-play\"></i></button> button in the toolbar or the \"Cell:Run\" menu item. To unrender the selected cell, double click on the cell."
]
},
{
@ -140,100 +182,27 @@
"source": [
"The modal user interface of the IPython Notebook has been optimized for efficient keyboard usage. This is made possible by having two different sets of keyboard shortcuts: one set that is active in edit mode and another in command mode.\n",
"\n",
"The most important keyboard shortcuts are `enter`, which enters edit mode, and `esc`, which enters command mode.\n",
"The most important keyboard shortcuts are `Enter`, which enters edit mode, and `Esc`, which enters command mode.\n",
"\n",
"In edit mode, most of the keyboard is dedicated to typing into the cell's editor. Thus, in edit mode there are relatively few shortcuts:"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The `display_edit_shortcuts()` function used here is defined in the [Utilities section](#Utilities) at the bottom of this notebook."
"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",
"The notebook UI and notebook documents are a linear sequence of cells. There are four cell types:\n",
"<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",
"* **Code cells:** Input and output of live code that is run in the kernel\n",
"* **Markdown cells:** Narrative text with embedded LaTeX equations\n",
"* **Heading cells:** 6 levels of hierarchical organization and formatting\n",
"* **Raw cells:** Unformatted text that is included, without modification, when notebooks are converted to different formats using nbconvert\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",
"More information about code and Markdown cell can be found in these tutorials:\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`:"
"* [Working With Code Cells](Working With Code Cells.ipynb)\n",
"* [Working With Markdown Cells](Working With Markdown Cells.ipynb)"
"<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."
]
},
{
"cell_type": "heading",
"level": 2,
"metadata": {},
"source": [
"Utilities"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"We use the following functions to generate the keyboard shortcut listings above."
"* **Code cells:** Input and output of live code that is run in the kernel\n",
"* **Markdown cells:** Narrative text with embedded LaTeX equations\n",
"* **Heading cells:** 6 levels of hierarchical organization\n",
"* **Heading cells:** 6 levels of hierarchical organization and formatting\n",
"* **Raw cells:** Unformatted text that is included, without modification, when notebooks are converted to different formats using nbconvert\n",
"\n",
"Internally, notebook documents are [JSON](http://en.wikipedia.org/wiki/JSO) data with binary values [base64](http://en.wikipedia.org/wiki/Base64) encoded. This allows them to be read and manipulated programmatically by any programming language. Because JSON is a text format, notebook documents are version control friendly.\n",
Brian E. Granger
12 years ago