gryf/pentadactyl-pm
1
0
Fork 0
mirror of https://github.com/gryf/pentadactyl-pm.git synced 2025-12-20 04:27:59 +01:00
Code Issues Projects Releases Wiki Activity

Cleanup and add some documention.

Browse Source
This commit is contained in:
Doug Kearns
2009-06-29 19:06:40 +10:00
parent 701f9ef494
commit f9ffc9138a
14 changed files with 193 additions and 66 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
common/content/buffer.js
View File

@@ -1028,8 +1028,8 @@ function Buffer() //{{{
* @default The current document.
* @param {Node} elem The context element.
* @default <b>doc</b>
* @param {boolean} asIterator Whether to return the results as an XPath
* iterator.
* @param {boolean} asIterator Whether to return the results as an
* XPath iterator.
*/
evaluateXPath: function (expression, doc, elem, asIterator)
{
@@ -1510,7 +1510,7 @@ function Buffer() //{{{
/**
* Displays information about the specified element.
*
* @param {Node} elem
* @param {Node} elem The element to query.
*/
showElementInfo: function (elem)
{
@@ -1848,7 +1848,8 @@ function Marks() //{{{
* selected from. If it matches [a-z'"], it's a local mark, and can
* only be recalled from a buffer with a matching URL.
*
* @param {string} mark
* @param {string} mark The mark name.
* @param {boolean} silent Whether to output error messages.
*/
// TODO: add support for frameset pages
add: function (mark, silent)

4
common/content/commands.js
View File

@@ -181,7 +181,7 @@ Command.prototype = {
* @param {string} args The args to be parsed and passed to
* {@link #action}.
* @param {boolean} bang Whether this command was executed with a trailing
* !.
* bang.
* @deprecated
* @param {number} count Whether this command was executed with a leading
* count.
@@ -224,7 +224,7 @@ Command.prototype = {
/**
* Returns whether this command may be invoked via <b>name</b>.
*
* @param {string} name
* @param {string} name The candidate name.
* @returns {boolean}
*/
hasName: function (name)

1
common/content/completion.js
View File

@@ -547,6 +547,7 @@ CompletionContext.prototype = {
/**
* Gets a key from {@link #cache}, setting it to <b>defVal</b> if it
* doesn't already exists.
*
* @param {string} key
* @param defVal
*/

4
common/content/configbase.js
View File

@@ -37,7 +37,7 @@ const configbase = { //{{{
get browserModes() [modes.NORMAL],
/**
* @property {object} Application specific defaults for option values. The
* @property {Object} Application specific defaults for option values. The
* property names must be the options' canonical names, and the values
* must be strings as entered via :set.
*/
@@ -86,7 +86,7 @@ const configbase = { //{{{
init: function () {},
/**
* @property {object} A map between key names for key events should be ignored,
* @property {Object} A map between key names for key events should be ignored,
* and a mask of the modes in which they should be ignored.
*/
ignoreKeys: {}, // XXX: be aware you can't put useful values in here, as "modes.NORMAL" etc. are not defined at this time

46
common/content/events.js
View File

@@ -479,7 +479,7 @@ function Events() //{{{
let elem = liberator.focus;
return ((elem instanceof HTMLInputElement && !/image/.test(elem.type)) ||
elem instanceof HTMLTextAreaElement ||
elem instanceof HTMLIsIndexElement)
elem instanceof HTMLIsIndexElement);
}
function triggerLoadAutocmd(name, doc)
@@ -965,18 +965,21 @@ function Events() //{{{
},
/**
* Converts a user-input string of keys into a canonical representation.
* Converts a user-input string of keys into a canonical
* representation.
*
* <C-A> maps to <C-a>, <C-S-a> maps to <C-S-A>
* <C- > maps to <C-Space>, <S-a> maps to A
* << maps to <lt><lt>
*
* <S-@> is preserved, as in vim, to allow untypable key-combinations in macros
* <S-@> is preserved, as in vim, to allow untypable key-combinations
* in macros.
*
* canonicalKeys(canonicalKeys(x)) == canonicalKeys(x) for all values of x.
* canonicalKeys(canonicalKeys(x)) == canonicalKeys(x) for all values
* of x.
*
* @param {String} keys messy form
* @returns {String} canonical form
* @param {string} keys Messy form.
* @returns {string} Canonical form.
*/
canonicalKeys: function (keys)
{
@@ -986,16 +989,18 @@ function Events() //{{{
/**
* Converts an event string into an array of pseudo-event objects.
*
* These objects can be used as arguments to events.toString or events.create,
* though they are unlikely to be much use for other purposes. They have many
* of the properties you'd expect to find on a real event, but none of the methods.
* These objects can be used as arguments to events.toString or
* events.create, though they are unlikely to be much use for other
* purposes. They have many of the properties you'd expect to find on a
* real event, but none of the methods.
*
* Also may contain two "special" parameters, .liberatorString and .liberatorShift
* these are set for characters that can never by typed, but may appear in mappings,
* for example <Nop> is passed as liberatorString, and liberatorShift is set when
* a user specifies <S-@> where @ is a non-case-changable, non-space character.
* Also may contain two "special" parameters, .liberatorString and
* .liberatorShift these are set for characters that can never by
* typed, but may appear in mappings, for example <Nop> is passed as
* liberatorString, and liberatorShift is set when a user specifies
* <S-@> where @ is a non-case-changable, non-space character.
*
* @param {String} keys The string to parse
* @param {string} keys The string to parse.
* @return {Array[Object]}
*/
fromString: function (input)
@@ -1082,7 +1087,7 @@ function Events() //{{{
* @param {Event} event
* @returns {string}
*/
toString: function (event, all)
toString: function (event)
{
if (!event)
return "[object Mappings]";
@@ -1197,6 +1202,7 @@ function Events() //{{{
* Whether <b>key</b> is a key code defined to accept/execute input on
* the command line.
*
* @param {string} key The key code to test.
* @returns {boolean}
*/
isAcceptKey: function (key) key == "<Return>" || key == "<C-j>" || key == "<C-m>",
@@ -1205,11 +1211,12 @@ function Events() //{{{
* Whether <b>key</b> is a key code defined to reject/cancel input on
* the command line.
*
* @param {string} key The key code to test.
* @returns {boolean}
*/
isCancelKey: function (key) key == "<Esc>" || key == "<C-[>" || key == "<C-c>",
/*
/**
* Waits for the current buffer to successfully finish loading. Returns
* true for a successful page load otherwise false.
*
@@ -1346,7 +1353,9 @@ function Events() //{{{
// }
},
// global escape handler, is called in ALL modes
/**
* The global escape key handler. This is called in ALL modes.
*/
onEscape: function ()
{
if (modes.passNextKey)
@@ -1665,6 +1674,9 @@ function Events() //{{{
},
// TODO: move to buffer.js?
/**
* The liberator document loading progress listener.
*/
progressListener: {
QueryInterface: XPCOMUtils.generateQI([
Ci.nsIWebProgressListener,

19
common/content/hints.js
View File

@@ -217,7 +217,7 @@ function Hints() //{{{
try
{
// Need to add the offset to the area element.
// Always try to find the top-left point, as per vimperator default.
// Always try to find the top-left point, as per liberator default.
let shape = elem.getAttribute("shape").toLowerCase();
let coordstr = elem.getAttribute("coords");
// Technically it should be only commas, but hey
@@ -352,8 +352,8 @@ function Hints() //{{{
*
* By default highlights it green instead of yellow.
*
* @param {Number} newID The hint to make active
* @param {Number} oldID The currently active hint
* @param {number} newID The hint to make active.
* @param {number} oldID The currently active hint.
*/
function showActiveHint(newID, oldID)
{
@@ -624,7 +624,7 @@ function Hints() //{{{
* would match the first letters of words. It will always only match
* words in order.
*
* @param {String} hintString The string typed by the user.
* @param {string} hintString The string typed by the user.
* @param {boolean} allowWordOverleaping Whether to allow non-contiguous
* words to match.
* @returns {function(String):boolean} A function that will filter only
@@ -893,15 +893,16 @@ function Hints() //{{{
* Creates a new hint mode.
*
* @param {string} mode The letter that identifies this mode.
* @param {string} description The description to display to the user
* @param {string} prompt The description to display to the user
* about this mode.
* @param {function(Node)} callback The function to be called with the
* @param {function(Node)} action The function to be called with the
* element that matches.
* @param {function():string} selector The function that returns an
* XPath selector to decide which elements can be hinted (the
* @param {function():string} tags The function that returns an
* XPath expression to decide which elements can be hinted (the
* default returns options.hinttags).
* @optional
*/
addMode: function (mode)
addMode: function (mode, prompt, action, tags)
{
hintModes[mode] = Mode.apply(Mode, Array.slice(arguments, 1));
},

6
common/content/io.js
View File

@@ -65,7 +65,7 @@ function IO() //{{{
/////////////////////////////////////////////////////////////////////////////{{{
const WINDOWS = liberator.has("Win32");
const EXTENSION_NAME = config.name.toLowerCase(); // "vimperator" or "muttator"
const EXTENSION_NAME = config.name.toLowerCase();
const downloadManager = Cc["@mozilla.org/download-manager;1"].createInstance(Ci.nsIDownloadManager);
@@ -569,7 +569,7 @@ function IO() //{{{
expandPath: IO.expandPath,
// TODO: there seems to be no way, short of a new component, to change
// the process's CWD - see // https://bugzilla.mozilla.org/show_bug.cgi?id=280953
// the process's CWD - see https://bugzilla.mozilla.org/show_bug.cgi?id=280953
/**
* Returns the current working directory.
*
@@ -1119,7 +1119,7 @@ lookup:
},
// TODO: when https://bugzilla.mozilla.org/show_bug.cgi?id=68702 is
// fixed is fixed, should use that instead of a tmpfile
// fixed use that instead of a tmpfile
/**
* Runs <b>command</b> in a subshell and returns the output in a
* string. The shell used is that specified by the 'shell' option.

157
common/content/liberator.js
View File

@@ -26,7 +26,6 @@ the provisions above, a recipient may use your version of this file under
the terms of any one of the MPL, the GPL or the LGPL.
}}} ***** END LICENSE BLOCK *****/
/** @scope modules */
Cu.import("resource://gre/modules/XPCOMUtils.jsm", modules);
@@ -87,8 +86,8 @@ const liberator = (function () //{{{
}
}
// initially hide all GUI, it is later restored unless the user has :set go= or something
// similar in his config
// initially hide all GUI elements, they are later restored unless the user
// has :set go= or something similar in his config
function hideGUI()
{
let guioptions = config.guioptions;
@@ -108,7 +107,6 @@ const liberator = (function () //{{{
function getPlatformFeature()
{
let platform = navigator.platform;
return /^Mac/.test(platform) ? "MacUnix" : platform == "Win32" ? "Win32" : "Unix";
}
@@ -153,7 +151,7 @@ const liberator = (function () //{{{
////////////////////// OPTIONS /////////////////////////////////////////////////
/////////////////////////////////////////////////////////////////////////////{{{
// Only general options are added here, which are valid for all Vimperator like extensions
// Only general options are added here, which are valid for all Liberator extensions
registerObserver("load_options", function () {
options.add(["errorbells", "eb"],
@@ -644,7 +642,10 @@ const liberator = (function () //{{{
modules: modules,
/** @property {number} The current main mode. */
/**
* @property {number} The current main mode.
* @see modes#mainModes
*/
get mode() modes.main,
set mode(value) modes.main = value,
@@ -661,14 +662,13 @@ const liberator = (function () //{{{
forceNewTab: false,
// these VERSION and DATE tokens are replaced by the Makefile
/** @property {string} The liberator application version string. */
version: "###VERSION### (created: ###DATE###)",
/** @property {string} The Liberator version string. */
version: "###VERSION### (created: ###DATE###)", // these VERSION and DATE tokens are replaced by the Makefile
// NOTE: services.get("profile").selectedProfile.name doesn't return
// what you might expect. It returns the last _actively_ selected
// profile (i.e. via the Profile Manager or -p option) rather than the
// current one. These will differ if the current process was run
// profile (i.e. via the Profile Manager or -P option) rather than the
// current profile. These will differ if the current process was run
// without explicitly selecting a profile.
/** @property {string} The name of the current user profile. */
profileName: services.get("directory").get("ProfD", Ci.nsIFile).leafName.replace(/^.+?\./, ""),
@@ -688,7 +688,7 @@ const liberator = (function () //{{{
rcFile: null,
/** @property An Ex command to run before any initialization is performed. */
preCommand: null,
/** @property An Ex command to run after all initialization is performed. */
/** @property An Ex command to run after all initialization has been performed. */
postCommand: null
},
@@ -758,15 +758,39 @@ const liberator = (function () //{{{
return false; // so you can do: if (...) return liberator.beep();
},
/**
* Creates a new thread.
*/
newThread: function () services.get("threadManager").newThread(0),
/**
* Calls a function asynchronously on a new thread.
*
* @param {nsIThread} thread The thread to call the function on. If no
* thread is specified a new one is created.
* @optional
* @param {Object} self The 'this' object used when executing the
* function.
* @param {function} func The function to execute.
*
*/
callAsync: function (thread, self, func)
{
thread = thread || services.get("threadManager").newThread(0);
thread.dispatch(new Runnable(self, func, Array.slice(arguments, 3)), thread.DISPATCH_NORMAL);
},
// be sure to call GUI related methods like alert() or dump() ONLY in the main thread
/**
* Calls a function synchronously on a new thread.
*
* NOTE: Be sure to call GUI related methods like alert() or dump()
* ONLY in the main thread.
*
* @param {nsIThread} thread The thread to call the function on. If no
* thread is specified a new one is created.
* @optional
* @param {function} func The function to execute.
*/
callFunctionInThread: function (thread, func)
{
thread = thread || services.get("threadManager").newThread(0);
@@ -775,11 +799,13 @@ const liberator = (function () //{{{
thread.dispatch(new Runnable(null, func, Array.slice(arguments, 2)), thread.DISPATCH_SYNC);
},
// NOTE: "browser.dom.window.dump.enabled" preference needs to be set
/**
* Prints a message to the console. If <b>msg</b> is an object it is
* pretty printed.
*
* NOTE: the "browser.dom.window.dump.enabled" preference needs to be
* set.
*
* @param {string|Object} msg The message to print.
*/
dump: function (msg)
@@ -805,12 +831,26 @@ const liberator = (function () //{{{
liberator.dump((msg || "Stack") + "\n" + stack);
},
/**
* Outputs a plain message to the command line.
*
* @param {string} str The message to output.
* @param {number} flags These control the multiline message behaviour.
* See {@link CommandLine#echo}.
*/
echo: function (str, flags)
{
commandline.echo(str, commandline.HL_NORMAL, flags);
},
// TODO: Vim replaces unprintable characters in echoerr/echomsg
/**
* Outputs an error message to the command line.
*
* @param {string} str The message to output.
* @param {number} flags These control the multiline message behaviour.
* See {@link CommandLine#echo}.
*/
echoerr: function (str, flags)
{
flags |= commandline.APPEND_TO_MESSAGES;
@@ -827,6 +867,16 @@ const liberator = (function () //{{{
},
// TODO: add proper level constants
/**
* Outputs an information message to the command line.
*
* @param {string} str The message to output.
* @param {number} verbosity The messages log level (0 - 15). Only
* messages with verbosity less than or equal to the value of the
* 'verbosity' option will be output.
* @param {number} flags These control the multiline message behaviour.
* See {@link CommandLine#echo}.
*/
echomsg: function (str, verbosity, flags)
{
// TODO: is there a reason for this? --djk
@@ -851,6 +901,15 @@ const liberator = (function () //{{{
commandline.echo(str, commandline.HL_INFOMSG, flags);
},
/**
* Loads and executes the script referenced by <b>uri</b> in the scope
* of the <b>context</b> object.
*
* @param {string} uri The URI of the script to load. Should be a local
* chrome:, file:, or resource: URL.
* @param {Object} context The context object into which the script
* should be loaded.
*/
loadScript: function (uri, context)
{
services.get("subscriptLoader").loadSubScript(uri, context);
@@ -978,7 +1037,7 @@ const liberator = (function () //{{{
},
/**
* Focus the content window.
* Focuses the content window.
*
* @param {boolean} clearFocusedElement Remove focus from any focused
* element.
@@ -1014,16 +1073,33 @@ const liberator = (function () //{{{
elem.focus();
},
// does this liberator extension have a certain feature?
/**
* Returns whether this Liberator extension supports <b>feature</b>.
*
* @param {string} feature The feature name.
* @returns {boolean}
*/
has: function (feature) config.features.indexOf(feature) >= 0,
/**
* Returns whether the host application has the specified extension
* installed.
*
* @param {string} name The extension name.
* @returns {boolean}
*/
hasExtension: function (name)
{
let extensions = services.get("extensionManager").getItemList(Ci.nsIUpdateItem.TYPE_EXTENSION, {});
return extensions.some(function (e) e.name == name);
},
/**
* Returns the URL of the specified help <b>topic</b> if it exists.
*
* @param {string} topic The help topic to lookup.
* @returns {string}
*/
findHelp: function (topic)
{
let items = completion.runCompleter("help", topic);
@@ -1041,9 +1117,17 @@ const liberator = (function () //{{{
if (partialMatch)
return format(partialMatch);
return null;
else
return null;
},
/**
* Opens the help page containing the specified <b>topic</b> if it
* exists.
*
* @param {string} topic The help topic to open.
* @returns {string}
*/
help: function (topic)
{
let where = (options["newtab"] && options.get("newtab").has("all", "help"))
@@ -1069,6 +1153,11 @@ const liberator = (function () //{{{
content.postMessage("fragmentChange", "*");
},
/**
* The map of global variables.
*
* These are set and accessed with the "g:" prefix.
*/
globalVariables: {},
loadModule: function (name, func) { loadModule(name, func); },
@@ -1239,7 +1328,14 @@ const liberator = (function () //{{{
// v.plugins.onEvent = <func> function triggered, on keypresses (unless <esc>) (see events.js)
plugins: plugins,
// quit liberator, no matter how many tabs/windows are open
/**
* Quit the host application, no matter how many tabs/windows are open.
*
* @param {boolean} saveSession If true the current session will be
* saved and restored when the host application is restarted.
* @param {boolean} force Forcibly quit irrespective of whether all
* windows could be closed individually.
*/
quit: function (saveSession, force)
{
// TODO: Use safeSetPref?
@@ -1254,10 +1350,17 @@ const liberator = (function () //{{{
window.goQuitApplication();
},
/**
* Reports an error to both the console and the host application's
* Error Console.
*
* @param {Object} error The error object.
*/
reportError: function (error)
{
if (Cu.reportError)
Cu.reportError(error);
try
{
let obj = {
@@ -1276,7 +1379,7 @@ const liberator = (function () //{{{
},
/**
* Restart the Liberator host application.
* Restart the host application.
*/
restart: function ()
{
@@ -1302,7 +1405,16 @@ const liberator = (function () //{{{
services.get("appStartup").quit(Ci.nsIAppStartup.eRestart | Ci.nsIAppStartup.eAttemptQuit);
},
parseCommandLine: function (commandline)
/**
* Parses a Liberator command-line string i.e. the value of the
* -liberator command-line option.
*
* @param {string} cmdline The string to parse for command-line
* options.
* @returns {Object}
* @see Commands#parseArgs
*/
parseCommandLine: function (cmdline)
{
const options = [
[["+u"], commands.OPTIONS_STRING],
@@ -1310,10 +1422,9 @@ const liberator = (function () //{{{
[["++cmd"], commands.OPTIONS_STRING],
[["+c"], commands.OPTIONS_STRING]
];
return commands.parseArgs(commandline, options, "*");
return commands.parseArgs(cmdline, options, "*");
},
// TODO: move to {muttator,vimperator,...}.js
// this function is called when the chrome is ready
startup: function ()
{

2
common/content/style.js
View File

@@ -200,7 +200,7 @@ function Highlights(name, store)
this.selector = function (class)
{
let [, hl, rest] = class.match(/^(\w*)(.*)/);
return "[liberator|highlight~=" + hl + "]" + rest
return "[liberator|highlight~=" + hl + "]" + rest;
};
/**

3
common/content/ui.js
View File

@@ -812,7 +812,6 @@ function CommandLine() //{{{
validator: Option.validateCompleter
});
// TODO: these belong in ui.js
options.add(["complete", "cpt"],
"Items which are completed at the :[tab]open prompt",
"charlist", "slf",
@@ -1072,7 +1071,7 @@ function CommandLine() //{{{
* Open the command line. The main mode is set to
* COMMAND_LINE, the extended mode to <b>extendedMode</b>.
* Further, callbacks defined for <b>extendedMode</b> are
* triggered as appropriate (see {@link Liberator#registerCallback}).
* triggered as appropriate (see {@link liberator#registerCallback}).
*
* @param {string} prompt
* @param {string} cmd

5
common/content/util.js
View File

@@ -179,9 +179,9 @@ const util = { //{{{
},
/**
* Split a string on literal occurances of a marker.
* Split a string on literal occurrences of a marker.
*
* Specifically this ignores occurences preceded by a backslash, or
* Specifically this ignores occurrences preceded by a backslash, or
* contained within 'single' or "double" quotes.
*
* It assumes backslash escaping on strings, and will thus not count quotes
@@ -703,6 +703,7 @@ const util = { //{{{
}
}; //}}}
// TODO: Why don't we just push all util.BuiltinType up into modules? --djk
/**
* Array utility methods.
*/

1
muttator/content/config.js
View File

@@ -30,6 +30,7 @@ const config = { //{{{
/*** required options, no checks done if they really exist, so be careful ***/
name: "Muttator",
hostApplication: "Thunderbird", // TODO: can this be found out otherwise? gBrandBundle.getString("brandShortName");
// Yes, but it will be localized unlike all other strings. So, it's best left until we i18n liberator. --djk
get mainWindowID() this.isComposeWindow ? "msgcomposeWindow" : "messengerWindow",
/*** optional options, there are checked for existence and a fallback provided ***/

1
vimperator/TODO
View File

@@ -6,6 +6,7 @@ ARCHITECTURE:
- I made a quick attempt at parameterizing it using attributes but it
breaks Asciidoc formatting in certain unpredictable (to me at least)
contexts. *sigh* --djk
- decide on how to document Arrays in our jsdoc(ish) documentation.
BUGS:
- add window resize support to hints

1
vimperator/content/config.js
View File

@@ -383,7 +383,6 @@ const config = { //{{{
},
{ argCount: "0" });
// TODO: move sidebar commands to ui.js?
commands.add(["sbcl[ose]"],
"Close the sidebar window",
function ()