dijit/focus (version 1.10)

dojo/Stateful, dojo/Evented

Summary

Tracks the currently focused node, and which widgets are currently "active". Access via require(["dijit/focus"], function(focus){ ... }).

A widget is considered active if it or a descendant widget has focus, or if a non-focusable node of this widget or a descendant was recently clicked.

Call focus.watch("curNode", callback) to track the current focused DOMNode, or focus.watch("activeStack", callback) to track the currently focused stack of widgets.

Call focus.on("widget-blur", func) or focus.on("widget-focus", ...) to monitor when when widgets become active/inactive

Finally, focus(node) will focus a node, suppressing errors if the node doesn't exist.

See the dijit/focus reference documentation for more information.

Property Summary

  • _attrPairNamesUsed across all instances a hash to cache attribute names and their getter and setter names.
  • activeStackList of currently active widgets (focused widget and it's ancestors)
  • curNodeCurrently focused item on screen

Method Summary

  • _changeAttrValue(name,value) Internal helper for directly changing an attribute value.
  • _get(name,names) Private function that does a get based off a hash of names
  • _getAttrNames(name) Helper function for get() and set().
  • _setStack(newStack,by) The stack of active widgets has changed.
  • emit(type,event)
  • focus(node) Focus the specified node, suppressing errors if they occur
  • get(name) Get a property on a Stateful instance.
  • on(type,listener)
  • postscript(params)
  • registerIframe(iframe) Registers listeners on the specified iframe so that any click or focus event on that iframe (or anything in it) is reported as a focus/click event on the <iframe> itself.
  • registerWin(targetWindow,effectiveNode) Registers listeners on the specified window (either the main window or an iframe's window) to detect when the user has clicked somewhere or focused somewhere.
  • set(name,value) Set a property on a Stateful instance
  • watch(name,callback) Watches a property for changes

Event Summary

Properties

_attrPairNames
Defined by: dojo/Stateful

Used across all instances a hash to cache attribute names and their getter and setter names.

activeStack
Defined by: dijit/focus

List of currently active widgets (focused widget and it's ancestors)

curNode
Defined by: dijit/focus

Currently focused item on screen

Methods

_changeAttrValue(name,value)
Defined by dojo/Stateful

Internal helper for directly changing an attribute value.

Directly change the value of an attribute on an object, bypassing any accessor setter. Also handles the calling of watch and emitting events. It is designed to be used by descendant class when there are two values of attributes that are linked, but calling .set() is not appropriate.

Parameter Type Description
name String

The property to set.
value Mixed

The value to set in the property.

Returns:function

Internal helper for directly changing an attribute value.

_get(name,names)
Defined by dojo/Stateful

Private function that does a get based off a hash of names

Parameter Type Description
name undefined
names undefined

Hash of names of custom attributes
Returns:undefined
_getAttrNames(name)
Defined by dojo/Stateful

Helper function for get() and set(). Caches attribute name values so we don't do the string ops every time.

Parameter Type Description
name undefined
Returns:undefined | object
_setStack(newStack,by)
Defined by dijit/focus

The stack of active widgets has changed. Send out appropriate events and records new stack.

Parameter Type Description
newStack String[]

array of widget id's, starting from the top (outermost) widget
by String

"mouse" if the focus/touch was caused by a mouse down event
emit(type,event)
Defined by dojo/Evented
Parameter Type Description
type undefined
event undefined
Returns:undefined
focus(node)
Defined by dijit/focus

Focus the specified node, suppressing errors if they occur

Parameter Type Description
node undefined
get(name)
Defined by dojo/Stateful

Get a property on a Stateful instance.

Get a named property on a Stateful object. The property may potentially be retrieved via a getter method in subclasses. In the base class this just retrieves the object's property.

Parameter Type Description
name String

The property to get.
Returns:any | undefined

The property value on this Stateful instance.

Examples

Example 1

require(["dojo/Stateful", function(Stateful) {
    var stateful = new Stateful({foo: 3});
    stateful.get("foo") // returns 3
    stateful.foo // returns 3
});
on(type,listener)
Defined by dojo/Evented
Parameter Type Description
type undefined
listener undefined
Returns:undefined
postscript(params)
Defined by dojo/Stateful
Parameter Type Description
params Object
Optional
registerIframe(iframe)
Defined by dijit/focus

Registers listeners on the specified iframe so that any click or focus event on that iframe (or anything in it) is reported as a focus/click event on the <iframe> itself.

Currently only used by editor.

Parameter Type Description
iframe DomNode
Returns:any | undefined

Handle with remove() method to deregister.

registerWin(targetWindow,effectiveNode)
Defined by dijit/focus

Registers listeners on the specified window (either the main window or an iframe's window) to detect when the user has clicked somewhere or focused somewhere.

Users should call registerIframe() instead of this method.

Parameter Type Description
targetWindow Window
Optional

If specified this is the window associated with the iframe, i.e. iframe.contentWindow.
effectiveNode DomNode
Optional

If specified, report any focus events inside targetWindow as an event on effectiveNode, rather than on evt.target.
Returns:any

Handle with remove() method to deregister.

set(name,value)
Defined by dojo/Stateful

Set a property on a Stateful instance

Sets named properties on a stateful object and notifies any watchers of the property. A programmatic setter may be defined in subclasses.

Parameter Type Description
name String

The property to set.
value Object

The value to set in the property.
Returns:any | function

The function returns this dojo.Stateful instance.

Examples

Example 1

require(["dojo/Stateful", function(Stateful) {
    var stateful = new Stateful();
    stateful.watch(function(name, oldValue, value){
        // this will be called on the set below
    }
    stateful.set(foo, 5);

set() may also be called with a hash of name/value pairs, ex: 

stateful.set({
    foo: "Howdy",
    bar: 3
});
});

This is equivalent to calling set(foo, "Howdy") and set(bar, 3)

watch(name,callback)
Defined by dojo/Stateful

Watches a property for changes

Parameter Type Description
name String
Optional

Indicates the property to watch. This is optional (the callback may be the only parameter), and if omitted, all the properties will be watched
callback Function

The function to execute when the property changes. This will be called after the property has been changed. The callback will be called with the |this| set to the instance, the first argument as the name of the property, the second argument as the old value and the third argument as the new value.
Returns:any | object

An object handle for the watch. The unwatch method of this object can be used to discontinue watching this property: 

var watchHandle = obj.watch("foo", callback);
watchHandle.unwatch(); // callback won't be called now

Events

_onBlurNode(node)
Defined by: dijit/focus

Called when focus leaves a node. Usually ignored, unless it isn't followed by touching another node, which indicates that we tabbed off the last field on the page, in which case every widget is marked inactive

Parameter Type Description
node DomNode

Examples

Example 1

require(["dojo/Stateful", function(Stateful) {
    var stateful = new Stateful();
    stateful.watch(function(name, oldValue, value){
        // this will be called on the set below
    }
    stateful.set(foo, 5);

set() may also be called with a hash of name/value pairs, ex: 

stateful.set({
    foo: "Howdy",
    bar: 3
});
});

This is equivalent to calling set(foo, "Howdy") and set(bar, 3)

_onFocusNode(node)
Defined by: dijit/focus

Callback when node is focused

Parameter Type Description
node DomNode

Examples

Example 1

require(["dojo/Stateful", function(Stateful) {
    var stateful = new Stateful();
    stateful.watch(function(name, oldValue, value){
        // this will be called on the set below
    }
    stateful.set(foo, 5);

set() may also be called with a hash of name/value pairs, ex: 

stateful.set({
    foo: "Howdy",
    bar: 3
});
});

This is equivalent to calling set(foo, "Howdy") and set(bar, 3)

_onTouchNode(node,by)
Defined by: dijit/focus

Callback when node is focused or touched. Note that _onFocusNode() calls _onTouchNode().

Parameter Type Description
node DomNode

The node that was touched.
by String

"mouse" if the focus/touch was caused by a mouse down event

Examples

Example 1

require(["dojo/Stateful", function(Stateful) {
    var stateful = new Stateful();
    stateful.watch(function(name, oldValue, value){
        // this will be called on the set below
    }
    stateful.set(foo, 5);

set() may also be called with a hash of name/value pairs, ex: 

stateful.set({
    foo: "Howdy",
    bar: 3
});
});

This is equivalent to calling set(foo, "Howdy") and set(bar, 3)

Error in the documentation? Can’t find what you are looking for? Let us know!