event-valuechange.js revision 07736441474adf14e00c95d5e41ed58513c47d74
/**
* Adds a synthetic <code>valueChange</code> event that fires when the
* <code>value</code> property of an input field or textarea changes as a result
* of a keystroke, mouse operation, or input method editor (IME) input event.
*
* @module event-valuechange
*/
/**
* Provides the implementation for the synthetic <code>valueChange</code> event.
*
* @class ValueChange
* @static
*/
var YArray = Y.Array,
VALUE = 'value',
// Just a simple namespace to make methods overridable.
VC = {
// -- Static Constants -----------------------------------------------------
/**
* Interval (in milliseconds) at which to poll for changes to the value of
* an element with one or more <code>valueChange</code> subscribers when the
* user is likely to be interacting with it.
*
* @property POLL_INTERVAL
* @type Number
* @default 50
* @static
*/
POLL_INTERVAL: 50,
/**
* Timeout (in milliseconds) after which to stop polling when there hasn't
* been any new activity (keypresses, mouse clicks, etc.) on an element.
*
* @property TIMEOUT
* @type Number
* @default 10000
* @static
*/
TIMEOUT: 10000,
// -- Protected Static Properties ------------------------------------------
_history : {},
_intervals: {},
_notifiers: {},
_timeouts : {},
// -- Protected Static Methods ---------------------------------------------
/**
* Called at an interval to poll for changes to the value of the specified
* node.
*
* @method _poll
* @param {Node} node
* @param {String} stamp
* @param {EventFacade} e
* @protected
* @static
*/
facade = {
_event : e,
};
});
}
},
/**
* Restarts the inactivity timeout for the specified node.
*
* @method _refreshTimeout
* @param {Node} node
* @param {String} stamp
* @protected
* @static
*/
// If we don't see any changes within the timeout period (10 seconds by
// default), stop polling.
},
/**
* Begins polling for changes to the <code>value</code> property of the
* specified node. If polling is already underway for the specified node,
* it will not be restarted unless the <i>force</i> parameter is
* <code>true</code>
*
* @method _startPolling
* @param {Node} node Node to watch.
* @param {String} stamp (optional) Object stamp for the node. Will be
* generated if not provided (provide it to improve performance).
* @param {EventFacade} e (optional) Event facade of the event that
* initiated the polling (if any).
* @param {Boolean} force (optional) If <code>true</code>, polling will be
* restarted even if we're already polling this node.
* @protected
* @static
*/
if (!stamp) {
}
// Don't bother continuing if we're already polling.
return;
}
// Poll for changes to the node's value. We can't rely on keyboard
// events for this, since the value may change due to a mouse-initiated
// paste event, an IME input event, or for some other reason that
// doesn't trigger a key event.
}, VC.POLL_INTERVAL);
},
/**
* Stops polling for changes to the specified node's <code>value</code>
* attribute.
*
* @method _stopPolling
* @param {Node} node
* @param {String} stamp (optional)
* @protected
* @static
*/
if (!stamp) {
}
},
/**
* Clears the inactivity timeout for the specified node, if any.
*
* @method _stopTimeout
* @param {Node} node
* @param {String} stamp (optional)
* @protected
* @static
*/
if (!stamp) {
}
},
// -- Protected Static Event Handlers --------------------------------------
/**
* Stops polling when a node's blur event fires.
*
* @method _onBlur
* @param {EventFacade} e
* @protected
* @static
*/
_onBlur: function (e) {
},
/**
* Resets a node's history and starts polling when a focus event occurs.
*
* @method _onFocus
* @param {EventFacade} e
* @protected
* @static
*/
_onFocus: function (e) {
var node = e.currentTarget;
},
/**
* Starts polling when a node receives a keyDown event.
*
* @method _onKeyDown
* @param {EventFacade} e
* @protected
* @static
*/
_onKeyDown: function (e) {
},
/**
* Starts polling when an IME-related keyUp event occurs on a node.
*
* @method _onKeyUp
* @param {EventFacade} e
* @protected
* @static
*/
_onKeyUp: function (e) {
// These charCodes indicate that an IME has started. We'll restart
// polling and give the IME up to 10 seconds (by default) to finish.
}
},
/**
* Starts polling when a node receives a mouseDown event.
*
* @method _onMouseDown
* @param {EventFacade} e
* @protected
* @static
*/
_onMouseDown: function (e) {
},
/**
* Called when event-valuechange receives a new subscriber.
*
* @method _onSubscribe
* @param {Node} node
* @param {Subscription} subscription
* @param {SyntheticEvent.Notifier} notifier
* @protected
* @static
*/
});
if (!notifiers) {
}
},
/**
* Called when event-valuechange loses a subscriber.
*
* @method _onUnsubscribe
* @param {Node} node
* @param {Subscription} subscription
* @param {SyntheticEvent.Notifier} notifier
* @protected
* @static
*/
if (index !== -1) {
}
}
}
};
/**
* <p>
* Synthetic event that fires when the <code>value</code> property of an input
* field or textarea changes as a result of a keystroke, mouse operation, or
* input method editor (IME) input event.
* </p>
*
* <p>
* Unlike the <code>onchange</code> event, this event fires when the value
* actually changes and not when the element loses focus. This event also
* reports IME and multi-stroke input more reliably than <code>oninput</code> or
* the various key events across browsers.
* </p>
*
* <p>
* This event is provided by the <code>event-valuechange</code> module.
* </p>
*
* <p>
* <strong>Usage example:</strong>
* </p>
*
* <code><pre>
* YUI().use('event-valuechange', function (Y) {
* Y.one('input').on('valueChange', function (e) {
* // Handle valueChange events on the first input element on the page.
* });
* });
* </pre></code>
*
* @event valueChange
* @param {EventFacade} e Event facade with the following additional
* properties:
*
* <dl>
* <dt>prevVal (String)</dt>
* <dd>
* Previous value before the latest change.
* </dd>
*
* <dt>newVal (String)</dt>
* <dd>
* New value after the latest change.
* </dd>
* </dl>
*
* @for YUI
*/
emitFacade: true
}
});
Y.ValueChange = VC;