Code comments and minor fixes.

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

@@ -1,491 +1,494 b''
 //----------------------------------------------------------------------------
 //  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;
 
     /**
      * 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 optimisation, 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();
         }
     };
 
     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 () {
     };
 
 
     /**
      * 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 === false) {
                 $([IPython.events]).trigger('select.Cell', {'cell':that});
             };
         });
         that.element.focusin(function (event) {
             if (that.selected === false) {
                 $([IPython.events]).trigger('select.Cell', {'cell':that});
             };
         });
         that.element.focusout(function (event) {
             var is_or_has = function (a, b) {
                 // Is b a child of a or a itself?
                 return a.has(b).length !==0 || a.is(b);
             }
             if (that.mode === 'edit') {
+                // Most of the time, when a cell is in edit mode and focusout
+                // fires, it means we should enter command mode. But there are cases
+                // when we should not enter command mode.
                 setTimeout(function () {
                     var trigger = true;
                     var target = $(document.activeElement);
-                    var completer = that.element.find($('div.completions'));
-                    var tooltip = $('div#tooltip')
+                    var completer = $('div.completions');
+                    var tooltip = $('div#tooltip');
                     if (target.length > 0) {
                         // If the focused element (target) is inside the cell
                         // (that.element) don't enter command mode.
                         if (is_or_has(that.element, target)) {
                             trigger = false;
                         // The focused element is outside the cell
                         } else {
                             // If the focused element is the tooltip or completer
                             // don't enter command mode, otherwise do.
                             trigger = true;
                             if (tooltip.length > 0 && is_or_has(tooltip, target)) {
                                 trigger = false;
                             } else if (completer.length > 0 && is_or_has(completer, target)) {
                                 trigger = false;
                             }
                         }
                     }
                     if (trigger) {
                         $([IPython.events]).trigger('command_mode.Cell', {'cell':that});
                     }
                 }, 1);
             };
         });
         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});
             });
         };
     };
 
     /**
      * 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;
         };
     };
 
     /**
      * 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;
         };
     }
 
     /**
      * 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
      * @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
         if( this.user_highlight != undefined &&  this.user_highlight != 'auto' )
         {
             var 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( var mode in modes) {
             var regs = modes[mode]['reg'];
             // only one key every time but regexp can't be keys...
             for(var reg in regs ) {
                 // here we handle non magic_modes
                 if(first_line.match(regs[reg]) != 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));
 

IPython/html/static/notebook/js/completer.js

@@ -1,357 +1,357 b''
 // function completer.
 //
 // completer should be a class that takes an cell instance
 var IPython = (function (IPython) {
     // that will prevent us from misspelling
     "use strict";
 
     // easier key mapping
     var key = IPython.utils.keycodes;
 
     function prepend_n_prc(str, n) {
         for( var i =0 ; i< n ; i++){
             str = '%'+str ;
         }
         return str;
     }
 
     function _existing_completion(item, completion_array){
         for( var c in completion_array ) {
             if(completion_array[c].trim().substr(-item.length) == item)
             { return true; }
         }
        return false;
     }
 
     // what is the common start of all completions
     function shared_start(B, drop_prct) {
         if (B.length == 1) {
             return B[0];
         }
         var A = new Array();
         var common;
         var min_lead_prct = 10;
         for (var i = 0; i < B.length; i++) {
             var str = B[i].str;
             var localmin = 0;
             if(drop_prct === true){
                 while ( str.substr(0, 1) == '%') {
                     localmin = localmin+1;
                     str = str.substring(1);
                 }
             }
             min_lead_prct = Math.min(min_lead_prct, localmin);
             A.push(str);
         }
 
         if (A.length > 1) {
             var tem1, tem2, s;
             A = A.slice(0).sort();
             tem1 = A[0];
             s = tem1.length;
             tem2 = A.pop();
             while (s && tem2.indexOf(tem1) == -1) {
                 tem1 = tem1.substring(0, --s);
             }
             if (tem1 === "" || tem2.indexOf(tem1) !== 0) {
                 return {
                     str:prepend_n_prc('', min_lead_prct),
                     type: "computed",
                     from: B[0].from,
                     to: B[0].to
                     };
             }
             return {
                 str: prepend_n_prc(tem1, min_lead_prct),
                 type: "computed",
                 from: B[0].from,
                 to: B[0].to
             };
         }
         return null;
     }
 
 
     var Completer = function (cell) {
         this.cell = cell;
         this.editor = cell.code_mirror;
         var that = this;
         $([IPython.events]).on('status_busy.Kernel', function () {
             that.skip_kernel_completion = true;
         });
         $([IPython.events]).on('status_idle.Kernel', function () {
             that.skip_kernel_completion = false;
         });
     };
 
 
     Completer.prototype.startCompletion = function () {
         // call for a 'first' completion, that will set the editor and do some
         // special behaviour like autopicking if only one completion availlable
         //
         if (this.editor.somethingSelected()) return;
         this.done = false;
         // use to get focus back on opera
         this.carry_on_completion(true);
     };
 
 
     // easy access for julia to monkeypatch
     //
     Completer.reinvoke_re = /[%0-9a-z._/\\:~-]/i;
 
     Completer.prototype.reinvoke= function(pre_cursor, block, cursor){
         return Completer.reinvoke_re.test(pre_cursor);
     }
 
     /**
      *
      * pass true as parameter if this is the first invocation of the completer
      * this will prevent the completer to dissmiss itself if it is not on a
      * word boundary like pressing tab after a space, and make it autopick the
      * only choice if there is only one which prevent from popping the UI.  as
      * well as fast-forwarding the typing if all completion have a common
      * shared start
      **/
     Completer.prototype.carry_on_completion = function (first_invocation) {
         // Pass true as parameter if you want the completer to autopick when
         // only one completion. This function is automatically reinvoked at
         // each keystroke with first_invocation = false
         var cur = this.editor.getCursor();
         var line = this.editor.getLine(cur.line);
         var pre_cursor = this.editor.getRange({
             line: cur.line,
             ch: cur.ch - 1
         }, cur);
 
         // we need to check that we are still on a word boundary
         // because while typing the completer is still reinvoking itself
         // so dismiss if we are on a "bad" caracter
         if (!this.reinvoke(pre_cursor) && !first_invocation) {
             this.close();
             return;
         }
 
         this.autopick = false;
         if (first_invocation) {
             this.autopick = true;
         }
 
         // We want a single cursor position.
         if (this.editor.somethingSelected()) {
             return;
         };
 
         // one kernel completion came back, finish_completing will be called with the results
         // we fork here and directly call finish completing if kernel is busy
         if (this.skip_kernel_completion == true) {
             this.finish_completing({
                 'matches': [],
                 matched_text: ""
             })
         } else {
             this.cell.kernel.complete(line, cur.ch, $.proxy(this.finish_completing, this));
         }
     };
 
     Completer.prototype.finish_completing = function (msg) {
         // let's build a function that wrap all that stuff into what is needed
         // for the new completer:
         var content = msg.content;
         var matched_text = content.matched_text;
         var matches = content.matches;
 
         var cur = this.editor.getCursor();
         var results = CodeMirror.contextHint(this.editor);
         var filterd_results = Array();
         //remove results from context completion
         //that are already in kernel completion
         for(var elm in results) {
             if(_existing_completion(results[elm]['str'], matches) == false)
             { filterd_results.push(results[elm]); }
         }
 
         // append the introspection result, in order, at at the beginning of
         // the table and compute the replacement range from current cursor
         // positon and matched_text length.
         for (var i = matches.length - 1; i >= 0; --i) {
             filterd_results.unshift({
                 str: matches[i],
                 type: "introspection",
                 from: {
                     line: cur.line,
                     ch: cur.ch - matched_text.length
                 },
                 to: {
                     line: cur.line,
                     ch: cur.ch
                 }
             });
         }
 
         // one the 2 sources results have been merge, deal with it
         this.raw_result = filterd_results;
 
         // if empty result return
         if (!this.raw_result || !this.raw_result.length) return;
 
         // When there is only one completion, use it directly.
         if (this.autopick == true && this.raw_result.length == 1) {
             this.insert(this.raw_result[0]);
             return;
         }
 
         if (this.raw_result.length == 1) {
             // test if first and only completion totally matches
             // what is typed, in this case dismiss
             var str = this.raw_result[0].str;
             var pre_cursor = this.editor.getRange({
                 line: cur.line,
                 ch: cur.ch - str.length
             }, cur);
             if (pre_cursor == str) {
                 this.close();
                 return;
             }
         }
 
         this.complete = $('<div/>').addClass('completions');
         this.complete.attr('id', 'complete');
 
+        // Currently webkit doesn't use the size attr correctly. See:
+        // https://code.google.com/p/chromium/issues/detail?id=4579
         this.sel = $('<select style="width: auto"/>')
             .attr('multiple', 'true')
             .attr('size', Math.min(10, this.raw_result.length));
         this.complete.append(this.sel);
         $('body').append(this.complete);
 
         // After everything is on the page, compute the postion.
         // We put it above the code if it is too close to the bottom of the page.
         var cur = this.editor.getCursor();
         cur.ch = cur.ch-matched_text.length;
         var pos = this.editor.cursorCoords(cur);
         var left = pos.left-3;
         var top;
         var cheight = this.complete.height();
         var wheight = $(window).height();
         if (pos.bottom+cheight+5 > wheight) {
             top = pos.top-cheight-4;
         } else {
             top = pos.bottom+1;
         }
         this.complete.css('left', left + 'px');
         this.complete.css('top', top + 'px');
 
 
         //build the container
         var that = this;
         this.sel.dblclick(function () {
             that.pick();
         });
         this.sel.blur(this.close);
         this.sel.keydown(function (event) {
             that.keydown(event);
         });
 
         this.build_gui_list(this.raw_result);
 
         this.sel.focus();
-        // This needs to be after the focus() call because that puts the notebook into
-        // command mode.
         IPython.keyboard_manager.null_mode();
         // Opera sometimes ignores focusing a freshly created node
         if (window.opera) setTimeout(function () {
             if (!this.done) this.sel.focus();
         }, 100);
         return true;
     }
 
     Completer.prototype.insert = function (completion) {
         this.editor.replaceRange(completion.str, completion.from, completion.to);
     }
 
     Completer.prototype.build_gui_list = function (completions) {
         for (var i = 0; i < completions.length; ++i) {
             var opt = $('<option/>').text(completions[i].str).addClass(completions[i].type);
             this.sel.append(opt);
         }
         this.sel.children().first().attr('selected', 'true');
         this.sel.scrollTop(0);
     }
 
     Completer.prototype.close = function () {
         if (this.done) return;
         this.done = true;
         $('.completions').remove();
         IPython.keyboard_manager.edit_mode();
     }
 
     Completer.prototype.pick = function () {
         this.insert(this.raw_result[this.sel[0].selectedIndex]);
         this.close();
         var that = this;
         setTimeout(function () {
             that.editor.focus();
         }, 50);
     }
 
 
     Completer.prototype.keydown = function (event) {
         var code = event.keyCode;
         var that = this;
         var special_key = false;
 
         // detect special keys like SHIFT,PGUP,...
         for( var _key in key ) {
             if (code == key[_key] ) {
                 special_key = true;
             }
         };
 
         // Enter
         if (code == key.ENTER) {
             CodeMirror.e_stop(event);
             this.pick();
         }
         // Escape or backspace
         else if (code == key.ESC) {
             CodeMirror.e_stop(event);
             this.close();
             this.editor.focus();
         } else if (code == key.SPACE || code == key.BACKSPACE) {
             this.close();
             this.editor.focus();
         } else if (code == key.TAB) {
             //all the fastforwarding operation,
             //Check that shared start is not null which can append with prefixed completion
             // like %pylab , pylab have no shred start, and ff will result in py<tab><tab>
             // to erase py
             var sh = shared_start(this.raw_result, true);
             if (sh) {
                 this.insert(sh);
             }
             this.close();
             CodeMirror.e_stop(event);
             this.editor.focus();
             //reinvoke self
             setTimeout(function () {
                 that.carry_on_completion();
             }, 50);
         } else if (code == key.UPARROW || code == key.DOWNARROW) {
             // need to do that to be able to move the arrow
             // when on the first or last line ofo a code cell
             event.stopPropagation();
         } else if (special_key != true) {
             this.close();
             this.editor.focus();
             //we give focus to the editor immediately and call sell in 50 ms
             setTimeout(function () {
                 that.carry_on_completion();
             }, 50);
         }
     }
 
 
     IPython.Completer = Completer;
 
     return IPython;
 }(IPython));