Library: activator.js
Overview
activator.js Widget.Activator activates controls with highlighters, selection, and en/disabling functionality.
Requires Prototype (http://www.prototypejs.org) 1.6 or later

Copyright (c) 2007 - 2008 Marc Heiligers (marc@eternal.co.za) http://www.eternal.co.za

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Change History:
Version 0.2.00: 11 Oct 2008
- Prepared for release, updated docs and demo pages
- Added MIT license
Version 0.1.15: 8 Oct 2008
- BREAKING CHANGE: the event memo is no longer the element but now contains the following properties:
element - the element
activator - the activator
event - the event that triggered this event
Version 0.1.14: 5 Oct 2008
- Fixed bug where elements were still firing mouseout when disabled
Version 0.1.13: 8 Jun 2008
- Updated setEnabled so that it removes the active and hover styles if you disable an element
Version 0.1.12: 18 Apr 2008
- Updated apply so that it ensures that selected and enabled elements remain so
Version 0.1.11: 17 Mar 2008
- Fixed a bug in setSelected and setEnabled where the default was not true
Version 0.1.10: 12 Mar 2008
- Added click event
Version 0.1.9: 7 Mar 2008
- Added this.selector to save the original selector
- Added apply method which removes all and reapplies the original selector
Version 0.1.8: 3 Mar 2008
- Moved event name options into their own events options
Version 0.1.7: 25 Feb 2008
- Fixed a bug where the elements array was not correctly compacted after remove
Version 0.1.6: 23 Feb 2008
- getElements will return all elements if passed null or *
- The above affects methods like remove: remove() or remove("*") will remove all elements
- Selector in constructor is now optional
- Minor improvement in constructor - just call add instead of calling add for each element returned from $$(selector) which add does anyway
- Fixed a bug in add where it would incorrectly try to add a selector string passed in
- Moved className options into a classNames object
Version 0.1.5: 18 Feb 2008
- Fixed a bugs in selectAll and enableAll where the default was not true
Version 0.1.4: 19 Jan 2008
- Fixed a minor bug in add
- Added possibility for selector to be null - TODO: paramater mashing
Version 0.1.3: 10 Dec 2007
- Added mousedownEvent and mouseupEvent names to options
Version 0.1.2: 19 Oct 2007
- Added handlers array and updated destroy method to stopObserving all event handlers
Version 0.1.1: 18 Oct 2007
- Improved #isElement method to allow for sliding doors
- Turned event names into properties of Widget.Activator (Widget.Activator.mousedownEvent and Widget.Activator.mouseupEvent)
Version 0.1.0: 14 Oct 2007
- Initial version
Constructors
Widget.Activator()
Widget.Activator
version: 0.1.13
Widget.Activator.initialize(selector, options)
The Activator class constructor.
parameters
string selector? A CSS selector string which is defines one or more elements to be activated
object options? An object hash of options.
Widget.Activator.initialize.options(classNames, events, container, singleSelect, extendElements)
The default options object.
parameters
object classNames? The classNames object to be applied to all activated elements. (default: null)
object events? The event names to be used. (default: null)
string container? An element that contains all activated elements, and that is the source of all activator events. If null, document.body is used. (default: null)
bool singleSelect? If true, only one element can be selected at a time. (default: false)
bool extendElements? If true, all activated elements are extended with #getActivator(), #isSelected(), #setSelected(bool), #isEnabled(), and #setEnabled(bool) methods. (default: false)
Namespaces
Functions
Widget.Activator.apply(elements)
Removes all elements and then adds elements based on the selector, or the original selector if none is passed.
parameters
string, Array, element elements A CSS selector string, array of elements, or single element to add.
Widget.Activator.add(elements)
Add elements to the activator.
parameters
string, Array, element elements A CSS selector string, array of elements, or single element to add.
Widget.Activator.remove(elements)
Remove elements from the activator.
parameters
string, Array, number, element elements A CSS selector string, array of elements, index of an element, or single element to remove.
Widget.Activator.observe(eventName, elements)
Set an event handler for an activator event. The Activator class fires mousedown and mouseup events. Event handlers are attached to the options.container if there is one, and document.body if not. If there are multiple Activators without containers, all event handlers will receive messages for all the activators. You can test to see if the element is part of this activator using the isElement method. The element for which the event was fired is in event.memo.
parameters
string eventName The name of the event. Use Widget.Activator.mousedownHandler and Widget.Activator.mouseupHandler constants.
function elements Your event handler function.
Widget.Activator.stopObserving(eventName, elements)
Remove an event handler for an activator event.
parameters
string eventName The name of the event. Use Widget.Activator.mousedownHandler and Widget.Activator.mouseupHandler constants.
function elements Your event handler function.
Widget.Activator.getElement(element)
Gets an element from the activator by index or id.
parameters
number, string element The index or id of the element to get.
returns
element The element if found, null otherwise.
Widget.Activator.getElements(elements)
Gets activator elements by index or CSS selector.
parameters
number, string, Array elements The index, CSS selector, or Array of element ids or indices to get.
returns
Array The array elements found.
Widget.Activator.isElement(element)
Determines if an element or one of it's parent elements is member of the activator's list of elements.
parameters
element element The element to test.
returns
element The element or parent element that is a member of the activator's list of elements if found, null otherwise.
Widget.Activator.setSelected(elements, selected)
(De)Selects one or more elements (and deselects all other elements if the singleSelect option is true).
parameters
number, string, Array elements The index, CSS selector, or Array of element ids or indices to select.
bool selected? If true, the elements are selected; they are deselected otherwise. (default: true)
Widget.Activator.isSelected(element)
Determines if an element is selected.
parameters
number, string element The index or id of the element to get.
returns
bool True if the element is selected, false otherwise.
Widget.Activator.getSelected()
Gets all selected elements.
returns
Array, element An array of selected elements if the singleSelect option is false. If the singleSelect option is true, returns the selected element if any, null otherwise.
Widget.Activator.setEnabled(elements, enabled)
(Dis)Enables one or more elements.
parameters
number, string, Array elements The index, CSS selector, or Array of element ids or indices to enable.
bool enabled? If true, the elements are enabled; they are disabled otherwise. (default: true)
Widget.Activator.isEnabled(element)
Determines if an element is enabled.
parameters
number, string element The index or id of the element to get.
returns
bool True if the element is enabled, false otherwise.
Widget.Activator.getDisabled()
Gets all disabled elements.
returns
Array An array of disabled elements.
Widget.Activator.selectAll(selected)
(De)Selects all elements.
parameters
bool selected? If true, the elements are selected; they are deselected otherwise. (default: true)
Widget.Activator.enableAll(enabled)
(Dis)Enables all elements.
parameters
bool enabled? If true, the elements are enabled; they are disabled otherwise. (default: true)
Widget.Activator.destroy()
Destroys the activator. Removes all event handlers and extended methods.
Objects
Generated by JsDoc Toolkit 1.4.1b on Sat, 11 Oct 2008 16:21:42 GMT.