diff --git a/common/content/ui.js b/common/content/ui.js index f45f5cfb..36a1f144 100644 --- a/common/content/ui.js +++ b/common/content/ui.js @@ -75,6 +75,12 @@ function CommandLine() //{{{ var keepCommand = false; var lastEcho = null; + /** + * A class for managing the history of an inputField + * + * @param {Object} inputField + * @param {string} mode + */ function History(inputField, mode) { if (!(this instanceof arguments.callee)) @@ -85,11 +91,16 @@ function CommandLine() //{{{ this.reset(); } History.prototype = { + /** + * Empties the history. + */ reset: function () { this.index = null; }, - + /** + * Permanently save the history + */ save: function () { let str = this.input.value; @@ -99,13 +110,23 @@ function CommandLine() //{{{ this.store.push(str); this.store.truncate(options["history"], true); }, - + /** + * Set the current match to val + * + * @param {string} val + */ replace: function (val) { this.input.value = val; liberator.triggerCallback("change", currentExtendedMode, val); }, + /** + * move up or (if backward) down in the history + * + * @param {boolean} backward + * @param {boolean} matchCurrent XXX: what? + */ select: function (backward, matchCurrent) { // always reset the tab completion if we use up/down keys @@ -154,6 +175,11 @@ function CommandLine() //{{{ } }; + /** + * A class for tab completions on an input field + * + * @param {Object} input + */ function Completions(input) { if (!(this instanceof arguments.callee)) @@ -529,16 +555,28 @@ function CommandLine() //{{{ var multilineRegexp = null; var multilineCallback = null; + /** + * @private - highlight the messageBox according to group + */ function setHighlightGroup(group) { messageBox.setAttributeNS(NS.uri, "highlight", group); } - // Whether the command line must be open. + /** + * @private - Determines whether the command line should be visible. + * + * @return {boolean} + */ function commandShown() modes.main == modes.COMMAND_LINE && !(modes.extended & (modes.INPUT_MULTILINE | modes.OUTPUT_MULTILINE)); - // sets the prompt - for example, : or / + /** + * @private - set the prompt to val styled with highlightGroup + * + * @param {string} val + * @param {string} highlightGroup + */ function setPrompt(val, highlightGroup) { promptWidget.value = val; @@ -547,7 +585,11 @@ function CommandLine() //{{{ promptWidget.setAttributeNS(NS.uri, "highlight", highlightGroup || commandline.HL_NORMAL); } - // sets the command - e.g. 'tabopen', 'open http://example.com/' + /** + * @private - set the command to cmd and move the user's cursor to the end. + * + * @param {string} cmd + */ function setCommand(cmd) { commandWidget.value = cmd; @@ -555,6 +597,14 @@ function CommandLine() //{{{ commandWidget.selectionEnd = cmd.length; } + /** + * @private - display a message styled with highlightGroup + * and, if forceSingle is true, ensure it takes only one line. + * + * @param {string} str + * @param {string} highlightGroup + * @param {boolean} forceSingle + */ function echoLine(str, highlightGroup, forceSingle) { setHighlightGroup(highlightGroup); @@ -570,7 +620,14 @@ function CommandLine() //{{{ echoMultiline({str}, highlightGroup); } - // TODO: resize upon a window resize + /** + * Display a multiline message, possible through a "more" like interface + * + * TODO: resize upon a window resize + * + * @param {string} str + * @param {string} highlightGroup + */ function echoMultiline(str, highlightGroup) { let doc = multilineOutputWidget.contentDocument; @@ -615,6 +672,10 @@ function CommandLine() //{{{ commandline.updateMorePrompt(); } + /** + * @private - ensure that the Multiline input widget is the + * correct size. + */ function autosizeMultilineInputWidget() { let lines = multilineInputWidget.value.split("\n").length - 1; @@ -622,7 +683,16 @@ function CommandLine() //{{{ multilineInputWidget.setAttribute("rows", Math.max(lines, 1)); } - // used for the :echo[err] commands + /** + * @private - eval()s a javascript expression + * and returns a string suitable to be echo'd. + * + * If useColor is true, util.objectToString will + * colorize object output. + * + * @param {string} arg + * @param {boolean} useColor + */ function echoArgumentToString(arg, useColor) { if (!arg) @@ -891,6 +961,9 @@ function CommandLine() //{{{ storage.styles.removeSheet(true, "silent-mode"); }, + /** + * XXX: This function is not used! + */ runSilently: function (fn, self) { let wasSilent = this.silent; @@ -918,6 +991,16 @@ function CommandLine() //{{{ get message() messageBox.value, + /** + * Changes the command line to display the following prompt (usually ":") + * followed by the command, in the given mode. Valid modes are + * attributes of the "modes" variable, and modes.EX is probably + * a good choice. + * + * @param {string} prompt + * @param {string} cmd + * @param {number} mode + */ open: function open(prompt, cmd, extendedMode) { // save the current prompts, we need it later if the command widget @@ -942,7 +1025,11 @@ function CommandLine() //{{{ liberator.triggerCallback("change", currentExtendedMode, cmd); }, - // normally used when pressing , does not execute a command + /** + * Removes any input from the command line, without executing its + * contents. Removes any "More" windows or other such output. + * Pressing in EX mode normally has this effect. + */ close: function close() { let mode = currentExtendedMode; @@ -976,14 +1063,33 @@ function CommandLine() //{{{ keepCommand = false; }, + + /** + * Hide any auto-completion/More-ing that is happening. + */ hide: function hide() { commandlineWidget.collapsed = true; }, - // liberator.echo uses different order of flags as it omits the highlight group, change v.commandline.echo argument order? --mst + /** + * Output the given string onto the command line coloured + * using the rules according to highlightGroup. If not + * given higlightGroup defaults to commandline.HL_NORMAL + * and other possibe values are at commandline.HL_[A-Z]*. + * + * Flags can be any of: + * commandline.APPEND_TO_MESSAGES (causes message to be added to the messagesHistory) + * commandline.FORCE_SINGLELINE | commandline.DISALLOW_MULTILINE + * commandline.FORCE_MULTILINE + * + * @param {string} str + * @param {string} highlightGroup + * @param {number} flags + */ echo: function echo(str, highlightGroup, flags) { + // liberator.echo uses different order of flags as it omits the highlight group, change v.commandline.echo argument order? --mst if (silent) return false; @@ -1028,8 +1134,23 @@ function CommandLine() //{{{ return true; }, - // this will prompt the user for a string - // commandline.input("(s)ave or (o)pen the file?") + /** + * Prompt the user for a string and execute the given + * callback with that as the only argument on + * extra can have any of the following attributes: + * + * onChange: A function to be called with the current input every time it changes + * completer: A function called with a ?context? when the user tries to tabcomplete + * promptHighlight: The HighlightGroup to use (default commandline.HL_QUESTION, others + * can be found at commandline.HL_[A-Z]*) + * + * This function sets the mode to modes.COMMAND_LINE, and thus popping the mode will + * stop further input from being waited for (useful for stopping onChange) + * + * @param {string} prompt + * @param {function(string)} callback + * @param {Object} extra + */ input: function input(prompt, callback, extra) { extra = extra || {}; @@ -1049,8 +1170,14 @@ function CommandLine() //{{{ completions = Completions(commandWidget.inputField); }, - // reads a multi line input and returns the string once the last line matches - // @param untilRegexp + /** + * Get a multiline input from a user, up to but not including + * the line which matches the given regular expression. Then + * execute the callback with that string as a parameter. + * + * @param {RegExp} untilRegexp + * @param {function(string)} callbackFunc + */ inputMultiline: function inputMultiline(untilRegexp, callbackFunc) { // Kludge. @@ -1070,6 +1197,13 @@ function CommandLine() //{{{ setTimeout(function () { multilineInputWidget.focus(); }, 10); }, + /** + * Handle events, the come from liberator when liberator.mode = modes.COMMAND_LINE + * but also takes blur/focus/input events raw from #liberator-commandline-command + * in the XUL + * + * @param {Event} event + */ onEvent: function onEvent(event) { let command = this.command; @@ -1162,6 +1296,12 @@ function CommandLine() //{{{ } }, + /** + * Multiline input events, they will come straight from + * #liberator-multiline-input in the XUL. + * + * @param {Event} event + */ onMultilineInputEvent: function onMultilineInputEvent(event) { if (event.type == "keypress") @@ -1196,8 +1336,16 @@ function CommandLine() //{{{ return true; }, - // FIXME: if 'more' is set and the MOW is not scrollable we should still - // allow a down motion after an up rather than closing + /** + * Handle events when we are in multiline output mode, + * these come from liberator when modes.extended & modes.MULTILINE_OUTPUT + * and also from #liberator-multiline-output in the XUL + * + * FIXME: if 'more' is set and the MOW is not scrollable we should still + * allow a down motion after an up rather than closing + * + * @param {Event} event + */ onMultilineOutputEvent: function onMultilineOutputEvent(event) { let win = multilineOutputWidget.contentWindow; @@ -1407,6 +1555,15 @@ function CommandLine() //{{{ } }, + /** + * Refresh or remove the prompt that displays when in multiline mode. + * showHelp will cause the possible key-options to be displayed, + * force will cause a display of the default message even if it + * could be at the end of the output. + * + * @param {boolean} force + * @param {boolean} showHelp + */ updateMorePrompt: function updateMorePrompt(force, showHelp) { if (outputContainer.collapsed) @@ -1424,6 +1581,14 @@ function CommandLine() //{{{ echoLine("Press ENTER or type command to continue", this.HL_QUESTION, true); }, + /** + * Changes the height of the multilineOutputWidget to fit + * its contents, if open is true, it will cause the + * widget to uncollapse, if not it will leave the widget + * closed. + * + * @param {boolean} open + */ updateOutputHeight: function updateOutputHeight(open) { if (!open && outputContainer.collapsed) @@ -1446,6 +1611,10 @@ function CommandLine() //{{{ outputContainer.collapsed = false; }, + /** + * Disable any active completion functions by calling their cancelFunc's + * Will also remove the completions preview window. + */ resetCompletions: function resetCompletions() { autocompleteTimer.reset(); @@ -1782,6 +1951,14 @@ function StatusLine() //{{{ return { + /** + * Update the status bar to indicate how secure the website is + * secure => https:// with valid certificate + * broken => https:// with invalid certificate + * insecure => http:// + * + * @param {'secure'|'broken'|'insecure'} type + */ setClass: function setClass(type) { const highlightGroup = { @@ -1803,7 +1980,14 @@ function StatusLine() //{{{ this.updateBufferPosition(); }, - // if "url" is omitted, build a usable string for the URL + /** + * Update which URL is displayed on the status line, + * if url is omitted then buffer.URL is used instead and + * status icons [+-❤] are updated to match whether one can + * go back/forwards in history/have bookmarked the page. + * + * @param {string} url + */ updateUrl: function updateUrl(url) { if (typeof url == "string") @@ -1846,6 +2030,13 @@ function StatusLine() //{{{ urlWidget.value = url; }, + /** + * Set the contents of the status line's input buffer + * to the given string. + * + * Used for displaying partial key combinations in + * normal mode. + */ updateInputBuffer: function updateInputBuffer(buffer) { if (!buffer || typeof buffer != "string") @@ -1854,6 +2045,17 @@ function StatusLine() //{{{ inputBufferWidget.value = buffer; }, + /** + * Update the display of the progress bar. + * If the parameter is a string, it will be + * displayed literally. Otherwise it must be a number + * less than one. + * Negative numbers cause a "Loading..." status, + * Positive (< 1) numbers cause an arrow ==> of length + * proportional to the arrow. + * + * @param {string|number} progress + */ updateProgress: function updateProgress(progress) { if (!progress) @@ -1881,7 +2083,13 @@ function StatusLine() //{{{ } }, - // you can omit either of the 2 arguments + /** + * Display the correct tabcount (e.g. [1/5]) on the status bar. + * If either parameter is omitted, they will be calculated. + * + * @param {number} currentIndex + * @param {number} totalTabs + */ updateTabCount: function updateTabCount(currentIndex, totalTabs) { if (!liberator.has("tabs")) @@ -1906,7 +2114,16 @@ function StatusLine() //{{{ tabCountWidget.value = "[" + currentIndex + "/" + totalTabs + "]"; }, - // percent is given between 0 and 1 + /** + * Display the correct position on the status bar, if the + * percent parameter is omitted it will be calculated. + * + * Negative numbers are set to "All", Zero implies "Top" + * One or above is "Bot", and anything else is multiplied by + * a hundred and displayed as a percentage. + * + * @param {number} percent + */ updateBufferPosition: function updateBufferPosition(percent) { if (!percent || typeof percent != "number")