Class GLOBALS

addRequestCallback

<static> void addRequestCallback(request, callback)

Add a callback to the request for when the request completes.

arrayCopy

<static> Object arrayCopy(obj)

Creates a 'real' array from something that matches the array interface.

Useful for 'live' arrays like the return value from "Element.getElementsByTagName", which updates live as objects are removed from it. That's great, but makes iteration tough when you are modifying the targets. Also useful on the special Javascript variable arguments, which at least on Mozilla is not a real Array.

blink

<static> void blink(jc, e)

boundMethod

<static> Object boundMethod(object, methodName)

A function to create "bound methods".

A "bound method" is like a function reference to a method, that also carries with it the object to call the method on. This is really useful for things like event handlers.

You can take the return value of this function and call it as if you were calling object[methodName]().

Design note: We take the method name, not a reference, to keep the resolution as late as possible. This allows you to do the Javascript things like re-assign methods in an object freely, and the result of this function will track it.

Parameters:
object - The object to bind the method to.
methodName - The name of the method to bind to.

cancelPendingEvent

<static> void cancelPendingEvent( key )

Cancels the pending event indicated by "key". If the event had a cancelStatement, the cancel statement will be executed.

Parameters:
key - The key of the pending event to cancel.

closureMaker

<static> Object closureMaker(params, func)

A function to create a closure, without having the passed-in variables change underneath you.

Javascript closures work on variable slots, not references, so creating multiple closures in a loop, which widgets.js sometimes does, can fail in unexpected ways. This function provides another frame for the objects to persist in, so each closure gets the intended arguments.

The passed in function will recieve two arguments, "arguments", the Javascript arguments object for the function call, and the provided "params" object, which should be created new for each call (i.e., do not pass as a variable reference, create a new object with {}). From that you can extract all argument information and any of the information you passed in at creation time.

(This has been a lifesaver; I'm not sure XBLinJS's event handling would be possible without this.)

Parameters:
params - A Javascript object, created anew in the call itself, that contains whatever information you want the closed function to have.
func - The function to close on, with the given parameters.

createWidgetGlobals

<static> Object createWidgetGlobals()

create an object suitable to be used as the WidgetGlobals in a frame

This function creates the widget globals needed by the framework. This will be automatically used in the current 'window', but if you trying to use the XBLinJS framework across framesets (which has definate advantages), you'll need to use this on the windows that don't load up 'widgets.js'. See the HTML documentation about "advanced uses".

deriveNewJObject

<static> void deriveNewJObject(newName, baseObject, extraInstanceInit, extraClassInit)

deriveNewJObject is the preferred way to create a new JObject class, since it is moderately complicated. See source or HTML documentation for a full description of what it does, but in summary, it does all the bookwork so you don't have to.

Parameters:
newName - A string, indication the name of the class to create.
baseObject - A string naming the base JObject class, or a reference to the desired base JObject class.
extraInstanceInit - A function that will be called with the newly-created instance as the only parameter. This is rarely used for things that don't really belong in the widget itself, but need to be done.
extraClassInit - A function that will be called as the class initialization, i.e., Object.prototype.initClass = extraClassInit. (This is necessary because you can't define it later in the code, as this function can't see it yet.)

display

<static> void display(object)

display an object in an 'alert' box

display alert()s an object with some relatively nice formatting, showing the relevant attributes and eliding some things like functions that shouldn't be displayed as strings. Works more nicely in Mozilla where more of the browser-provided objects have nicer string representations than in IE, but works better in both than a simple alert(object).

This does require the object to support the for (var x in object) syntax, and every once in a while you will find a browser object which doesn't.

DOM

<static> Object DOM(node)

Given a DOM node or a Widget, flattens them into a DOM node reference. Useful for agnostically using a Widget as a DOM node for DOM node manipulation purposes.

emptyNode

<static> void emptyNode(domNode)

Given a DOM node, empty it of all children nodes by removing them until they are all gone.

equalButNotEscaped

<static> Object equalButNotEscaped(s,i,q)

findbeginning

<static> Object findbeginning(s, from, stopAtDot)

focusIt

<static> Object focusIt(a)

getcaretpos

<static> Object getcaretpos(inp)

getKeys

<static> Object getKeys(object)

Given a JS object, returns a list of the keys of the values in that object.

getRequest

<static> Object getRequest()

Retrieve an XMLHttpRequest in a cross-platform manner.

load

<static> void load(jc, url)

min

<static> Object min(a,b)

objCopy

<static> Object objCopy(obj)

Creates a one-layer-deep deep copy of another object.

Useful in the Widget context for dynamically modifying certain things out of a .prototype without affecting the original.

pendingEvent

<static> void pendingEvent( key, ms, exeStatement, cancelStatement )

Creates a new pending event.

A "pending event" is in essense a more intelligent version of the .setTimeout call (which is used to implement pending events). The best way to understand it is to start with a canonical example of one: Suppose you are writing a drop-down box attached to a text box, and you want the dropdown box to fire after the user is idle for some amount of time. (Most browser address bars are like this.)

The way to do that is to create a pendingEvent every time the user enters a character, with the same key used for each one; for concreteness let's call the key "dropDown". Each subsequent "dropDown" pendingEvent will cancel the previous one, so if each one is created with a half second delay, the net effect is that only the final half-second delay will fire the event handling code. As long as the user types more quickly than that, the handler never fires. This turns out to be very useful in UI code.

Each pendingEvent can also have a cancel function which will be called every time it is cancelled, and pendingEvents can be manually cancelled by calling cancelEvent. In the dropdown example, that would most likely be done every time the user leaves the text box, so the dropdown won't suddenly appear a half second later when the user's attention is on another widget entirely.

Parameters:
key - The unique key that identifies this pending event. Use this key to cancel the event with cancelEvent, or supercede the event with later calls to pendingEvent. (Only the last pendingEvent call for a given key will be used.)
ms - When to fire this pending event in milliseconds from the call time, as long as it is not cancelled or superceded. This is of course build on window.setTimeout, and subject to the same timing considerations: You are guaranteed to not have the event fire before the time has passed, but it can occur arbitrarily far into the future.
exeStatement - The statement to execute when the event fires. Can either be a string, or a closure function taking no arguments.
cancelStatement - The statement to execute when the event is cancelled, either by a call to cancelEvent or a superceding call to pendingEvent. Can either be a string, or a closure function taking no arguments.

pr

<static> Object pr(jc, s)

print

<static> void print(jc, s)

props

<static> void props(jc, e)

replaceElementWithWidget

<static> Object replaceElementWithWidget(element, targetWindow)

For a given tag in a DOM document, replace it with a newly-created Widget, passed the attributes from the HTML tag.

You should generally use existing functions that use this, but you may need to call this directly for your own advanced uses.

Any content in the tag will be passed to the newly-constructed widget via .appendChild calls; any children widget tags will be first converted to widgets. Returns the created widget, or the HTML DOM node passed in if no Widget was created.

If an element is replaced, an attribute "XBLinJSreplaced" will be set to "1" on the DOM Node, and this function will not replace the element a second time.

A special attribute "globalName" will be eaten by this function (not passed to the Widget creation function), and a new global variable will be created containing the resulting widget. You'll know when you need this.

Parameters:
element - The DOM element to be replaced with a widget. This function actually doesn't care what type of element it is.
targetWindow - For advanced usage: specify the window object this widget will be a part of. For when you are using XBLinJS in a framed environment. See HTML documentation on "advanced uses".

ReplaceWidgetTags

<static> void ReplaceWidgetTags(targetWindow)

A function to replace tags with widgets.

This uses document.getElementsByTagName with a non-HTML tag name, which may cause problems with some browsers, or not; I'm being paranoid since it is very hard to test them all. Any content in the tag will be passed to the newly-constructed widget via .appendChild calls; any children widget tags will be first converted to widgets.

Parameters:
window - : The target window to traverse. For advanced uses where XBLinJS is being used across frames: Due to the way scopes work, this function can only pick up the window it is defined in, not the one it was called in. Passing in the window will correctly create the widgets. Not doing this correctly currently causes silent failure; I need to detect this and give a better error.

resolveFlavor

<static> void resolveFlavor(flavor)

Resolve the deferred functions in a Flavor, copy relevant globals.

This resolves all the functions in a flavor that we deferred the execution of and prepares a Flavor for actual use, among other things copying relevant global functions out like setAttributeOn.

runOnloadHandlers

<static> void runOnloadHandlers(targetWindow)

A function to run onloadHandlers as defined in WidgetGlobals.

This should be called like <body onload="runOnloadHandlers(window)"> for Widgets that set onload handlers. (None of the XBLinJS-provided Widgets do, but yours may.)

scope

<static> void scope(jc, sc)

setOutline

<static> Object setOutline(e,o)

setselectionto

<static> Object setselectionto(inp,pos)

textNode

<static> Object textNode(text)

A convenience function to create a text node with the given text.

All DOM implementations should do this the same, so this is a function, not a method.

Parameters:
text - The contents of the text node.

times

<static> Object times(s, n)

WidgetInit

<static> void WidgetInit()

Store Widgets also in a WidgetNameToType object, so we can know that anything in that object is a Widget.