renamed 'use_shortcut' method to 'handles'

IPython/html/static/base/js/keyboard.js

@@ -1,257 +1,257
 //----------------------------------------------------------------------------
 //  Copyright (C) 2011  The IPython Development Team
 //
 //  Distributed under the terms of the BSD License.  The full license is in
 //  the file COPYING, distributed as part of this software.
 //----------------------------------------------------------------------------
 
 //============================================================================
 // Keyboard management
 //============================================================================
 
 IPython.namespace('IPython.keyboard');
 
 IPython.keyboard = (function (IPython) {
     "use strict";
 
     // Setup global keycodes and inverse keycodes.
 
     // See http://unixpapa.com/js/key.html for a complete description. The short of
     // it is that there are different keycode sets. Firefox uses the "Mozilla keycodes"
     // and Webkit/IE use the "IE keycodes". These keycode sets are mostly the same
     // but have minor differences.
 
     // These apply to Firefox, (Webkit and IE)
     var _keycodes = {
         'a': 65, 'b': 66, 'c': 67, 'd': 68, 'e': 69, 'f': 70, 'g': 71, 'h': 72, 'i': 73,
         'j': 74, 'k': 75, 'l': 76, 'm': 77, 'n': 78, 'o': 79, 'p': 80, 'q': 81, 'r': 82,
         's': 83, 't': 84, 'u': 85, 'v': 86, 'w': 87, 'x': 88, 'y': 89, 'z': 90,
         '1 !': 49, '2 @': 50, '3 #': 51, '4 $': 52, '5 %': 53, '6 ^': 54,
         '7 &': 55, '8 *': 56, '9 (': 57, '0 )': 48, 
         '[ {': 219, '] }': 221, '` ~': 192,  ', <': 188, '. >': 190, '/ ?': 191,
         '\\ |': 220, '\' "': 222,
         'numpad0': 96, 'numpad1': 97, 'numpad2': 98, 'numpad3': 99, 'numpad4': 100,
         'numpad5': 101, 'numpad6': 102, 'numpad7': 103, 'numpad8': 104, 'numpad9': 105,
         'multiply': 106, 'add': 107, 'subtract': 109, 'decimal': 110, 'divide': 111,
         'f1': 112, 'f2': 113, 'f3': 114, 'f4': 115, 'f5': 116, 'f6': 117, 'f7': 118,
         'f8': 119, 'f9': 120, 'f11': 122, 'f12': 123, 'f13': 124, 'f14': 125, 'f15': 126,
         'backspace': 8, 'tab': 9, 'enter': 13, 'shift': 16, 'ctrl': 17, 'alt': 18,
         'meta': 91, 'capslock': 20, 'esc': 27, 'space': 32, 'pageup': 33, 'pagedown': 34,
         'end': 35, 'home': 36, 'left': 37, 'up': 38, 'right': 39, 'down': 40,
         'insert': 45, 'delete': 46, 'numlock': 144,
     };
     
     // These apply to Firefox and Opera
     var _mozilla_keycodes = {
         '; :': 59, '= +': 61, '- _': 173, 'meta': 224
     }
     
     // This apply to Webkit and IE
     var _ie_keycodes = {
         '; :': 186, '= +': 187, '- _': 189, 
     }
     
     var browser = IPython.utils.browser[0];
     var platform = IPython.utils.platform;
     
     if (browser === 'Firefox' || browser === 'Opera') {
         $.extend(_keycodes, _mozilla_keycodes);
     } else if (browser === 'Safari' || browser === 'Chrome' || browser === 'MSIE') {
         $.extend(_keycodes, _ie_keycodes);
     }
 
     var keycodes = {};
     var inv_keycodes = {};
     for (var name in _keycodes) {
         var names = name.split(' ');
         if (names.length === 1) {
             var n = names[0]
             keycodes[n] = _keycodes[n]
             inv_keycodes[_keycodes[n]] = n
         } else {
             var primary = names[0];
             var secondary = names[1];
             keycodes[primary] = _keycodes[name]
             keycodes[secondary] = _keycodes[name]
             inv_keycodes[_keycodes[name]] = primary
         }
     }
 
     var normalize_key = function (key) {
         return inv_keycodes[keycodes[key]];
     }
 
     var normalize_shortcut = function (shortcut) {
         // Put a shortcut into normalized form:
         // 1. Make lowercase
         // 2. Replace cmd by meta
         // 3. Sort '+' separated modifiers into the order alt+ctrl+meta+shift
         // 4. Normalize keys
         shortcut = shortcut.toLowerCase().replace('cmd', 'meta');
         var values = shortcut.split("+");
         if (values.length === 1) {
             return normalize_key(values[0])
         } else {
             var modifiers = values.slice(0,-1);
             var key = normalize_key(values[values.length-1]);
             modifiers.sort();
             return modifiers.join('+') + '+' + key;
         }
     }
 
     var shortcut_to_event = function (shortcut, type) {
         // Convert a shortcut (shift+r) to a jQuery Event object
         type = type || 'keydown';
         shortcut = normalize_shortcut(shortcut);
         var values = shortcut.split("+");
         var modifiers = values.slice(0,-1);
         var key = values[values.length-1];
         var opts = {which: keycodes[key]};
         if (modifiers.indexOf('alt') !== -1) {opts.altKey = true;}
         if (modifiers.indexOf('ctrl') !== -1) {opts.ctrlKey = true;}
         if (modifiers.indexOf('meta') !== -1) {opts.metaKey = true;}
         if (modifiers.indexOf('shift') !== -1) {opts.shiftKey = true;}
         return $.Event(type, opts);
     }
 
     var event_to_shortcut = function (event) {
         // Convert a jQuery Event object to a shortcut (shift+r)
         var shortcut = '';
         var key = inv_keycodes[event.which]
         if (event.altKey && key !== 'alt') {shortcut += 'alt+';}
         if (event.ctrlKey && key !== 'ctrl') {shortcut += 'ctrl+';}
         if (event.metaKey && key !== 'meta') {shortcut += 'meta+';}
         if (event.shiftKey && key !== 'shift') {shortcut += 'shift+';}
         shortcut += key;
         return shortcut
     }
 
     var trigger_keydown = function (shortcut, element) {
         // Trigger shortcut keydown on an element
         element = element || document;
         element = $(element);
         var event = shortcut_to_event(shortcut, 'keydown');
         element.trigger(event);
     }
 
 
     // Shortcut manager class
 
     var ShortcutManager = function (delay) {
         this._shortcuts = {}
         this._counts = {}
         this._timers = {}
         this.delay = delay || 800; // delay in milliseconds
     }
 
     ShortcutManager.prototype.help = function () {
         var help = [];
         for (var shortcut in this._shortcuts) {
             var help_string = this._shortcuts[shortcut]['help'];
             var help_index = this._shortcuts[shortcut]['help_index'];
             if (help_string) {
                 if (platform === 'MacOS') {
                     shortcut = shortcut.replace('meta', 'cmd');
                 }
                 help.push({
                     shortcut: shortcut,
                     help: help_string,
                     help_index: help_index}
                 );
             }
         }
         help.sort(function (a, b) {
             if (a.help_index > b.help_index)
                 return 1;
             if (a.help_index < b.help_index)
                 return -1;
             return 0;
         });
         return help;
     }
 
     ShortcutManager.prototype.clear_shortcuts = function () {
         this._shortcuts = {};
     }
 
     ShortcutManager.prototype.add_shortcut = function (shortcut, data) {
         if (typeof(data) === 'function') {
             data = {help: '', help_index: '', handler: data}
         }
         data.help_index = data.help_index || '';
         data.help = data.help || '';
         data.count = data.count || 1;
         if (data.help_index === '') {
             data.help_index = 'zz';
         }
         shortcut = normalize_shortcut(shortcut);
         this._counts[shortcut] = 0;
         this._shortcuts[shortcut] = data;
     }
 
     ShortcutManager.prototype.add_shortcuts = function (data) {
         for (var shortcut in data) {
             this.add_shortcut(shortcut, data[shortcut]);
         }
     }
 
     ShortcutManager.prototype.remove_shortcut = function (shortcut) {
         shortcut = normalize_shortcut(shortcut);
         delete this._counts[shortcut];
         delete this._shortcuts[shortcut];
     }
 
     ShortcutManager.prototype.count_handler = function (shortcut, event, data) {
         var that = this;
         var c = this._counts;
         var t = this._timers;
         var timer = null;
         if (c[shortcut] === data.count-1) {
             c[shortcut] = 0;
             var timer = t[shortcut];
             if (timer) {clearTimeout(timer); delete t[shortcut];}
             return data.handler(event);
         } else {
             c[shortcut] = c[shortcut] + 1;
             timer = setTimeout(function () {
                 c[shortcut] = 0;
             }, that.delay);
             t[shortcut] = timer;
         }
         return false;
     }
 
     ShortcutManager.prototype.call_handler = function (event) {
         var shortcut = event_to_shortcut(event);
         var data = this._shortcuts[shortcut];
         if (data) {
             var handler = data['handler'];
             if (handler) {
                 if (data.count === 1) {
                     return handler(event);
                 } else if (data.count > 1) {
                     return this.count_handler(shortcut, event, data);
                 }
             }
         }
         return true;
     }
 
-    ShortcutManager.prototype.use_shortcut = function (event) {
+    ShortcutManager.prototype.handles = function (event) {
         var shortcut = event_to_shortcut(event);
         var data = this._shortcuts[shortcut];
         return !( data === undefined )
     }
 
     return {
         keycodes : keycodes,
         inv_keycodes : inv_keycodes,
         ShortcutManager : ShortcutManager,
         normalize_key : normalize_key,
         normalize_shortcut : normalize_shortcut,
         shortcut_to_event : shortcut_to_event,
         event_to_shortcut : event_to_shortcut,
         trigger_keydown : trigger_keydown
     }
 
 }(IPython));

IPython/html/static/notebook/js/cell.js

@@ -1,567 +1,567
 //----------------------------------------------------------------------------
 //  Copyright (C) 2008-2011  The IPython Development Team
 //
 //  Distributed under the terms of the BSD License.  The full license is in
 //  the file COPYING, distributed as part of this software.
 //----------------------------------------------------------------------------
 
 //============================================================================
 // Cell
 //============================================================================
 /**
  * An extendable module that provide base functionnality to create cell for notebook.
  * @module IPython
  * @namespace IPython
  * @submodule Cell
  */
 
 var IPython = (function (IPython) {
     "use strict";
 
     var utils = IPython.utils;
     var keycodes = IPython.keyboard.keycodes;
 
     /**
      * The Base `Cell` class from which to inherit
      * @class Cell
      **/
 
     /*
      * @constructor
      *
      * @param {object|undefined} [options]
      *     @param [options.cm_config] {object} config to pass to CodeMirror, will extend default parameters
      */
     var Cell = function (options) {
 
         options = this.mergeopt(Cell, options);
         // superclass default overwrite our default
         
         this.placeholder = options.placeholder || '';
         this.read_only = options.cm_config.readOnly;
         this.selected = false;
         this.rendered = false;
         this.mode = 'command';
         this.metadata = {};
         // load this from metadata later ?
         this.user_highlight = 'auto';
         this.cm_config = options.cm_config;
         this.cell_id = utils.uuid();
         this._options = options;
 
         // For JS VM engines optimization, attributes should be all set (even
         // to null) in the constructor, and if possible, if different subclass
         // have new attributes with same name, they should be created in the
         // same order. Easiest is to create and set to null in parent class.
 
         this.element = null;
         this.cell_type = this.cell_type || null;
         this.code_mirror = null;
 
         this.create_element();
         if (this.element !== null) {
             this.element.data("cell", this);
             this.bind_events();
             this.init_classes();
         }
     };
 
     Cell.options_default = {
         cm_config : {
             indentUnit : 4,
             readOnly: false,
             theme: "default"
         }
     };
     
     // FIXME: Workaround CM Bug #332 (Safari segfault on drag)
     // by disabling drag/drop altogether on Safari
     // https://github.com/marijnh/CodeMirror/issues/332    
     if (utils.browser[0] == "Safari") {
         Cell.options_default.cm_config.dragDrop = false;
     }
 
     Cell.prototype.mergeopt = function(_class, options, overwrite){
         options = options || {};
         overwrite = overwrite || {};
         return $.extend(true, {}, _class.options_default, options, overwrite);
     };
 
     /**
      * Empty. Subclasses must implement create_element.
      * This should contain all the code to create the DOM element in notebook
      * and will be called by Base Class constructor.
      * @method create_element
      */
     Cell.prototype.create_element = function () {
     };
 
     Cell.prototype.init_classes = function () {
         // Call after this.element exists to initialize the css classes
         // related to selected, rendered and mode.
         if (this.selected) {
             this.element.addClass('selected');
         } else {
             this.element.addClass('unselected');
         }
         if (this.rendered) {
             this.element.addClass('rendered');
         } else {
             this.element.addClass('unrendered');
         }
         if (this.mode === 'edit') {
             this.element.addClass('edit_mode');
         } else {
             this.element.addClass('command_mode');
         }
     };
 
     /**
      * Subclasses can implement override bind_events.
      * Be carefull to call the parent method when overwriting as it fires event.
      * this will be triggerd after create_element in constructor.
      * @method bind_events
      */
     Cell.prototype.bind_events = function () {
         var that = this;
         // We trigger events so that Cell doesn't have to depend on Notebook.
         that.element.click(function (event) {
             if (!that.selected) {
                 $([IPython.events]).trigger('select.Cell', {'cell':that});
             }
         });
         that.element.focusin(function (event) {
             if (!that.selected) {
                 $([IPython.events]).trigger('select.Cell', {'cell':that});
             }
         });
         if (this.code_mirror) {
             this.code_mirror.on("change", function(cm, change) {
                 $([IPython.events]).trigger("set_dirty.Notebook", {value: true});
             });
         }
         if (this.code_mirror) {
             this.code_mirror.on('focus', function(cm, change) {
                 $([IPython.events]).trigger('edit_mode.Cell', {cell: that});
             });
         }
         if (this.code_mirror) {
             this.code_mirror.on('blur', function(cm, change) {
                 // Check if this unfocus event is legit.
                 if (!that.should_cancel_blur()) {
                     $([IPython.events]).trigger('command_mode.Cell', {cell: that});
                 }
             });
         }
     };
     
     /**
      * This method gets called in CodeMirror's onKeyDown/onKeyPress
      * handlers and is used to provide custom key handling.
      *
      * To have custom handling, subclasses should override this method, but still call it
      * in order to process the Edit mode keyboard shortcuts.
      *
      * @method handle_codemirror_keyevent
      * @param {CodeMirror} editor - The codemirror instance bound to the cell
      * @param {event} event - key press event which either should or should not be handled by CodeMirror
      * @return {Boolean} `true` if CodeMirror should ignore the event, `false` Otherwise
      */
     Cell.prototype.handle_codemirror_keyevent = function (editor, event) {
         var that = this;
         var shortcuts = IPython.keyboard_manager.edit_shortcuts;
 
         // if this is an edit_shortcuts shortcut, the global keyboard/shortcut
         // manager will handle it
-        if (shortcuts.use_shortcut(event)) { return true; }
+        if (shortcuts.handles(event)) { return true; }
         
         return false;
     };
 
 
     /**
      * Triger typsetting of math by mathjax on current cell element
      * @method typeset
      */
     Cell.prototype.typeset = function () {
         if (window.MathJax) {
             var cell_math = this.element.get(0);
             MathJax.Hub.Queue(["Typeset", MathJax.Hub, cell_math]);
         }
     };
 
     /**
      * handle cell level logic when a cell is selected
      * @method select
      * @return is the action being taken
      */
     Cell.prototype.select = function () {
         if (!this.selected) {
             this.element.addClass('selected');
             this.element.removeClass('unselected');
             this.selected = true;
             return true;
         } else {
             return false;
         }
     };
 
     /**
      * handle cell level logic when a cell is unselected
      * @method unselect
      * @return is the action being taken
      */
     Cell.prototype.unselect = function () {
         if (this.selected) {
             this.element.addClass('unselected');
             this.element.removeClass('selected');
             this.selected = false;
             return true;
         } else {
             return false;
         }
     };
 
     /**
      * handle cell level logic when a cell is rendered
      * @method render
      * @return is the action being taken
      */
     Cell.prototype.render = function () {
         if (!this.rendered) {
             this.element.addClass('rendered');
             this.element.removeClass('unrendered');
             this.rendered = true;
             return true;
         } else {
             return false;
         }
     };
 
     /**
      * handle cell level logic when a cell is unrendered
      * @method unrender
      * @return is the action being taken
      */
     Cell.prototype.unrender = function () {
         if (this.rendered) {
             this.element.addClass('unrendered');
             this.element.removeClass('rendered');
             this.rendered = false;
             return true;
         } else {
             return false;
         }
     };
 
     /**
      * Delegates keyboard shortcut handling to either IPython keyboard
      * manager when in command mode, or CodeMirror when in edit mode
      *
      * @method handle_keyevent
      * @param {CodeMirror} editor - The codemirror instance bound to the cell
      * @param {event} event -
      * @return {Boolean} `true` if CodeMirror should ignore the event, `false` Otherwise
      */
     Cell.prototype.handle_keyevent = function (editor, event) {
 
         // console.log('CM', this.mode, event.which, event.type)
 
         if (this.mode === 'command') {
             return true;
         } else if (this.mode === 'edit') {
             return this.handle_codemirror_keyevent(editor, event);
         }
     };
 
     /**
      * @method at_top
      * @return {Boolean}
      */
     Cell.prototype.at_top = function () {
         var cm = this.code_mirror;
         var cursor = cm.getCursor();
         if (cursor.line === 0 && cm.findPosV(cursor, -1, 'line').hitSide) {
             return true;
         } else {
             return false;
         }
     };
 
     /**
      * @method at_bottom
      * @return {Boolean}
      * */
     Cell.prototype.at_bottom = function () {
         var cm = this.code_mirror;
         var cursor = cm.getCursor();
         if (cursor.line === (cm.lineCount()-1) && cm.findPosV(cursor, 1, 'line').hitSide) {
             return true;
         } else {
             return false;
         }
     };
     /**
      * enter the command mode for the cell
      * @method command_mode
      * @return is the action being taken
      */
     Cell.prototype.command_mode = function () {
         if (this.mode !== 'command') {
             this.element.addClass('command_mode');
             this.element.removeClass('edit_mode');
             this.mode = 'command';
             return true;
         } else {
             return false;
         }
     };
 
     /**
      * enter the edit mode for the cell
      * @method command_mode
      * @return is the action being taken
      */
     Cell.prototype.edit_mode = function () {
         if (this.mode !== 'edit') {
             this.element.addClass('edit_mode');
             this.element.removeClass('command_mode');
             this.mode = 'edit';
             return true;
         } else {
             return false;
         }
     };
 
     /**
      * Determine whether or not the unfocus event should be aknowledged.
      *
      * @method should_cancel_blur
      *
      * @return results {bool} Whether or not to ignore the cell's blur event.
      **/
     Cell.prototype.should_cancel_blur = function () {
         return false;
     };
 
     /**
      * Focus the cell in the DOM sense
      * @method focus_cell
      */
     Cell.prototype.focus_cell = function () {
         this.element.focus();
     };
 
     /**
      * Focus the editor area so a user can type
      *
      * NOTE: If codemirror is focused via a mouse click event, you don't want to
      * call this because it will cause a page jump.
      * @method focus_editor
      */
     Cell.prototype.focus_editor = function () {
         this.refresh();
         this.code_mirror.focus();
     };
 
     /**
      * Refresh codemirror instance
      * @method refresh
      */
     Cell.prototype.refresh = function () {
         this.code_mirror.refresh();
     };
 
     /**
      * should be overritten by subclass
      * @method get_text
      */
     Cell.prototype.get_text = function () {
     };
 
     /**
      * should be overritten by subclass
      * @method set_text
      * @param {string} text
      */
     Cell.prototype.set_text = function (text) {
     };
 
     /**
      * should be overritten by subclass
      * serialise cell to json.
      * @method toJSON
      **/
     Cell.prototype.toJSON = function () {
         var data = {};
         data.metadata = this.metadata;
         data.cell_type = this.cell_type;
         return data;
     };
 
 
     /**
      * should be overritten by subclass
      * @method fromJSON
      **/
     Cell.prototype.fromJSON = function (data) {
         if (data.metadata !== undefined) {
             this.metadata = data.metadata;
         }
         this.celltoolbar.rebuild();
     };
 
 
     /**
      * can the cell be split into two cells
      * @method is_splittable
      **/
     Cell.prototype.is_splittable = function () {
         return true;
     };
 
 
     /**
      * can the cell be merged with other cells
      * @method is_mergeable
      **/
     Cell.prototype.is_mergeable = function () {
         return true;
     };
 
 
     /**
      * @return {String} - the text before the cursor
      * @method get_pre_cursor
      **/
     Cell.prototype.get_pre_cursor = function () {
         var cursor = this.code_mirror.getCursor();
         var text = this.code_mirror.getRange({line:0, ch:0}, cursor);
         text = text.replace(/^\n+/, '').replace(/\n+$/, '');
         return text;
     };
 
 
     /**
      * @return {String} - the text after the cursor
      * @method get_post_cursor
      **/
     Cell.prototype.get_post_cursor = function () {
         var cursor = this.code_mirror.getCursor();
         var last_line_num = this.code_mirror.lineCount()-1;
         var last_line_len = this.code_mirror.getLine(last_line_num).length;
         var end = {line:last_line_num, ch:last_line_len};
         var text = this.code_mirror.getRange(cursor, end);
         text = text.replace(/^\n+/, '').replace(/\n+$/, '');
         return text;
     };
 
     /**
      * Show/Hide CodeMirror LineNumber
      * @method show_line_numbers
      *
      * @param value {Bool}  show (true), or hide (false) the line number in CodeMirror
      **/
     Cell.prototype.show_line_numbers = function (value) {
         this.code_mirror.setOption('lineNumbers', value);
         this.code_mirror.refresh();
     };
 
     /**
      * Toggle  CodeMirror LineNumber
      * @method toggle_line_numbers
      **/
     Cell.prototype.toggle_line_numbers = function () {
         var val = this.code_mirror.getOption('lineNumbers');
         this.show_line_numbers(!val);
     };
 
     /**
      * Force codemirror highlight mode
      * @method force_highlight
      * @param {object} - CodeMirror mode
      **/
     Cell.prototype.force_highlight = function(mode) {
         this.user_highlight = mode;
         this.auto_highlight();
     };
 
     /**
      * Try to autodetect cell highlight mode, or use selected mode
      * @methods _auto_highlight
      * @private
      * @param {String|object|undefined} - CodeMirror mode | 'auto'
      **/
     Cell.prototype._auto_highlight = function (modes) {
         //Here we handle manually selected modes
         var mode;
         if( this.user_highlight !== undefined &&  this.user_highlight != 'auto' )
         {
             mode = this.user_highlight;
             CodeMirror.autoLoadMode(this.code_mirror, mode);
             this.code_mirror.setOption('mode', mode);
             return;
         }
         var current_mode = this.code_mirror.getOption('mode', mode);
         var first_line = this.code_mirror.getLine(0);
         // loop on every pairs
         for(mode in modes) {
             var regs = modes[mode].reg;
             // only one key every time but regexp can't be keys...
             for(var i=0; i<regs.length; i++) {
                 // here we handle non magic_modes
                 if(first_line.match(regs[i]) !== null) {
                     if(current_mode == mode){
                         return;
                     }
                     if (mode.search('magic_') !== 0) {
                         this.code_mirror.setOption('mode', mode);
                         CodeMirror.autoLoadMode(this.code_mirror, mode);
                         return;
                     }
                     var open = modes[mode].open || "%%";
                     var close = modes[mode].close || "%%end";
                     var mmode = mode;
                     mode = mmode.substr(6);
                     if(current_mode == mode){
                         return;
                     }
                     CodeMirror.autoLoadMode(this.code_mirror, mode);
                     // create on the fly a mode that swhitch between
                     // plain/text and smth else otherwise `%%` is
                     // source of some highlight issues.
                     // we use patchedGetMode to circumvent a bug in CM
                     CodeMirror.defineMode(mmode , function(config) {
                         return CodeMirror.multiplexingMode(
                         CodeMirror.patchedGetMode(config, 'text/plain'),
                             // always set someting on close
                             {open: open, close: close,
                              mode: CodeMirror.patchedGetMode(config, mode),
                              delimStyle: "delimit"
                             }
                         );
                     });
                     this.code_mirror.setOption('mode', mmode);
                     return;
                 }
             }
         }
         // fallback on default
         var default_mode;
         try {
             default_mode = this._options.cm_config.mode;
         } catch(e) {
             default_mode = 'text/plain';
         }
         if( current_mode === default_mode){
             return;
         }
         this.code_mirror.setOption('mode', default_mode);
     };
 
     IPython.Cell = Cell;
 
     return IPython;
 
 }(IPython));