The Gimme API Reference

The Gimme Object

A Gimme Object is the object returned from any g(..) invocation. A Gimme Object exposes all of the methods in the Core Gimme Modules (listed below).
Additionally, the inclusion of other, optional, modules (listed later) can extend the Gimme Object and allows it to expose even more methods.

Supported CSS selectors

The most recent list of CSS selectors supported by Gimme

g(css, [callback)]

this is how you invoke Gimme's CSS selector engine

Core Gimme (gimme.core.js)

.entities

Returns the underlying array of DOM elements that a call to g(..) fetches

.element([n)]

Returns an underlying DOM element from the Gimme Object's internal array. The n parameter is is optional; if unspecified, it will default to 0.

.parent([n)]

Returns the parentNode of an underlying DOM element from the Gimme Object's internal array. The n parameter is is optional; if unspecified, it will default to 0.

.addEvent(eventName, handlerFn, [useCapture)]

Adds an event listener to all elements in the Gimme Object (useCapture defaults to false).

.removeEvent(eventName, handlerFn, [useCapture)]

Removes an event listener from all elements in the Gimme Object (useCapture defaults to false).

.setHTML(html)

Set the .innerHTML property of all element in the Gimme Object.

.getHTML([n)]

Returns the .innerHTML property of the nth element in the Gimme Object; n is optional and defaults to 0.

.setValue(val)

Sets the .value (or .nodeValue in the case of textNodes) property of all elements in the Gimme Object.

.getValue([n)]

Returns the .value property of the nth element in the Gimme Object; n is optional and defaults to 0.

.setStyle(styleName, val)

Sets the .style[styleName] property of all elements in the Gimme Object to the given val.

.setStyles(styleName, val, [styleName, val, styleName, val, etc...)]

Simliar to .setStyle, but allows you to set multiple styles at once, alleviating the need to chain together multiple .setStyle(..) calls.

.getStyle(styleName, [n)]

Returns the specified style property of the nth element in the GImme Object's internal array; n is optional and default to 0.

.addClass(classNames)

Adds a CSS class (or classes) to all elements in the Gimme Object.

.removeClass(classNames)

Removes a CSS class (or classes) from all elements in the Gimme Object.

.swapClass(oldClass, newClass)

Iterates through all elements in the Gimme Object, replacing oldClass with newClass in each element's .className property.

.hasClass(classNames, [n)]

Returns true if the nth element in the Gimme Object has all of the specified classNames; returns false otherwise.

.getSibling(dist, [n)]

Returns a sibling DOM element that is dist siblings away from the nth element in the Gimme Object (dist can be negative; n is optional and defaults to 0).

.getAncestor(dist, [n)]

Returns an ancestor DOM element that dist generations removed from the nth element in the Gimme Object (dist should be > 0; n is optional and defaults to 0).

.readAttribute(attr, [n)]

Retrieves the attribute specified by attr of the nth element in the Gimme Object's internal array (attempts to equalize browser differences).

.writeAttribute(attr, val)

Sets the attribute specified by attr of all elements in the Gimme Object to the value specified by val.

.filter(callback)

Filters the Gimme Object's internal array be executing callback on each element. The DOM element itself is automatically passed into the callback. If the callback returns true, the element remains; otherwise it is filtered out.

.iterate(callback)

Iterates through all elements in the Gimme Object's underlying array, executing the specified callback on each DOM element. The callback automatically receives a Gimme-wrapped version of the DOM element (which can be accessed via the "this" keyword) and the index of the DOM element in the underlying array.

.forEach(callback, [thisObject)]

Iterates through all elements in the Gimme Object's underlying array, executing the specified callback on each DOM element. The callback automatically receives a direct reference to the DOM element, the index of that DOM element, and a reference to the underlying array being iterated over. Optionally, you may specify the object to be used as the "this" object in the callback by supplying the second parameter.

.map(callback, [thisObject)]

Returns a new array, where each element in the new array a direct one-to-one mapping of each element from the Gimme Object's underlying array (but which has been modified by the specified callback function). Optionally, you may specifying the object to be used as the "this" object in the callback by supplying the second parameter.

.contains(item)

Returns true if the Gimme Object's underlying array contains the specified item, false otherwise.

.indexOf(item)

Returns the index at which the specified item was found in the Gimme Object's underlying array. If the item was not found, -1 will be returned.

.select(cssQuery)

Returns a new Gimme Object, but uses element at index 0 of the current Gimme Object's entities array as the root for the given cssQuery

The Gimme Screen Module & Extensions (gimme.screen.js)

Gimme.Screen.getViewportSize()

Returns an object literal in the form { height: h, width: w } indicating the current height and width of the the viewport.

Gimme.Screen.getMousePosition(evt)

Returns an object literal in the form { x: xPos, y: yPos } indicating the (x, y) coordinates of the mouse cursor (given a valid event object).

Gimme.Screen.getScrollPosition()

Returns an object literal in the form { x: horizScroll, y: vertScroll } indicating the horizontal and vertical scroll values of the browser window.

.getScreenPosition([n)]

Returns an object literal in the form { x: xPos, y: yPos } indicating the absolute screen position of the nth element in the Gimme Object's internal array (n is optional and defaults to 0).

.getPagePosition([n)]

Returns an object literal in the form { x: xPos, y: yPos } indicating the page position of the nth element in the Gimme Object's internal array (n is optional and defaults to 0).

.getPosition(accountForScroll, [n)]

Returns an object literal in the form { x: xPos, y: yPos } indicating the position of the nth element in the Gimme Object's internal array (n is optional and defaults to 0).
Note: It is not recommended that you call this function directly. Instead, use .getScreenPosition(..) or .getPagePosition(..) which know how to properly forward to this function.

.getComputedPosition([n)]

Returns an object literal in the form { x: topVal, y: leftVal } indicating the CSS computed position (top and left) of the nth element in the Gimme Object's internal array (n is optional and defaults to 0).

The Gimme Effects Extensions (gimme.effects.js)

.fadeIn([duration, guid, callback)]

Fades in all DOM elements in the Gimme Object's interal array, starting at each individual element's current opacity and increasing to 100% opacity.

.fadeOut([duration, guid, callback)]

Fades out all DOM elements in the Gimme Object's interal array, starting at each individual element's current opacity and decreasing to 0% opacity.

.fadeTo(startOpacity, endOpacity, [duration, guid, callback, accelerationLine)]

Fade all DOM elements in the Gimme Object's internal array, forcing each element to the specified startOpacity and increasing/decreasing tot he specified endOpacity.

.veil([direction, duration, guid, callback)]

Veils (or gradually hides through change in height) each DOM element in the Gimme Object's internal array, starting with the element's current (rendered) height and decreasing to height zero.

.unveil([direction, duration, guid, callback)]

Unveils (or gradually reveals through change in height) each DOM element in the Gimme Object's internal array, forcing the element to start height zero and increasing to the element's natural, full height.

.scrollTo([duration, guid, callback)]

Causes the window to scroll (in an animated fashion) to the point needed to bring the first element in the Gimme Object's internal array into view.

.slideToPoint(endPt, [duration, guid, callback, accelerationLine)]

Slides each DOM element in the Gimme Object's internal array from its current position to the specified endPt, an object literal in the form { x: xPos, y: yPox } (an absolute position on the screen).

.followPath(path, factor, [duration, guid, callback, acclererationLine)]

Animates each DOM element in the Gimme Object's internal array along the specified path (a BezierCurve object), according to the specified factor (used to scale the BezierCurve).

.animate([path, duration, guid, callback, logicFn, setupFn_]

Invokes a "generic" animation on all DOM elements in the Gimme Object's internal array, using the specified setupFn to "set up" the animation and using the specified logicFn, to execute the animation's logic.
Note: This function is called internally by all of Gimme's stock effects functions (slideToPoint, followPath, etc...). Additionally, it can be used by 3rd party devs to create custom animations.

The Gimme Animation Module (gimme.animation.js)

Note: Generally speaking, the functions that live in the Gimme Animation Module are not intended to be called directly. Rather the Gimme Animation Module is used primarily as a helper for the Gimme Effects Extensions (see above) and as a mechanism to allow 3rd party developers to leverage Gimme's animation capabilities in order to simplify writing their own animation extensions for Gimme.

Gimme.Animation.start(guid, fn, milliseconds)

Starts an animation (identified by its guid), that works by repeatedly executing the specified function, fn, at the requested interval (milliseconds) until a call to Gimme.Animation.end(guid) is executed.

Gimme.Animation.end(guid)

Ends the animation with the specified guid.

Gimme.Animation.isRunning(guid)

Returns true if the animation with the specified guid is currently running, false otherwise.

Gimme.Animation.whenDone(guid, callback)

Instructs Gimme that the animation with the specified guid should invoke the function, callback, when said animation has completed.

Last edited Nov 13, 2007 at 10:57 PM by sstchur, version 38

Comments

No comments yet.