-
Notifications
You must be signed in to change notification settings - Fork 806
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #440 from jcb91/usability/keyboard_shortcut_editor
Add keyboard_shortcut_editor extension
- Loading branch information
Showing
17 changed files
with
1,531 additions
and
0 deletions.
There are no files selected for viewing
131 changes: 131 additions & 0 deletions
131
nbextensions/usability/keyboard_shortcut_editor/README.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,131 @@ | ||
Copyright © 2015 IPython-Contrib Team. | ||
Distributed under the terms of the Modified BSD License. | ||
|
||
This extension allows you to edit or remove the default notebook keyboard | ||
shortcuts, or create your own new ones. | ||
|
||
Currently, this extension supports the editing of any shortcut provided by | ||
Jupyter, with the exception of those provided by the CodeMirror editors, since | ||
they use a different API. | ||
|
||
To edit your keyboard shortcuts, open the keyboard shortcuts help dialog, | ||
either by pressing <kbd>h</kbd> in command mode, or by selecting | ||
`help > keyboard shortcuts` from the menu: | ||
|
||
![keyboard shortcuts menu item](readme_menu_item.png) | ||
|
||
When the extension has been loaded, each shortcut in the dialog will show a | ||
small dropdown menu next to it, with items to remove or edit the shortcut: | ||
|
||
![keyboard shortcut edit dropdown](readme_dropdown.png) | ||
|
||
Clicking the edit item opens a second modal dialog, with a text input. While | ||
the input has focus, you can press keys to form your combination. The reset | ||
button (the curly arrow to the left hand side) allows you to clear any keys you | ||
may input accidentally. | ||
|
||
![the shortcut editor dialog](readme_shortcut_editor_blank.png) | ||
![the shortcut editor dialog](readme_shortcut_editor_success.png) | ||
|
||
If you'd like to disable an existing shortcut, you can click the 'Disable' | ||
button on the dropdown. This will move the shortcut into a new section on the | ||
dialog headed 'disabled'. You can click the reset button next to disabled | ||
shortcuts to re-enable them: | ||
|
||
![re-enabling a disabled shortcut](readme_reset_disabled.png) | ||
|
||
You can create new custom keyboard shortcuts using the link at the base of the | ||
shortcut list for each mode: | ||
|
||
![add a new keyboard shortcut](readme_add_new_link.png) | ||
|
||
This opens a dialog similar to the editor, with the addition of a select box | ||
from which you can select the action which will be called: | ||
|
||
![selecting an action for a new keyboard shortcut](readme_add_new_select_action.png) | ||
|
||
|
||
Limitations: problem shortcuts | ||
============================== | ||
|
||
Since this editor uses the same key-identification method as the notebook, | ||
anything you can get it to recognise should (?!) work as a notebook shortcut, | ||
even if it gets represented by the editor differently to the letters on your | ||
actual, physical, keyboard. However, bear in mind that key identification is | ||
not perfect, (this is a problem on the web in general), so it's possible that | ||
some combinations may not be identified by Jupyter at all. In such cases, the | ||
editor should notify you: | ||
|
||
![an unrecognised keypress](readme_undefined_key.png) | ||
|
||
In addition, the handling of shortcuts including commas is currently | ||
compromised to the extent that they don't really work properly, so the editor | ||
also won't accept anything with a comma in it: | ||
|
||
![commas don't work properly!](readme_comma.png) | ||
|
||
The dialog will also not accept a shortcut that would conflict with one which | ||
already exists: | ||
|
||
![conflicting keyboard shortcuts are not accepted](readme_conflict.png) | ||
|
||
If the conflicting shortcut is provided by Jupyter rather than CodeMirror, you | ||
can of course disable it to prevent the conflict occurring. | ||
|
||
|
||
Internals | ||
========= | ||
|
||
The extension stores a record of the edits in use in the config, as a list | ||
of objects for each mode. Those without a `to` key denote shortcuts to disable, | ||
while those without a `from` key denote new shortcuts. For example: | ||
|
||
```json | ||
// the config object with section name 'notebook' at the base URL | ||
{ | ||
... | ||
"kse_rebinds": { | ||
// command-mode rebindings | ||
'command': [ | ||
{ // disable the default 'space' shortcut, which used to scroll the notebook down | ||
from: "space", | ||
action_name: "jupyter-notebook:scroll-notebook-down" | ||
}, | ||
{ // create a new shortcut 't,t' to trust the notebook | ||
action_name: "jupyter-notebook:trust-notebook", | ||
to: "t,t" | ||
}, | ||
{ // change the default save-notebook shortcut from 's' to 'shift-s' | ||
action_name: "jupyter-notebook:save-notebook", | ||
to: "shift-s", | ||
from: "s" | ||
} | ||
], | ||
// edit-mode rebindings: | ||
"edit": [ | ||
{ // disable the default edit-mode binding which switches to command mode | ||
action_name: "jupyter-notebook:enter-command-mode", | ||
from: "ctrl-m" | ||
} | ||
] | ||
}, | ||
... | ||
} | ||
``` | ||
|
||
The extension applies the shortcut edits when it is loaded, and in addition to | ||
any shortcut registered subsequently, as detailed below. | ||
|
||
|
||
Patches | ||
------- | ||
|
||
The extension applies patches to two Jupyter class prototypes. | ||
The method `ShortcutManager.prototype.add_shortcut` from `base/js/keyboard`, | ||
is patched to ensure any appropriate edits are applied to any shortcuts which | ||
get registered after the extension is loaded, for example by other notebook | ||
extensions. | ||
|
||
The `QuickHelp.prototype.build_command_help` and | ||
`QuickHelp.prototype.build_edit_help` methods from `notebook/js/quickhelp`, are | ||
patched to insert the dropdown menus, disabled shortcuts and other links. |
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
7 changes: 7 additions & 0 deletions
7
nbextensions/usability/keyboard_shortcut_editor/keyboard_shortcut_editor.yaml
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
Type: IPython Notebook Extension | ||
Compatibility: 4.x | ||
Name: Keyboard shortcut editor | ||
Main: main.js | ||
Icon: icon.png | ||
Link: README.md | ||
Description: Edit or remove Jupyter keyboard shortcuts, or add you own new ones |
Oops, something went wrong.