start to document js

IPython/frontend/html/notebook/static/js/textcell.js

@@ -1,417 +1,487 b''
 //----------------------------------------------------------------------------
 //  Copyright (C) 2008-2012  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.
 //----------------------------------------------------------------------------
 
 //============================================================================
 // TextCell
 //============================================================================
 
+/**
+    A module that allow to create different type of Text Cell
+ */
 var IPython = (function (IPython) {
 
     // TextCell base class
     var key = IPython.utils.keycodes;
 
+    /**
+     * @class TextCell
+     * @constructs TextCell
+     */
     var TextCell = function () {
         this.code_mirror_mode = this.code_mirror_mode || 'htmlmixed';
         IPython.Cell.apply(this, arguments);
         this.rendered = false;
         this.cell_type = this.cell_type || 'text';
     };
 
-
     TextCell.prototype = new IPython.Cell();
 
-
+    /** create the DOM element of the TextCell
+     * @method create_element
+     * @private
+     */
     TextCell.prototype.create_element = function () {
         var cell = $("<div>").addClass('cell text_cell border-box-sizing');
         cell.attr('tabindex','2');
         var input_area = $('<div/>').addClass('text_cell_input border-box-sizing');
         this.code_mirror = CodeMirror(input_area.get(0), {
             indentUnit : 4,
             mode: this.code_mirror_mode,
             theme: 'default',
             value: this.placeholder,
             readOnly: this.read_only,
             lineWrapping : true,
             extraKeys: {"Tab": "indentMore","Shift-Tab" : "indentLess"},
             onKeyEvent: $.proxy(this.handle_codemirror_keyevent,this)
         });
         // The tabindex=-1 makes this div focusable.
         var render_area = $('<div/>').addClass('text_cell_render border-box-sizing').
             addClass('rendered_html').attr('tabindex','-1');
         cell.append(input_area).append(render_area);
         this.element = cell;
     };
 
 
+    /** bind the DOM evet to cell actions
+     * Need to be called after TextCell.create_element
+     * @private
+     * @method bind_event
+     */
     TextCell.prototype.bind_events = function () {
         IPython.Cell.prototype.bind_events.apply(this);
         var that = this;
         this.element.keydown(function (event) {
             if (event.which === 13 && !event.shiftKey) {
                 if (that.rendered) {
                     that.edit();
                     return false;
                 };
             };
         });
         this.element.dblclick(function () {
             that.edit();
         });
     };
 
-
+    /** This method gets called in CodeMirror's onKeyDown/onKeyPress
+     * handlers and is used to provide custom key handling.
+     *
+     * @method handle_codemirror_keyevent
+     * @param {CodeMirror } editor - The codemirror instance bound to the cell
+     * @param {event} event -
+     * @return {Boolean} <tt>true</tt> if CodeMirror should ignore the event, `false` Otherwise
+     */
     TextCell.prototype.handle_codemirror_keyevent = function (editor, event) {
-        // This method gets called in CodeMirror's onKeyDown/onKeyPress
-        // handlers and is used to provide custom key handling. Its return
-        // value is used to determine if CodeMirror should ignore the event:
-        // true = ignore, false = don't ignore.
-        
+
         if (event.keyCode === 13 && (event.shiftKey || event.ctrlKey)) {
             // Always ignore shift-enter in CodeMirror as we handle it.
             return true;
         }
         return false;
     };
 
-
+    /**
+     * Select the current cell
+     * @method select
+     */
     TextCell.prototype.select = function () {
         IPython.Cell.prototype.select.apply(this);
         var output = this.element.find("div.text_cell_render");
         output.trigger('focus');
     };
 
-
+    /** unselect the current cell
+     * @method unselect
+     */
     TextCell.prototype.unselect = function() {
         // render on selection of another cell
         this.render();
         IPython.Cell.prototype.unselect.apply(this);
     };
 
-
+    /** put the current cell in edition mode
+     * @method edit
+     */
     TextCell.prototype.edit = function () {
         if ( this.read_only ) return;
         if (this.rendered === true) {
             var text_cell = this.element;
-            var output = text_cell.find("div.text_cell_render");  
+            var output = text_cell.find("div.text_cell_render");
             output.hide();
             text_cell.find('div.text_cell_input').show();
             this.code_mirror.refresh();
             this.code_mirror.focus();
             // We used to need an additional refresh() after the focus, but
             // it appears that this has been fixed in CM. This bug would show
             // up on FF when a newly loaded markdown cell was edited.
             this.rendered = false;
             if (this.get_text() === this.placeholder) {
                 this.set_text('');
                 this.refresh();
             }
         }
     };
 
 
-    // Subclasses must define render.
+    /** Subclasses must define render.
+     * @method render
+     */
     TextCell.prototype.render = function () {};
 
 
+    /**
+     * setter: {{#crossLink "TextCell/set_text"}}{{/crossLink}}
+     * @method get_text
+     * @retrun {string} CodeMirror current text value
+     */
     TextCell.prototype.get_text = function() {
         return this.code_mirror.getValue();
     };
 
-
+    /**
+     * @param {string} text - Codemiror text value
+     * @see TextCell#get_text
+     * @method set_text
+     * */
     TextCell.prototype.set_text = function(text) {
         this.code_mirror.setValue(text);
         this.code_mirror.refresh();
     };
 
-
+    /**
+     * setter :{{#crossLink "TextCell/set_rendered"}}{{/crossLink}}
+     * @method get_rendered
+     * @return {html} html of rendered element
+     * */
     TextCell.prototype.get_rendered = function() {
         return this.element.find('div.text_cell_render').html();
     };
 
-
+    /**
+     * @method set_rendered
+     */
     TextCell.prototype.set_rendered = function(text) {
         this.element.find('div.text_cell_render').html(text);
     };
 
-
+    /**
+     * not deprecated, but implementation wrong
+     * @method at_top
+     * @deprecated
+     * @return {Boolean} true is cell rendered, false otherwise
+     * I doubt this is what it is supposed to do
+     * this implementation is completly false
+     */
     TextCell.prototype.at_top = function () {
         if (this.rendered) {
             return true;
         } else {
             return false;
         }
     };
 
 
+    /**
+     * not deprecated, but implementation wrong
+     * @method at_bottom
+     * @deprecated
+     * @return {Boolean} true is cell rendered, false otherwise
+     * I doubt this is what it is supposed to do
+     * this implementation is completly false
+     * */
     TextCell.prototype.at_bottom = function () {
         if (this.rendered) {
             return true;
         } else {
             return false;
         }
     };
 
-
+    /** Create Text cell from JSON
+     * @param {json} data - JSON serialized text-cell
+     */
     TextCell.prototype.fromJSON = function (data) {
         IPython.Cell.prototype.fromJSON.apply(this, arguments);
         if (data.cell_type === this.cell_type) {
             if (data.source !== undefined) {
                 this.set_text(data.source);
                 // make this value the starting point, so that we can only undo
                 // to this state, instead of a blank cell
                 this.code_mirror.clearHistory();
                 this.set_rendered(data.rendered || '');
                 this.rendered = false;
                 this.render();
             }
         }
     };
 
 
     TextCell.prototype.toJSON = function () {
         var data = IPython.Cell.prototype.toJSON.apply(this);
         data.cell_type = this.cell_type;
         data.source = this.get_text();
         return data;
     };
 
 
-    // HTMLCell
-
+    /**
+     * @constructs HtmlCell
+     * @class HtmlCell
+     * @extends TextCell
+     */
     var HTMLCell = function () {
         this.placeholder = "Type <strong>HTML</strong> and LaTeX: $\\alpha^2$";
         IPython.TextCell.apply(this, arguments);
         this.cell_type = 'html';
     };
 
 
     HTMLCell.prototype = new TextCell();
 
 
     HTMLCell.prototype.render = function () {
         if (this.rendered === false) {
             var text = this.get_text();
             if (text === "") { text = this.placeholder; }
             this.set_rendered(text);
             this.typeset();
             this.element.find('div.text_cell_input').hide();
             this.element.find("div.text_cell_render").show();
             this.rendered = true;
         }
     };
 
 
     // MarkdownCell
-
+    /** @class MarkdownCell
+     * @constructs MarkdownCell
+     * @extends HtmlCell
+     */
     var MarkdownCell = function () {
         this.placeholder = "Type *Markdown* and LaTeX: $\\alpha^2$";
         IPython.TextCell.apply(this, arguments);
         this.cell_type = 'markdown';
     };
 
 
     MarkdownCell.prototype = new TextCell();
 
 
     MarkdownCell.prototype.render = function () {
         if (this.rendered === false) {
             var text = this.get_text();
             if (text === "") { text = this.placeholder; }
             text = IPython.mathjaxutils.remove_math(text)
             var html = IPython.markdown_converter.makeHtml(text);
             html = IPython.mathjaxutils.replace_math(html)
             try {
                 this.set_rendered(html);
             } catch (e) {
                 console.log("Error running Javascript in Markdown:");
                 console.log(e);
                 this.set_rendered($("<div/>").addClass("js-error").html(
                     "Error rendering Markdown!<br/>" + e.toString())
                 );
             }
             this.element.find('div.text_cell_input').hide();
             this.element.find("div.text_cell_render").show();
             var code_snippets = this.element.find("pre > code");
             code_snippets.replaceWith(function () {
                 var code = $(this).html();
                 /* Substitute br for newlines and &nbsp; for spaces
                    before highlighting, since prettify doesn't
                    preserve those on all browsers */
                 code = code.replace(/(\r\n|\n|\r)/gm, "<br/>");
                 code = code.replace(/ /gm, '&nbsp;');
                 code = prettyPrintOne(code);
 
                 return '<code class="prettyprint">' + code + '</code>';
             });
             this.typeset()
             this.rendered = true;
         }
     };
 
 
     // RawCell
 
+    /** @construct RawCell
+     * @extends TextCell
+     */
     var RawCell = function () {
         this.placeholder = "Type plain text and LaTeX: $\\alpha^2$";
         this.code_mirror_mode = 'rst';
         IPython.TextCell.apply(this, arguments);
         this.cell_type = 'raw';
         var that = this
 
         this.element.focusout(
                 function() { that.auto_highlight(); }
             );
     };
 
 
     RawCell.prototype = new TextCell();
 
     RawCell.prototype.auto_highlight = function () {
         this._auto_highlight(IPython.config.raw_cell_highlight);
     };
 
     RawCell.prototype.render = function () {
         this.rendered = true;
         this.edit();
     };
 
 
     RawCell.prototype.handle_codemirror_keyevent = function (editor, event) {
         // This method gets called in CodeMirror's onKeyDown/onKeyPress
         // handlers and is used to provide custom key handling. Its return
         // value is used to determine if CodeMirror should ignore the event:
         // true = ignore, false = don't ignore.
 
         var that = this;
         if (event.which === key.UPARROW && event.type === 'keydown') {
             // If we are not at the top, let CM handle the up arrow and
             // prevent the global keydown handler from handling it.
             if (!that.at_top()) {
                 event.stop();
                 return false;
             } else {
                 return true;
             };
         } else if (event.which === key.DOWNARROW && event.type === 'keydown') {
             // If we are not at the bottom, let CM handle the down arrow and
             // prevent the global keydown handler from handling it.
             if (!that.at_bottom()) {
                 event.stop();
                 return false;
             } else {
                 return true;
             };
         };
         return false;
     };
 
 
     RawCell.prototype.select = function () {
         IPython.Cell.prototype.select.apply(this);
         this.code_mirror.refresh();
         this.code_mirror.focus();
     };
 
 
     RawCell.prototype.at_top = function () {
         var cursor = this.code_mirror.getCursor();
         if (cursor.line === 0 && cursor.ch === 0) {
             return true;
         } else {
             return false;
         }
     };
 
 
     RawCell.prototype.at_bottom = function () {
         var cursor = this.code_mirror.getCursor();
         if (cursor.line === (this.code_mirror.lineCount()-1) && cursor.ch === this.code_mirror.getLine(cursor.line).length) {
             return true;
         } else {
             return false;
         }
     };
 
 
-    // HTMLCell
-
+    /** @constructs HeadingCell
+     * @extends TextCell
+     */
     var HeadingCell = function () {
         this.placeholder = "Type Heading Here";
         IPython.TextCell.apply(this, arguments);
         this.cell_type = 'heading';
         this.level = 1;
     };
 
 
     HeadingCell.prototype = new TextCell();
 
-
+    /** from json */
     HeadingCell.prototype.fromJSON = function (data) {
         if (data.level != undefined){
             this.level = data.level;
         }
         IPython.TextCell.prototype.fromJSON.apply(this, arguments);
     };
 
 
     HeadingCell.prototype.toJSON = function () {
         var data = IPython.TextCell.prototype.toJSON.apply(this);
         data.level = this.get_level();
         return data;
     };
 
 
     HeadingCell.prototype.set_level = function (level) {
         this.level = level;
         if (this.rendered) {
             this.rendered = false;
             this.render();
         };
     };
 
-
+    /** The depth of header cell, based on html (h1 to h6)
+     * @return {integer} level - for 1 to 6
+     */
     HeadingCell.prototype.get_level = function () {
         return this.level;
     };
 
 
     HeadingCell.prototype.set_rendered = function (text) {
         var r = this.element.find("div.text_cell_render");
         r.empty();
         r.append($('<h'+this.level+'/>').html(text));
     };
 
 
     HeadingCell.prototype.get_rendered = function () {
         var r = this.element.find("div.text_cell_render");
         return r.children().first().html();
     };
 
 
     HeadingCell.prototype.render = function () {
         if (this.rendered === false) {
             var text = this.get_text();
             if (text === "") { text = this.placeholder; }
             this.set_rendered(text);
             this.typeset();
             this.element.find('div.text_cell_input').hide();
             this.element.find("div.text_cell_render").show();
             this.rendered = true;
         };
     };
 
     IPython.TextCell = TextCell;
     IPython.HTMLCell = HTMLCell;
     IPython.MarkdownCell = MarkdownCell;
     IPython.RawCell = RawCell;
     IPython.HeadingCell = HeadingCell;
 
 
     return IPython;
 
 }(IPython));