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

Add some very rough API documentation for Events.

Browse Source
This commit is contained in:
Doug Kearns
2009-05-20 23:59:31 +10:00
parent 72aba0f876
commit 111e27bf2e
3 changed files with 120 additions and 68 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
common/content/commands.js
View File

@@ -403,52 +403,54 @@ function Commands() //{{{
// FIXME: remove later, when our option handler is better // FIXME: remove later, when our option handler is better
/** /**
* @property The option argument is unspecified. Any argument is * @property {number} The option argument is unspecified. Any argument
* accepted and caller is responsible for parsing the return value. * is accepted and caller is responsible for parsing the return
* value.
* @final * @final
*/ */
OPTION_ANY: 0, OPTION_ANY: 0,
/** /**
* @property The option doesn't accept an argument. * @property {number} The option doesn't accept an argument.
* @final * @final
*/ */
OPTION_NOARG: 1, OPTION_NOARG: 1,
/** /**
* @property The option accepts a boolean argument. * @property {number} The option accepts a boolean argument.
* @final * @final
*/ */
OPTION_BOOL: 2, OPTION_BOOL: 2,
/** /**
* @property The option accepts a string argument. * @property {number} The option accepts a string argument.
* @final * @final
*/ */
OPTION_STRING: 3, OPTION_STRING: 3,
/** /**
* @property The option accepts an integer argument. * @property {number} The option accepts an integer argument.
* @final * @final
*/ */
OPTION_INT: 4, OPTION_INT: 4,
/** /**
* @property The option accepts a float argument. * @property {number} The option accepts a float argument.
* @final * @final
*/ */
OPTION_FLOAT: 5, OPTION_FLOAT: 5,
/** /**
* @property The option accepts a string list argument. E.g. "foo,bar" * @property {number} The option accepts a string list argument.
* E.g. "foo,bar"
* @final * @final
*/ */
OPTION_LIST: 6, OPTION_LIST: 6,
/** /**
* @property Indicates that no count was specified for this command * @property {number} Indicates that no count was specified for this
* invocation. * command invocation.
* @final * @final
*/ */
COUNT_NONE: -1, COUNT_NONE: -1,
/** /**
* @property Indicates that the full buffer range (1,$) was specified * @property {number} Indicates that the full buffer range (1,$) was
* for this command invocation. * specified for this command invocation.
* @final * @final
*/ */
// FIXME: this isn't a count at all // FIXME: this isn't a count at all

67
common/content/events.js
View File

@@ -765,10 +765,17 @@ function Events() //{{{
const self = { const self = {
/**
* @property {boolean} Whether synthetic key events are currently being
* processed.
*/
feedingKeys: false, feedingKeys: false,
wantsModeReset: true, // used in onFocusChange since Firefox is so buggy here wantsModeReset: true, // used in onFocusChange since Firefox is so buggy here
/**
* A destructor called when this module is destroyed.
*/
destroy: function () destroy: function ()
{ {
// removeEventListeners() to avoid mem leaks // removeEventListeners() to avoid mem leaks
@@ -789,6 +796,11 @@ function Events() //{{{
window.removeEventListener("keydown", this.onKeyDown, true); window.removeEventListener("keydown", this.onKeyDown, true);
}, },
/**
* Initiates the recording of a key event macro.
*
* @param {string} macro The name for the macro.
*/
startRecording: function (macro) startRecording: function (macro)
{ {
if (!/[a-zA-Z0-9]/.test(macro)) if (!/[a-zA-Z0-9]/.test(macro))
@@ -813,6 +825,12 @@ function Events() //{{{
} }
}, },
/**
* Replays a macro.
*
* @param {string} The name of the macro to replay.
* @return {boolean}
*/
playMacro: function (macro) playMacro: function (macro)
{ {
let res = false; let res = false;
@@ -863,6 +881,11 @@ function Events() //{{{
return res; return res;
}, },
/**
* Returns all macros matching <b>filter</b>.
*
* @param {string} filter A regular expression filter.
*/
getMacros: function (filter) getMacros: function (filter)
{ {
if (!filter) if (!filter)
@@ -872,6 +895,11 @@ function Events() //{{{
return ([macro, keys] for ([macro, keys] in macros) if (re.test(macro))); return ([macro, keys] for ([macro, keys] in macros) if (re.test(macro)));
}, },
/**
* Deletes all macros matching <b>filter</b>.
*
* @param {string} filter A regular expression filter.
*/
deleteMacros: function (filter) deleteMacros: function (filter)
{ {
let re = RegExp(filter); let re = RegExp(filter);
@@ -884,12 +912,13 @@ function Events() //{{{
}, },
/** /**
* Pushes keys into the event queue from liberator it is similar to * Pushes keys onto the event queue from liberator. It is similar to
* Vim's feedkeys() method, but cannot cope with 2 partially-fed * Vim's feedkeys() method, but cannot cope with 2 partially-fed
* strings, you have to feed one parsable string. * strings, you have to feed one parsable string.
* *
* @param {string} keys A string like "2<C-f>" to pass if you want "<" * @param {string} keys A string like "2<C-f>" to push onto the event
* to be taken literally, prepend it with a "\\". * queue. If you want "<" to be taken literally, prepend it with a
* "\\".
* @param {boolean} noremap Allow recursive mappings. * @param {boolean} noremap Allow recursive mappings.
* @param {boolean} silent Whether the command should be echoed to the * @param {boolean} silent Whether the command should be echoed to the
* command line. * command line.
@@ -1012,10 +1041,15 @@ function Events() //{{{
return i == keys.length; return i == keys.length;
}, },
// this function converts the given event to /**
// a keycode which can be used in mappings * Converts the specified key event to a string in liberator key-code
// e.g. pressing ctrl+n would result in the string "<C-n>" * notation. Returns null for an unknown key event.
// null if unknown key *
* E.g. pressing ctrl+n would result in the string "<C-n>".
*
* @param {Event} event
* @returns {string}
*/
toString: function (event) toString: function (event)
{ {
if (!event) if (!event)
@@ -1125,16 +1159,34 @@ function Events() //{{{
return "<" + modifier + key + ">"; return "<" + modifier + key + ">";
}, },
/**
* Whether <b>key</b> is a key code defined to accept/execute input on
* the command line.
*
* @returns {boolean}
*/
isAcceptKey: function (key) isAcceptKey: function (key)
{ {
return (key == "<Return>" || key == "<C-j>" || key == "<C-m>"); return (key == "<Return>" || key == "<C-j>" || key == "<C-m>");
}, },
/**
* Whether <b>key</b> is a key code defined to reject/cancel input on
* the command line.
*
* @returns {boolean}
*/
isCancelKey: function (key) isCancelKey: function (key)
{ {
return (key == "<Esc>" || key == "<C-[>" || key == "<C-c>"); return (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.
*
* @returns {boolean}
*/
waitForPageLoad: function () waitForPageLoad: function ()
{ {
//liberator.dump("start waiting in loaded state: " + buffer.loaded); //liberator.dump("start waiting in loaded state: " + buffer.loaded);
@@ -1181,6 +1233,7 @@ function Events() //{{{
// argument "event" is deliberately not used, as i don't seem to have // argument "event" is deliberately not used, as i don't seem to have
// access to the real focus target // access to the real focus target
// Huh? --djk
// //
// the ugly wantsModeReset is needed, because Firefox generates a massive // the ugly wantsModeReset is needed, because Firefox generates a massive
// amount of focus changes for things like <C-v><C-k> (focusing the search field) // amount of focus changes for things like <C-v><C-k> (focusing the search field)

49
common/content/hints.js
View File

@@ -84,9 +84,9 @@ function Hints() //{{{
}; };
/** /**
* Used to open multiple hints * Used to open multiple hints.
* *
* @param {node} elem the previously selected hint * @param {node} elem The previously selected hint.
*/ */
function hintAction_F(elem) function hintAction_F(elem)
{ {
@@ -131,7 +131,7 @@ function Hints() //{{{
* Get a hint for "input", "textarea" and "select". * Get a hint for "input", "textarea" and "select".
* *
* Tries to use <label>s if possible but does not try to guess that a * Tries to use <label>s if possible but does not try to guess that a
* neighbouring element might look like a label. Only called by generate() * neighbouring element might look like a label. Only called by generate().
* *
* If it finds a hint it returns it, if the hint is not the caption of the * If it finds a hint it returns it, if the hint is not the caption of the
* element it will return showtext=true. * element it will return showtext=true.
@@ -199,7 +199,7 @@ function Hints() //{{{
/** /**
* Gets the actual offset of an imagemap area. * Gets the actual offset of an imagemap area.
* *
* Only called by generate() * Only called by generate().
* *
* @param {Object} elem The <area> element. * @param {Object} elem The <area> element.
* @param {number} leftpos The left offset of the image. * @param {number} leftpos The left offset of the image.
@@ -274,7 +274,7 @@ function Hints() //{{{
* *
* Pushes the hints into the pageHints object, but does not display them. * Pushes the hints into the pageHints object, but does not display them.
* *
* @param {Window} win The window,defaults to window.content * @param {Window} win The window,defaults to window.content.
*/ */
function generate(win) function generate(win)
{ {
@@ -444,10 +444,6 @@ function Hints() //{{{
} }
} }
// TODO: is it better to set up an observer for this property and set
// 'usermode' appropriately? We're generally not very well integrated
// into FF so having menu items toggle Vimperator options may be
// confusing. --djk
if (getBrowser().markupDocumentViewer.authorStyleDisabled) if (getBrowser().markupDocumentViewer.authorStyleDisabled)
{ {
let css = []; let css = [];
@@ -471,7 +467,7 @@ function Hints() //{{{
* *
* Lingers on the active hint briefly to confirm the selection to the user. * Lingers on the active hint briefly to confirm the selection to the user.
* *
* @param {Number} timeout The number of milliseconds before the active * @param {number} timeout The number of milliseconds before the active
* hint disappears. * hint disappears.
*/ */
function removeHints(timeout) function removeHints(timeout)
@@ -504,8 +500,8 @@ function Hints() //{{{
* Called when there are one or zero hints in order to possibly activate it * Called when there are one or zero hints in order to possibly activate it
* and, if activated, to clean up the rest of the hinting system. * and, if activated, to clean up the rest of the hinting system.
* *
* @param {boolean} followFirst Whether to force the following of the * @param {boolean} followFirst Whether to force the following of the first
* first link (when 'followhints' is 1 or 2) * link (when 'followhints' is 1 or 2)
* *
*/ */
function processHints(followFirst) function processHints(followFirst)
@@ -595,11 +591,11 @@ function Hints() //{{{
/** /**
* Divide a string by a regular expression. * Divide a string by a regular expression.
* *
* @param {RegExp|String} pat The pattern to split on * @param {RegExp|string} pat The pattern to split on.
* @param {String} string The string to split * @param {string} str The string to split.
* @returns {Array(string)} The lowercased splits of the stting. * @returns {Array(string)} The lowercased splits of the splitting.
*/ */
function tokenize(pat, string) string.split(pat).map(String.toLowerCase); function tokenize(pat, str) str.split(pat).map(String.toLowerCase);
/** /**
* Get a hint matcher for hintmatching=contains * Get a hint matcher for hintmatching=contains
@@ -608,7 +604,7 @@ function Hints() //{{{
* returns true if each set of characters typed can be found, in any * returns true if each set of characters typed can be found, in any
* order, in the link. * order, in the link.
* *
* @param {String} hintString The string typed by the user. * @param {string} hintString The string typed by the user.
* @returns {function(String):boolean} A function that takes the text * @returns {function(String):boolean} A function that takes the text
* of a hint and returns true if all the (space-delimited) sets of * of a hint and returns true if all the (space-delimited) sets of
* characters typed by the user can be found in it. * characters typed by the user can be found in it.
@@ -649,8 +645,8 @@ function Hints() //{{{
* like 'Hey Kris, how are you?' -> [HE]y [K]ris [HO]w are you * like 'Hey Kris, how are you?' -> [HE]y [K]ris [HO]w are you
* --Daniel * --Daniel
* *
* @param {String} chars The characters to match * @param {string} chars The characters to match.
* @param {Array(String)} words The words to match them against * @param {Array(string)} words The words to match them against.
* @param {boolean} allowWordOverleaping Whether words may be * @param {boolean} allowWordOverleaping Whether words may be
* skipped during matching. * skipped during matching.
* @returns {boolean} Whether a match can be found. * @returns {boolean} Whether a match can be found.
@@ -701,15 +697,16 @@ function Hints() //{{{
} }
/** /**
* Check whether the array of strings all exist at the start of the words. * Check whether the array of strings all exist at the start of the
* words.
* *
* i.e. ['ro', 'e'] would match ['rollover', 'effect'] * i.e. ['ro', 'e'] would match ['rollover', 'effect']
* *
* The matches must be in order, and, if allowWordOverleaping is false, * The matches must be in order, and, if allowWordOverleaping is
* contiguous. * false, contiguous.
* *
* @param {Array(String)} strings The strings to search for. * @param {Array(string)} strings The strings to search for.
* @param {Array(String)} words The words to search in. * @param {Array(string)} words The words to search in.
* @param {boolean} allowWordOverleaping Whether matches may be * @param {boolean} allowWordOverleaping Whether matches may be
* non-contiguous. * non-contiguous.
* @returns boolean Whether all the strings matched. * @returns boolean Whether all the strings matched.
@@ -910,8 +907,8 @@ function Hints() //{{{
/** /**
* Updates the display of hints. * Updates the display of hints.
* *
* @param {String} minor Which hint mode to use. * @param {string} minor Which hint mode to use.
* @param {String} filter The filter to use. * @param {string} filter The filter to use.
* @param {Object} win The window in which we are showing hints. * @param {Object} win The window in which we are showing hints.
*/ */
show: function (minor, filter, win) show: function (minor, filter, win)