Class glow.ui.Focusable

Extends glow.ui.Behaviour.

Defined in: ui.js.

Class Summary
Constructor Attributes	Constructor Name and Description
	glow.ui.Focusable(container, opts) Manage a focusable element, or group of elements This can be used to create a single focus point for a set of focusable elements.

Field Summary
Field Attributes	Field Name and Description
	activeChild The active child item.
	activeIndex The index of the active child item in glow.ui.Focusable#children.
	children NodeList of child items that are managed by this Focusable.
	container Focusable container

Method Summary
Method Attributes	Method Name and Description
	active(toActivate) Get/set the active state of the Focusable Call without arguments to get the active state.
	destroy() Destroy the Focusable This removes all focusable behaviour from the continer and child items.
	disabled(newState) Enable/disable the Focusable, or get the disabled state When the Focusable is disabled, it (and its child items) cannot be activated or receive focus.
	modal(setModal) Get/set modality When a Focusable is modal it cannot be deactivated, focus cannot be given to elements outside of it until modal set to false.
	next() Activate next child item.
	prev() Activate previous child item Has no effect on an inactive Focusable.

Methods borrowed from class glow.ui.Behaviour:: enabled
Methods borrowed from class glow.events.Target:: detach, fire, on

Event Summary
Event Attributes	Event Name and Description
	activate(event) Fires when the Focusable becomes active Cancelling this event prevents the Focusable being actived
	childActivate(event) Fires when a child item of the Focusable becomes active Cancelling this event prevents the child item being actived
	deactivate(event) Fires when the Focusable becomes deactive Cancelling this event prevents the Focusable being deactived
	select(event) Fires when a child of the Focusable is selected.

Class Detail

glow.ui.Focusable(container, opts)

Manage a focusable element, or group of elements This can be used to create a single focus point for a set of focusable elements. Eg, a menu can have a single tab stop, and the arrow keys can be used to cycle through menu items. This means the user doesn't have to tab through every item in the menu to get to the next set of focusable items. The FocusManager can also be used to make a element 'modal', ensuring focus doesn't go to elements outside it. The aim of this behaviour is to make it easier to conform to ARIA best practices for keyboard navigation

			// A collection of buttons
			glow('#toolbar').focusable({
				children: '> li.button'
			});
			
			// The #toolbar now appears in tab order.
			// Once focused, the left & right arrow keys navigate between
			// buttons.

			// A modal dialog
			var dialog = glow('#dialog').hide();
			var focusable = dialog.focusable();
			
			glow('#openDialog').on('click', function() {
				dialog.show();
				focusable.modal(true);
			});
			
			glow('#closeDialog').on('click', function() {
				dialog.hide();
				focusable.modal(false);
			});

Parameters:
{glow.NodeList|string} container: Parent focusable element of the group If tabindex isn't set on this element, it will be given tabindex="0", allowing the element to be focused using the tab key.
{object} opts Optional: Options
{string} opts.children Optional: Selector for child items that can be active These can be cycled through using the arrow keys when the Focusable or one of its children is active (usually when it has focus).
{function|string} opts.keyboardNav Optional, Default: 'arrows': Alter the default keyboard behaviour. If 'arrows-x', the left & right arrow keys trigger {@link glow.ui.Focusable#next Focusable#next} and {@link glow.ui.Focusable#prev Focusable#prev} respectively. If 'arrows-y', the up & down arrow keys trigger {@link glow.ui.Focusable#next Focusable#next} and {@link glow.ui.Focusable#prev Focusable#prev} respectively. 'arrows' is a combination of the two. If a function is provided, it will be passed a glow.events.KeyboardEvent object. Use {@link glow.ui.Focusable#next Focusable#next}, {@link glow.ui.Focusable#prev Focusable#prev} or {@link glow.ui.Focusable#activate Focusable#activate} to react to the key event. 'this' inside this function refers to the Focusable.
{boolean} opts.setFocus Optional, Default: true: Sets whether focus is given to the active element. You need to set this to false if you want focus to remain in another element.
{string} opts.activeChildClass Optional, Default: 'active': Class name to give the active child element.
{boolean} opts.activateOnHover Optional, Default: false: Activate items on hover?
{boolean} opts.loop Optional, Default: false: Loop from the last child item to the first (and vice-versa)? When this is true, calling {@link glow.ui.Focusable#next Focusable#next} when the last focusable item is active will activate the first.

Field Detail

{glow.NodeList} activeChild

The active child item. This will be an empty NodeList if no child is active

{number} activeIndex

The index of the active child item in glow.ui.Focusable#children. This will be undefined if no child is active.

{glow.NodeList} children

NodeList of child items that are managed by this Focusable. This will be an empty nodelist if the focusable has no children

{glow.NodeList} container

Focusable container

Method Detail

{glow.ui.Focusable|boolean} active(toActivate)

Get/set the active state of the Focusable Call without arguments to get the active state. Call with arguments to set the active element. A Focusable will be activated automatically when it receieves focus.

Parameters:
{number|glow.NodeList|boolean} toActivate Optional: Item to activate. Numbers will be treated as an index of {@link glow.ui.FocusManager#children children}. 'true' will activate the container, but none of the children. 'false' will deactivate the container and any active child

Returns:: {glow.ui.Focusable|boolean} Returns boolean when getting, Focusable when setting

destroy()

Destroy the Focusable This removes all focusable behaviour from the continer and child items. The elements themselves will not be destroyed.

Returns:: this

{glow.ui.Focusable|boolean} disabled(newState)

Enable/disable the Focusable, or get the disabled state When the Focusable is disabled, it (and its child items) cannot be activated or receive focus.

Parameters:
{boolean} newState Optional: Disable the focusable? 'false' will enable a disabled focusable.

Returns:: {glow.ui.Focusable|boolean} Returns boolean when getting, Focusable when setting

modal(setModal)

Get/set modality When a Focusable is modal it cannot be deactivated, focus cannot be given to elements outside of it until modal set to false.

Parameters:
{boolean} setModal: New modal value

Returns:: this when setting, true/false when getting

next()

Activate next child item. Has no effect on an inactive Focusable.

Returns:: this

prev()

Activate previous child item Has no effect on an inactive Focusable.

Returns:: this

Event Detail

activate(event)

Fires when the Focusable becomes active Cancelling this event prevents the Focusable being actived

Parameters:
{glow.events.Event} event: Event Object

childActivate(event)

Fires when a child item of the Focusable becomes active Cancelling this event prevents the child item being actived

Parameters:
{glow.events.Event} event: Event Object
{glow.NodeList} event.item: Item activated.
{number} event.itemIndex: The index of the activated item in glow.ui.Focusable#children.
{string} event.method: Either 'key', 'hover' or 'api' depending on how the item was activated. This allows you to react to certain kinds of activation.
{glow.events.DomEvent} event.methodEvent Optional: An event object for the 'key' or 'hover' event. For 'key' methods this will be a more specific glow.events.KeyboardEvent. If the method was neither 'key' or 'hover', methodEvent will be undefined.

deactivate(event)

Fires when the Focusable becomes deactive Cancelling this event prevents the Focusable being deactived

Parameters:
{glow.events.Event} event: Event Object

select(event)

Fires when a child of the Focusable is selected. Items are selected by clicking, or pressing enter when a child is active. Cancelling this event prevents the default click/key action.

Parameters:
{glow.events.Event} event: Event Object
{glow.NodeList} event.item: Item selected.
{number} event.itemIndex: The index of the selected item in glow.ui.Focusable#children.

Classes

Class glow.ui.Focusable