gryf/pentadactyl-pm
1
0
Fork 0
mirror of https://github.com/gryf/pentadactyl-pm.git synced 2025-12-22 10:27: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
/**
* @property The option argument is unspecified. Any argument is
* accepted and caller is responsible for parsing the return value.
* @property {number} The option argument is unspecified. Any argument
* is accepted and caller is responsible for parsing the return
* value.
* @final
*/
OPTION_ANY: 0,
/**
* @property The option doesn't accept an argument.
* @property {number} The option doesn't accept an argument.
* @final
*/
OPTION_NOARG: 1,
/**
* @property The option accepts a boolean argument.
* @property {number} The option accepts a boolean argument.
* @final
*/
OPTION_BOOL: 2,
/**
* @property The option accepts a string argument.
* @property {number} The option accepts a string argument.
* @final
*/
OPTION_STRING: 3,
/**
* @property The option accepts an integer argument.
* @property {number} The option accepts an integer argument.
* @final
*/
OPTION_INT: 4,
/**
* @property The option accepts a float argument.
* @property {number} The option accepts a float argument.
* @final
*/
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
*/
OPTION_LIST: 6,
/**
* @property Indicates that no count was specified for this command
* invocation.
* @property {number} Indicates that no count was specified for this
* command invocation.
* @final
*/
COUNT_NONE: -1,
/**
* @property Indicates that the full buffer range (1,$) was specified
* for this command invocation.
* @property {number} Indicates that the full buffer range (1,$) was
* specified for this command invocation.
* @final
*/
// FIXME: this isn't a count at all

67
common/content/events.js
View File

@@ -765,10 +765,17 @@ function Events() //{{{
const self = {
/**
* @property {boolean} Whether synthetic key events are currently being
* processed.
*/
feedingKeys: false,
wantsModeReset: true, // used in onFocusChange since Firefox is so buggy here
/**
* A destructor called when this module is destroyed.
*/
destroy: function ()
{
// removeEventListeners() to avoid mem leaks
@@ -789,6 +796,11 @@ function Events() //{{{
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)
{
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)
{
let res = false;
@@ -863,6 +881,11 @@ function Events() //{{{
return res;
},
/**
* Returns all macros matching <b>filter</b>.
*
* @param {string} filter A regular expression filter.
*/
getMacros: function (filter)
{
if (!filter)
@@ -872,6 +895,11 @@ function Events() //{{{
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)
{
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
* strings, you have to feed one parsable string.
*
* @param {string} keys A string like "2<C-f>" to pass if you want "<"
* to be taken literally, prepend it with a "\\".
* @param {string} keys A string like "2<C-f>" to push onto the event
* queue. If you want "<" to be taken literally, prepend it with a
* "\\".
* @param {boolean} noremap Allow recursive mappings.
* @param {boolean} silent Whether the command should be echoed to the
* command line.
@@ -1012,10 +1041,15 @@ function Events() //{{{
return i == keys.length;
},
// this function converts the given event to
// a keycode which can be used in mappings
// e.g. pressing ctrl+n would result in the string "<C-n>"
// null if unknown key
/**
* Converts the specified key event to a string in liberator key-code
* notation. Returns null for an unknown key event.
*
* E.g. pressing ctrl+n would result in the string "<C-n>".
*
* @param {Event} event
* @returns {string}
*/
toString: function (event)
{
if (!event)
@@ -1125,16 +1159,34 @@ function Events() //{{{
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)
{
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)
{
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 ()
{
//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
// access to the real focus target
// Huh? --djk
//
// 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)

95
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)
{
@@ -131,14 +131,14 @@ function Hints() //{{{
* Get a hint for "input", "textarea" and "select".
*
* 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
* element it will return showtext=true.
*
* @param {Object} elem The element.
* @param {string} tagname Its tagname.
* @param {Document} doc The document it is in.
* @param {Object} elem The element.
* @param {string} tagname Its tagname.
* @param {Document} doc The document it is in.
*
* @returns [text, showtext]
*/
@@ -199,7 +199,7 @@ function Hints() //{{{
/**
* Gets the actual offset of an imagemap area.
*
* Only called by generate()
* Only called by generate().
*
* @param {Object} elem The <area> element.
* @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.
*
* @param {Window} win The window,defaults to window.content
* @param {Window} win The window,defaults to window.content.
*/
function generate(win)
{
@@ -351,8 +351,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)
{
@@ -368,8 +368,8 @@ function Hints() //{{{
/**
* Toggle the highlight of a hint.
*
* @param {Object} elem The element to toggle.
* @param {boolean} active Whether it is the currently active hint or not.
* @param {Object} elem The element to toggle.
* @param {boolean} active Whether it is the currently active hint or not.
*/
function setClass(elem, active)
{
@@ -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)
{
let css = [];
@@ -471,8 +467,8 @@ function Hints() //{{{
*
* Lingers on the active hint briefly to confirm the selection to the user.
*
* @param {Number} timeout The number of milliseconds before the active
* hint disappears.
* @param {number} timeout The number of milliseconds before the active
* hint disappears.
*/
function removeHints(timeout)
{
@@ -504,8 +500,8 @@ function Hints() //{{{
* 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.
*
* @param {boolean} followFirst Whether to force the following of the
* first link (when 'followhints' is 1 or 2)
* @param {boolean} followFirst Whether to force the following of the first
* link (when 'followhints' is 1 or 2)
*
*/
function processHints(followFirst)
@@ -563,7 +559,7 @@ function Hints() //{{{
* Will update the filter on displayed hints and follow the final hint if
* necessary.
*
* @param {Event} event The keypress event.
* @param {Event} event The keypress event.
*/
function onInput (event)
{
@@ -587,7 +583,7 @@ function Hints() //{{{
/**
* Get the hintMatcher according to user preference.
*
* @param {string} hintString The currently typed hint.
* @param {string} hintString The currently typed hint.
* @returns {hintMatcher}
*/
function hintMatcher(hintString) //{{{
@@ -595,11 +591,11 @@ function Hints() //{{{
/**
* Divide a string by a regular expression.
*
* @param {RegExp|String} pat The pattern to split on
* @param {String} string The string to split
* @returns {Array(string)} The lowercased splits of the stting.
* @param {RegExp|string} pat The pattern to split on.
* @param {string} str The string to split.
* @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
@@ -608,7 +604,7 @@ function Hints() //{{{
* returns true if each set of characters typed can be found, in any
* 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
* of a hint and returns true if all the (space-delimited) sets of
* characters typed by the user can be found in it.
@@ -630,8 +626,8 @@ 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 {boolean} allowWordOverleaping Whether to allow non-contiguous
* @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
* hints that match as above.
@@ -649,11 +645,11 @@ function Hints() //{{{
* like 'Hey Kris, how are you?' -> [HE]y [K]ris [HO]w are you
* --Daniel
*
* @param {String} chars The characters to match
* @param {Array(String)} words The words to match them against
* @param {boolean} allowWordOverleaping Whether words may be
* @param {string} chars The characters to match.
* @param {Array(string)} words The words to match them against.
* @param {boolean} allowWordOverleaping Whether words may be
* skipped during matching.
* @returns {boolean} Whether a match can be found.
* @returns {boolean} Whether a match can be found.
*/
function charsAtBeginningOfWords(chars, words, allowWordOverleaping)
{
@@ -701,18 +697,19 @@ 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,
* contiguous.
* The matches must be in order, and, if allowWordOverleaping is
* false, contiguous.
*
* @param {Array(String)} strings The strings to search for.
* @param {Array(String)} words The words to search in.
* @param {boolean} allowWordOverleaping Whether matches may be
* @param {Array(string)} strings The strings to search for.
* @param {Array(string)} words The words to search in.
* @param {boolean} allowWordOverleaping Whether matches may be
* non-contiguous.
* @returns boolean Whether all the strings matched.
* @returns boolean Whether all the strings matched.
*/
function stringsAtBeginningOfWords(strings, words, allowWordOverleaping)
{
@@ -893,12 +890,12 @@ 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} mode The letter that identifies this mode.
* @param {string} description The description to display to the user
* about this mode.
* @param {function(Node)} callback The function to be called with the
* @param {function(Node)} callback The function to be called with the
* element that matches.
* @param {function():string} selector The function that returns an
* @param {function():string} selector The function that returns an
* XPath selector to decide which elements can be hinted (the
* default returns options.hinttags).
*/
@@ -910,9 +907,9 @@ function Hints() //{{{
/**
* Updates the display of hints.
*
* @param {String} minor Which hint mode to use.
* @param {String} filter The filter to use.
* @param {Object} win The window in which we are showing hints.
* @param {string} minor Which hint mode to use.
* @param {string} filter The filter to use.
* @param {Object} win The window in which we are showing hints.
*/
show: function (minor, filter, win)
{
@@ -966,7 +963,7 @@ function Hints() //{{{
/**
* Handle a hint mode event.
*
* @param {Event} event The event to handle.
* @param {Event} event The event to handle.
*/
onEvent: function (event)
{