diff --git a/packages/platform-browser/src/dom/events/event_manager.ts b/packages/platform-browser/src/dom/events/event_manager.ts index 4f245aa315..42217b304f 100644 --- a/packages/platform-browser/src/dom/events/event_manager.ts +++ b/packages/platform-browser/src/dom/events/event_manager.ts @@ -10,29 +10,60 @@ import {Inject, Injectable, InjectionToken, NgZone} from '@angular/core'; import {getDOM} from '../dom_adapter'; +/** + * The injection token for the event-manager plug-in service. + */ export const EVENT_MANAGER_PLUGINS = new InjectionToken('EventManagerPlugins'); +/** + * An injectable service that provides event management for Angular + * through a browser plug-in. + */ @Injectable() export class EventManager { private _plugins: EventManagerPlugin[]; private _eventNameToPlugin = new Map(); + /** + * Initializes an instance of the event-manager service. + */ constructor(@Inject(EVENT_MANAGER_PLUGINS) plugins: EventManagerPlugin[], private _zone: NgZone) { plugins.forEach(p => p.manager = this); this._plugins = plugins.slice().reverse(); } + /** + * Registers a handler for a specific element and event. + * + * @param element The HTML element to receive event notifications. + * @param eventName The name of the event to listen for. + * @param handler A function to call when the notification occurs. Receives the + * event object as an argument. + * @returns A callback function that can be used to remove the handler. + */ addEventListener(element: HTMLElement, eventName: string, handler: Function): Function { const plugin = this._findPluginFor(eventName); return plugin.addEventListener(element, eventName, handler); } + /** + * Registers a global handler for an event in a target view. + * + * @param target A target for global event notifications. One of "window", "document", or "body". + * @param eventName The name of the event to listen for. + * @param handler A function to call when the notification occurs. Receives the + * event object as an argument. + * @returns A callback function that can be used to remove the handler. + */ addGlobalEventListener(target: string, eventName: string, handler: Function): Function { const plugin = this._findPluginFor(eventName); return plugin.addGlobalEventListener(target, eventName, handler); } + /** + * Retrieves the compilation zone in which event listeners are registered. + */ getZone(): NgZone { return this._zone; } /** @internal */ diff --git a/packages/platform-browser/src/dom/events/hammer_gestures.ts b/packages/platform-browser/src/dom/events/hammer_gestures.ts index e51126de6c..f4f4b9c09c 100644 --- a/packages/platform-browser/src/dom/events/hammer_gestures.ts +++ b/packages/platform-browser/src/dom/events/hammer_gestures.ts @@ -12,6 +12,9 @@ import {DOCUMENT} from '../dom_tokens'; import {EventManagerPlugin} from './event_manager'; +/** + * Supported HammerJS recognizer event names. + */ const EVENT_NAMES = { // pan 'pan': true, @@ -51,8 +54,8 @@ const EVENT_NAMES = { }; /** - * A DI token that you can use to provide{@link HammerGestureConfig} to Angular. Use it to configure - * Hammer gestures. + * DI token for providing [HammerJS](http://hammerjs.github.io/) support to Angular. + * @see `HammerGestureConfig` * * @experimental */ @@ -71,14 +74,44 @@ export interface HammerInstance { } /** + * An injectable [HammerJS Manager](http://hammerjs.github.io/api/#hammer.manager) + * for gesture recognition. Configures specific event recognition. * @experimental */ @Injectable() export class HammerGestureConfig { + /** + * A set of supported event names for gestures to be used in Angular. + * Angular supports all built-in recognizers, as listed in + * [HammerJS documentation](http://hammerjs.github.io/). + */ events: string[] = []; + /** + * Maps gesture event names to a set of configuration options + * that specify overrides to the default values for specific properties. + * + * The key is a supported event name to be configured, + * and the options object contains a set of properties, with override values + * to be applied to the named recognizer event. + * For example, to disable recognition of the rotate event, specify + * `{"rotate": {"enable": false}}`. + * + * Properties that are not present take the HammerJS default values. + * For information about which properties are supported for which events, + * and their allowed and default values, see + * [HammerJS documentation](http://hammerjs.github.io/). + * + */ overrides: {[key: string]: Object} = {}; + /** + * Properties whose default values can be overridden for a given event. + * Different sets of properties apply to different events. + * For information about which properties are supported for which events, + * and their allowed and default values, see + * [HammerJS documentation](http://hammerjs.github.io/). + */ options?: { cssProps?: any; domEvents?: boolean; enable?: boolean | ((manager: any) => boolean); preset?: any[]; @@ -88,8 +121,14 @@ export class HammerGestureConfig { inputTarget?: EventTarget; }; + /** + * Creates a [HammerJS Manager](http://hammerjs.github.io/api/#hammer.manager) + * and attaches it to a given HTML element. + * @param element The element that will recognize gestures. + * @returns A HammerJS event-manager object. + */ buildHammer(element: HTMLElement): HammerInstance { - const mc = new Hammer(element, this.options); + const mc = new Hammer !(element, this.options); mc.get('pinch').set({enable: true}); mc.get('rotate').set({enable: true}); diff --git a/packages/platform-browser/src/dom/events/key_events.ts b/packages/platform-browser/src/dom/events/key_events.ts index 5d0d7f2faf..bcf26c9ec9 100644 --- a/packages/platform-browser/src/dom/events/key_events.ts +++ b/packages/platform-browser/src/dom/events/key_events.ts @@ -13,7 +13,14 @@ import {DOCUMENT} from '../dom_tokens'; import {EventManagerPlugin} from './event_manager'; +/** + * Defines supported modifiers for key events. + */ const MODIFIER_KEYS = ['alt', 'control', 'meta', 'shift']; + +/** + * Retrieves modifiers from key-event objects. + */ const MODIFIER_KEY_GETTERS: {[key: string]: (event: KeyboardEvent) => boolean} = { 'alt': (event: KeyboardEvent) => event.altKey, 'control': (event: KeyboardEvent) => event.ctrlKey, @@ -23,13 +30,31 @@ const MODIFIER_KEY_GETTERS: {[key: string]: (event: KeyboardEvent) => boolean} = /** * @experimental + * A browser plug-in that provides support for handling of key events in Angular. */ @Injectable() export class KeyEventsPlugin extends EventManagerPlugin { + /** + * Initializes an instance of the browser plug-in. + * @param doc The document in which key events will be detected. + */ constructor(@Inject(DOCUMENT) doc: any) { super(doc); } + /** + * Reports whether a named key event is supported. + * @param eventName The event name to query. + * @return True if the named key event is supported. + */ supports(eventName: string): boolean { return KeyEventsPlugin.parseEventName(eventName) != null; } + /** + * Registers a handler for a specific element and key event. + * @param element The HTML element to receive event notifications. + * @param eventName The name of the key event to listen for. + * @param handler A function to call when the notification occurs. Receives the + * event object as an argument. + * @returns The key event that was registered. + */ addEventListener(element: HTMLElement, eventName: string, handler: Function): Function { const parsedEvent = KeyEventsPlugin.parseEventName(eventName) !; @@ -93,6 +118,13 @@ export class KeyEventsPlugin extends EventManagerPlugin { return fullKey; } + /** + * Configures a handler callback for a key event. + * @param fullKey The event name that combines all simultaneous keystrokes. + * @param handler The function that responds to the key event. + * @param zone The zone in which the event occurred. + * @returns A callback function. + */ static eventCallback(fullKey: any, handler: Function, zone: NgZone): Function { return (event: any /** TODO #9100 */) => { if (KeyEventsPlugin.getEventFullKey(event) === fullKey) {