From db8c6b7997a689a6aec02ede8abe369f6eeae92b Mon Sep 17 00:00:00 2001 From: Leon Yu Date: Wed, 18 Nov 2015 04:06:07 -0500 Subject: [PATCH] ZeroCLipboard 2.x.x and jsdoc Test for 1.x.x Fix encoding Fix styling Code review --- zeroclipboard/zeroclipboard-1.x.x-tests.ts | 158 ++++++ zeroclipboard/zeroclipboard-1.x.x.d.ts | 79 +++ zeroclipboard/zeroclipboard-tests.ts | 542 ++++++++++++++++++++ zeroclipboard/zeroclipboard.d.ts | 554 ++++++++++++++++++--- 4 files changed, 1271 insertions(+), 62 deletions(-) create mode 100644 zeroclipboard/zeroclipboard-1.x.x-tests.ts create mode 100644 zeroclipboard/zeroclipboard-1.x.x.d.ts create mode 100644 zeroclipboard/zeroclipboard-tests.ts diff --git a/zeroclipboard/zeroclipboard-1.x.x-tests.ts b/zeroclipboard/zeroclipboard-1.x.x-tests.ts new file mode 100644 index 0000000000..e087561f67 --- /dev/null +++ b/zeroclipboard/zeroclipboard-1.x.x-tests.ts @@ -0,0 +1,158 @@ +/// +/// + +// main.js +var client = new ZeroClipboard( document.getElementById("copy-button"), { + moviePath: "/path/to/ZeroClipboard.swf" +} ); + +client.on( "load", function(client) { + // alert( "movie is loaded" ); + + client.on( "complete", function(client, args) { + // `this` is the element that was clicked + this.style.display = "none"; + alert("Copied text to clipboard: " + args.text ); + } ); +} ); + +ZeroClipboard.config( { moviePath: 'http://YOURSERVER/path/ZeroClipboard.swf' } ); + +var client = new ZeroClipboard(); + +var client = new ZeroClipboard($(".copy-button")); + +var _globalConfig = { + // NOTE: For versions >= v1.3.x and < v2.x, you must use `swfPath` by setting `moviePath`: + // `ZeroClipboard.config({ moviePath: ZeroClipboard.config("swfPath") });` + // URL to movie, relative to the page. Default value will be "ZeroClipboard.swf" under the + // same path as the ZeroClipboard JS file. + swfPath: "path/to/ZeroClipboard.swf", + + // SWF inbound scripting policy: page domains that the SWF should trust. (single string or array of strings) + trustedDomains: [window.location.host], + + // Include a "nocache" query parameter on requests for the SWF + cacheBust: true, + + // Forcibly set the hand cursor ("pointer") for all clipped elements + forceHandCursor: false, + + // The z-index used by the Flash object. Max value (32-bit): 2147483647 + zIndex: 999999999, + + // Debug enabled: send `console` messages with deprecation warnings, etc. + debug: true, + + // Sets the title of the `div` encapsulating the Flash object + title: 'div', + + // Setting this to `false` would allow users to handle calling `ZeroClipboard.activate(...);` + // themselves instead of relying on our per-element `mouseover` handler + autoActivate: true, + + + /** @deprecated */ + // The class used to indicate that a clipped element is being hovered over + hoverClass: "zeroclipboard-is-hover", + + /** @deprecated */ + // The class used to indicate that a clipped element is active (is being clicked) + activeClass: "zeroclipboard-is-active", + + /** @deprecated */ + // DEPRECATED!!! Use `trustedDomains` instead! + // SWF inbound scripting policy: page origins that the SWF should trust. (single string or array of strings) + trustedOrigins: ['origin'], + + /** @deprecated */ + // SWF outbound scripting policy. Possible values: "never", "sameDomain", "always" + allowScriptAccess: 'always', + + /** @deprecated */ + // Include a "nocache" query parameter on requests for the SWF + useNoCache: true, + + /** @deprecated */ + // URL to movie + moviePath: "ZeroClipboard.swf" +}; + +ZeroClipboard.config(_globalConfig); + +ZeroClipboard.config({ moviePath: "new/path" }); + +var client = new ZeroClipboard($("#d_clip_button"), { moviePath: "new/path" }); +client.on( 'dataRequested', function (client, args) { + client.setText( "Copy me!" ); + }); + +client.setText( "Copy me!" ); + +client.clip( document.getElementById('d_clip_button') ); + +var client = new ZeroClipboard( $("button#my-button") ); + +function my_load_handler() { + +} + +client.on( 'load', my_load_handler ); + +client.off( 'load', my_load_handler ); + +client.on( 'load', function ( client, args ) { + alert( "movie has loaded" ); +}); + +client.on( 'mouseover', function ( client, args ) { + alert( "mouse is over movie" ); +}); + +client.on( 'mouseout', function ( client, args ) { + alert( "mouse has left movie" ); +} ); + +client.on( 'mousedown', function ( client, args ) { + alert( "mouse button is down" ); +} ); + +client.on( 'mouseup', function ( client, args ) { + alert( "mouse button is up" ); +} ); + +client.on( 'complete', function ( client, args ) { + alert("Copied text to clipboard: " + args.text ); +} ); + +client.on( 'noflash', function ( client, args ) { + alert("You don't support flash"); +} ); + +client.on( 'wrongflash', function ( client, args ) { + alert("Your flash is too old " + args.flashVersion); +} ); + +client.on( 'dataRequested', function ( client, args ) { + client.setText( 'Copied to clipboard.' ); +} ); + +var client = new ZeroClipboard( $('.clip_button') ); + +client.on( 'load', function(client) { + // alert( "movie is loaded" ); + + client.on( 'datarequested', function(client) { + client.setText(this.innerHTML); + } ); + + client.on( 'complete', function(client, args) { + alert("Copied text to clipboard: " + args.text ); + } ); +} ); + +client.on( 'wrongflash noflash', function() { + ZeroClipboard.destroy(); +}); + +ZeroClipboard.config({ debug: false }); diff --git a/zeroclipboard/zeroclipboard-1.x.x.d.ts b/zeroclipboard/zeroclipboard-1.x.x.d.ts new file mode 100644 index 0000000000..4305c18bcf --- /dev/null +++ b/zeroclipboard/zeroclipboard-1.x.x.d.ts @@ -0,0 +1,79 @@ +// Type definitions for ZeroClipboard v1.x.x +// Project: https://github.com/jonrohan/ZeroClipboard +// Definitions by: Eric J. Smith , Blake Niemyjski , György Balássy , Leon Yu +// Definitions: https://github.com/borisyankov/DefinitelyTyped + +declare class ZeroClipboard { + constructor(elements?: Element | { [index: number]: Element }, options?: ZeroClipboardOptions); + + activate(element: Element): void; + setText(newText: string): void; + title(newTitle: string): void; + setSize(width: number, height: number): void; + version: string; + moviePath: string; + trustedDomains: any; + text: string; + hoverClass: string; + activeClass: string; + deactivate(): void; + ready: boolean; + reposition(): void; // returns false in some scenarios, but never returns true + on(eventName: string, func: (client: ZeroClipboard, args: any) => void): void; + off(eventName: string, func: (client: ZeroClipboard, args: any) => void): void; + clip(elements: Element | { [index: number]: Element }): void; + unclip(elements: Element | { [index: number]: Element }): void; + + + static config(options: ZeroClipboardOptions): void; + static destroy(): void; + static emit(eventName: string, args: any): void; +} + +interface ZeroClipboardOptions { + + /** Setting this to false would allow users to handle calling ZeroClipboard.activate(...); themselves instead of relying on our per-element mouseover handler */ + autoActivate?: boolean; + + /** Include a "nocache" query parameter on requests for the SWF. */ + cacheBust?: boolean; + + /** Debug enabled: send console messages with deprecation warnings, etc. */ + debug?: boolean; + + /** Forcibly set the hand cursor ("pointer") for all clipped elements. */ + forceHandCursor?: boolean; + + /** URL to the movie. NOTE: For versions >= v1.3.x and < v2.x, you must use swfPath by setting moviePath! */ + moviePath?: string; + + /** URL to the movie, relative to the page. NOTE: For versions >= v1.3.x and < v2.x, you must use swfPath by setting moviePath! */ + swfPath?: string; + + /** Forcibly set the hand cursor ("pointer") for all clipped elements. */ + trustedDomains?: any; + + /** Sets the title of the div encapsulating the Flash object. */ + title?: string; + + /** The z-index used by the Flash object. */ + zIndex?: number; + + /** DEPRECATED. The class used to indicate that a clipped element is active (is being clicked). */ + activeClass?: string; + + /** DEPRECATED. The class used to indicate that a clipped element is being hovered over. */ + hoverClass?: string; + + /** DEPRECATED. SWF outbound scripting policy. Possible values: "never", "sameDomain", "always". */ + allowScriptAccess?: string; + + /** DEPRECATED, use trustedDomains instead! SWF inbound scripting policy: page origins that the SWF should trust. (single string or array of strings. */ + trustedOrigins?: any; + + /** DEPRECATED, use cacheBust instead! Include a "nocache" query parameter on requests for the SWF. */ + useNoCache?: boolean; +} + +// Support AMD. +declare module "zeroclipboard" { export = ZeroClipboard; } diff --git a/zeroclipboard/zeroclipboard-tests.ts b/zeroclipboard/zeroclipboard-tests.ts new file mode 100644 index 0000000000..26855210da --- /dev/null +++ b/zeroclipboard/zeroclipboard-tests.ts @@ -0,0 +1,542 @@ +/// +/// + +import ZeroClipboard = require("zeroclipboard"); +// import * as ZeroClipboard from "zeroclipboard"; + +namespace SimpleExample { + ZeroClipboard.config( { swfPath: "http://YOURSERVER/path/ZeroClipboard.swf" } ); + + let client = new ZeroClipboard(document.getElementById("copy-button")); + let client2 = new ZeroClipboard(jQuery('.copy-button')); + + client.on( "ready", function( readyEvent ) { + // alert( "ZeroClipboard SWF is ready!" ); + + client.on( "aftercopy", function( event ) { + this === client; + event.target === document.getElementById('el') + event.target.style.display = "none"; + alert("Copied text to clipboard: " + event.data["text/plain"] ); + }); + }); + + client.on( "copy", function (event) { + var clipboard = event.clipboardData; + clipboard.setData( "text/plain", "Copy me!" ); + clipboard.setData( "text/html", "Copy me!" ); + clipboard.setData( "application/rtf", "{\\rtf1\\ansi\n{\\b Copy me!}}" ); + }); + + ZeroClipboard.setData( "text/plain", "Copy me!" ); + + client.setText( "Copy me!" ); + + client.clip( document.getElementById("d_clip_button") ); + + var $client = new ZeroClipboard( $("button#my-button") ); + + function example() { + var client = new ZeroClipboard( $('.clip_button') ); + + client.on( 'ready', function(event) { + // console.log( 'movie is loaded' ); + + client.on( 'copy', function(event) { + event.clipboardData.setData('text/plain', event.target.innerHTML); + } ); + + client.on( 'aftercopy', function(event) { + console.log('Copied text to clipboard: ' + event.data['text/plain']); + } ); + } ); + + client.on( 'error', function(event) { + // console.log( 'ZeroClipboard error of type "' + event.name + '": ' + event.message ); + ZeroClipboard.destroy(); + } ); + } + + ZeroClipboard.config({ + fixLineEndings: false + }); + + ZeroClipboard.config({ + forceEnhancedClipboard: true + }); + +} + +namespace Static { + var version:String = ZeroClipboard.version; + + var config = ZeroClipboard.config(); + + var swfPath:String = ZeroClipboard.config("swfPath"); + + ZeroClipboard.config({}); + + ZeroClipboard.destroy(); + + ZeroClipboard.setData("text/plain", "Blah"); + + ZeroClipboard.setData({ + "text/plain": "Blah", + "text/html": "Blah" + }); + + ZeroClipboard.clearData("text/plain"); + + var text:String = ZeroClipboard.getData("text/plain"); + + var dataObj = ZeroClipboard.getData(); + + ZeroClipboard.focus(document.getElementById("d_clip_button")); + + ZeroClipboard.blur(); + + var el = document.getElementById("d_clip_button"); + ZeroClipboard.focus(el); + var activeEl = ZeroClipboard.activeElement(); + activeEl === el; + + ZeroClipboard.state(); + + let b:boolean = ZeroClipboard.isFlashUnusable(); + + var listenerFn = function(e: Object) { var ZeroClipboard = this; /* ... */ }; + ZeroClipboard.on("ready", listenerFn); + + var listenerObj = { + handleEvent: function(e: Object) { var listenerObj = this; /* ... */ } + }; + ZeroClipboard.on("error", listenerObj); + + ZeroClipboard.on("ready error", function(e) { /* ... */ }); + + ZeroClipboard.on({ + "ready": function(e) { /* ... */ }, + "error": function(e) { /* ... */ } + }); + + ZeroClipboard.off("ready", listenerFn); + ZeroClipboard.off("error", listenerObj); + + ZeroClipboard.off("ready error", listenerFn); + + ZeroClipboard.off({ + "ready": function(e) { /* ... */ }, + "error": function(e) { /* ... */ } + }); + + ZeroClipboard.off("ready"); + + ZeroClipboard.off(); + + ZeroClipboard.emit("ready"); + ZeroClipboard.emit({ + type: "error", + name: "flash-disabled" + }); + + var pendingCopyData = ZeroClipboard.emit("copy"); + + var listener = ZeroClipboard.handlers("ready"); + + var listeners = ZeroClipboard.handlers(); + + var currentlyActivatedElementOrNull = document.getElementById('currentlyActivatedElementOrNull'); + var dataClipboardElementTargetOfCurrentlyActivatedElementOrNull = document.getElementById('dataClipboardElementTargetOfCurrentlyActivatedElementOrNull') + var flashSwfObjectRef = document.getElementById('flashSwfObjectRef') as HTMLObjectElement; + + ZeroClipboard.on("ready", function(e) { + e = { + type: "ready", + message: "Flash communication is established", + target: currentlyActivatedElementOrNull, + relatedTarget: dataClipboardElementTargetOfCurrentlyActivatedElementOrNull, + currentTarget: flashSwfObjectRef, + version: "11.2.202", + timeStamp: Date.now() + }; + }); + + ZeroClipboard.on("beforecopy", function(e) { + e = { + type: "beforecopy", + target: currentlyActivatedElementOrNull, + relatedTarget: dataClipboardElementTargetOfCurrentlyActivatedElementOrNull, + currentTarget: flashSwfObjectRef, + timeStamp: Date.now() + }; + }); + + ZeroClipboard.on("copy", function(e) { + e.clipboardData.setData('text/html','
'); + e.clipboardData.setData({'text/html':'
'}); + e = { + type: "copy", + target: currentlyActivatedElementOrNull, + relatedTarget: dataClipboardElementTargetOfCurrentlyActivatedElementOrNull, + currentTarget: flashSwfObjectRef, + timeStamp: Date.now(), + clipboardData: { + setData: ZeroClipboard.setData, + clearData: ZeroClipboard.clearData + } + }; + }); + + + ZeroClipboard.on("aftercopy", function(e) { + e = { + type: "aftercopy", + target: currentlyActivatedElementOrNull, + relatedTarget: dataClipboardElementTargetOfCurrentlyActivatedElementOrNull, + currentTarget: flashSwfObjectRef, + timeStamp: Date.now(), + success: { + "text/plain": true, + "text/html": true, + "application/rtf": false + }, + data: { + "text/plain": "Blah", + "text/html": "Blah", + "application/rtf": "{\\rtf1\\ansi\n{\\b Blah}}" + }, + errors: [ + { + name: "SecurityError", + message: "Clipboard security error OMG", + errorID: 7320, + stack: null, + format: "application/rtf", + clipboard: "desktop" + } + ] + }; + }); + + ZeroClipboard.on("destroy", function(e) { + e = { + type: "destroy", + target: null, + relatedTarget: null, + currentTarget: flashSwfObjectRef, + timeStamp: Date.now(), + success: { + "text/plain": true, + "text/html": true, + "application/rtf": false + }, + data: { + "text/plain": "Blah", + "text/html": "Blah", + "application/rtf": "{\\rtf1\\ansi\n{\\b Blah}}" + } + }; + }); + + ZeroClipboard.on("error", function(e) { + e = { + type: "error", + name: "flash-disabled", + message: "Flash is disabled or not installed. May also be attempting to run Flash in a sandboxed iframe, which is impossible.", + target: null, + relatedTarget: null, + currentTarget: flashSwfObjectRef, + timeStamp: Date.now(), + minimumVersion: "11.0.0" + }; + }); + + ZeroClipboard.on("error", function(e) { + e = { + type: "error", + name: "flash-sandboxed", + message: "Attempting to run Flash in a sandboxed iframe, which is impossible", + target: null, + relatedTarget: null, + currentTarget: flashSwfObjectRef, + timeStamp: Date.now(), + minimumVersion: "11.0.0", + version: "11.2.202" + }; + }); + + ZeroClipboard.on("error", function(e) { + e = { + type: "error", + name: "flash-unavailable", + message: "Flash is unable to communicate bidirectionally with JavaScript", + target: null, + relatedTarget: null, + currentTarget: flashSwfObjectRef, + timeStamp: Date.now(), + minimumVersion: "11.0.0", + version: "11.2.202" + }; + }); + + ZeroClipboard.on("error", function(e) { + e = { + type: "error", + name: "flash-degraded", + message: "Flash is unable to preserve data fidelity when communicating with JavaScript", + target: null, + relatedTarget: null, + currentTarget: flashSwfObjectRef, + timeStamp: Date.now(), + minimumVersion: "11.0.0", + version: "11.2.202" + }; + }); + + ZeroClipboard.on("error", function(e) { + e = { + type: "error", + name: "flash-deactivated", + message: "Flash is too outdated for your browser and/or is configured as click-to-activate. This may also mean that the ZeroClipboard SWF object could not be loaded, so please check your `swfPath` configuration and/or network connectivity. May also be attempting to run Flash in a sandboxed iframe, which is impossible.", + target: null, + relatedTarget: null, + currentTarget: flashSwfObjectRef, + timeStamp: Date.now(), + minimumVersion: "11.0.0", + version: "11.2.202" + }; + }); + + ZeroClipboard.on("error", function(e) { + e = { + type: "error", + name: "flash-overdue", + message: "Flash communication was established but NOT within the acceptable time limit", + target: null, + relatedTarget: null, + currentTarget: flashSwfObjectRef, + timeStamp: Date.now(), + minimumVersion: "11.0.0", + version: "11.2.202" + }; + }); + + ZeroClipboard.on("error", function(e) { + e = { + type: "error", + name: "version-mismatch", + message: "ZeroClipboard JS version number does not match ZeroClipboard SWF version number", + target: null, + relatedTarget: null, + currentTarget: flashSwfObjectRef, + timeStamp: Date.now(), + jsVersion: "2.2.1", + swfVersion: "2.2.0" + }; + }); + + ZeroClipboard.on("error", function(e) { + e = { + type: "error", + name: "clipboard-error", + message: "At least one error was thrown while ZeroClipboard was attempting to inject your data into the clipboard", + target: currentlyActivatedElementOrNull, + relatedTarget: dataClipboardElementTargetOfCurrentlyActivatedElementOrNull, + currentTarget: flashSwfObjectRef, + timeStamp: Date.now(), + data: { + "text/plain": "Blah", + "text/html": "Blah", + "application/rtf": "{\\rtf1\\ansi\n{\\b Blah}}" + }, + errors: [ + { + name: "SecurityError", + message: "Clipboard security error OMG", + errorID: 7320, + stack: null, + format: "application/rtf", + clipboard: "desktop" + } + ] + }; + }); + + ZeroClipboard.on("error", function(e) { + e = { + type: "error", + name: "config-mismatch", + message: "ZeroClipboard configuration does not match Flash's reality", + target: null, + relatedTarget: null, + currentTarget: flashSwfObjectRef, + timeStamp: Date.now(), + property: "swfObjectId", + configuredValue: "my-zeroclipboard-object", + actualValue: "global-zeroclipboard-flash-bridge" + }; + }); + + ZeroClipboard.on("error", function(e) { + e = { + type: "error", + name: "swf-not-found", + message: "The ZeroClipboard SWF object could not be loaded, so please check your `swfPath` configuration and/or network connectivity", + target: null, + relatedTarget: null, + currentTarget: flashSwfObjectRef, + timeStamp: Date.now() + }; + }); +} + +namespace Instance { + var clippedEl = document.getElementById("d_clip_button"); + var client = new ZeroClipboard(clippedEl); + + client.setText("Blah"); + + client.setHtml("Blah"); + + client.setRichText("{\\rtf1\\ansi\n{\\b Blah}}"); + + client.setData("text/plain", "Blah"); + client.setData({ + "text/plain": "Blah", + "text/html": "Blah" + }); + + client.clearData("text/plain"); + client.clearData(); + + var text:String = client.getData("text/plain"); + var dataObj = client.getData(); + + client.clip(document.getElementById("d_clip_button")) + client.clip(document.querySelectorAll(".clip_button")); + client.clip(jQuery(".clip_button")); + + client.unclip(document.getElementById("d_clip_button")) + client.unclip(document.querySelectorAll(".clip_button")); + client.unclip(jQuery(".clip_button")); + client.unclip(); + + var els:HTMLElement[] = client.elements(); + + var listenerFn = function(e: Object) { var client = this; /* ... */ }; + client.on("ready", listenerFn); + + var listenerObj = { + handleEvent: function(e: Object) { var listenerObj = this; /* ... */ } + }; + client.on("error", listenerObj); + + client.on("ready error", function(e) { /* ... */ }); + + client.on({ + "ready": function(e) { /* ... */ }, + "error": function(e) { /* ... */ } + }); + + client.off("ready", listenerFn); + client.off("error", listenerObj); + + client.off("ready error", listenerFn); + + client.off({ + "ready": function(e) { /* ... */ }, + "error": function(e) { /* ... */ } + }); + + client.off("ready"); + + client.off(); + + client.emit("ready"); + client.emit({ + type: "error", + name: "flash-disabled" + }); + + var readyListeners = client.handlers("ready"); + + var listeners = client.handlers(); + + var client = new ZeroClipboard(); + client.on("ready", function(e) { + if (e.client === client && client === this) { + console.log("This client instance is ready!"); + } + }); +} + +namespace GlobalConfig { + var _globalConfig = { + + // SWF URL, relative to the page. Default value will be "ZeroClipboard.swf" + // under the same path as the ZeroClipboard JS file. + swfPath: '_swfPath', + + // SWF inbound scripting policy: page domains that the SWF should trust. + // (single string, or array of strings) + trustedDomains: window.location.host ? [window.location.host] : [], + + // Include a "noCache" query parameter on requests for the SWF. + cacheBust: true, + + // Enable use of the fancy "Desktop" clipboard, even on Linux where it is + // known to suck. + forceEnhancedClipboard: false, + + // How many milliseconds to wait for the Flash SWF to load and respond before assuming that + // Flash is deactivated (e.g. click-to-play) in the user's browser. If you don't care about + // how long it takes to load the SWF, you can set this to `null`. + flashLoadTimeout: 30000, + + // Setting this to `false` would allow users to handle calling `ZeroClipboard.focus(...);` + // themselves instead of relying on our per-element `mouseover` handler. + autoActivate: true, + + // Bubble synthetic events in JavaScript after they are received by the Flash object. + bubbleEvents: true, + + // Ensure OS-compliant line endings, i.e. "\r\n" on Windows, "\n" elsewhere + fixLineEndings: true, + + // Sets the ID of the `div` encapsulating the Flash object. + // Value is validated against the [HTML4 spec for `ID` tokens][valid_ids]. + containerId: "global-zeroclipboard-html-bridge", + + // Sets the class of the `div` encapsulating the Flash object. + containerClass: "global-zeroclipboard-container", + + // Sets the ID and name of the Flash `object` element. + // Value is validated against the [HTML4 spec for `ID` and `Name` tokens][valid_ids]. + swfObjectId: "global-zeroclipboard-flash-bridge", + + // The class used to indicate that a clipped element is being hovered over. + hoverClass: "zeroclipboard-is-hover", + + // The class used to indicate that a clipped element is active (is being clicked). + activeClass: "zeroclipboard-is-active", + + + + // Forcibly set the hand cursor ("pointer") for all clipped elements. + // IMPORTANT: This configuration value CAN be modified while a SWF is actively embedded. + forceHandCursor: false, + + // Sets the title of the `div` encapsulating the Flash object. + // IMPORTANT: This configuration value CAN be modified while a SWF is actively embedded. + title: 'title', + + // The z-index used by the Flash object. + // Max value (32-bit): 2147483647. + // IMPORTANT: This configuration value CAN be modified while a SWF is actively embedded. + zIndex: 999999999 + + }; + + ZeroClipboard.config(_globalConfig); + +} diff --git a/zeroclipboard/zeroclipboard.d.ts b/zeroclipboard/zeroclipboard.d.ts index 6db1ba180d..2a192a71e9 100644 --- a/zeroclipboard/zeroclipboard.d.ts +++ b/zeroclipboard/zeroclipboard.d.ts @@ -1,75 +1,505 @@ -// Type definitions for ZeroClipboard -// Project: https://github.com/jonrohan/ZeroClipboard -// Definitions by: Eric J. Smith , Blake Niemyjski , György Balássy -// Definitions: https://github.com/borisyankov/DefinitelyTyped +// Type definitions for ZeroClipboard v2.x.x +// Project: https://github.com/zeroclipboard/zeroclipboard +// Definitions by: Eric J. Smith , Blake Niemyjski , György Balássy , Leon Yu +// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped -declare class ZeroClipboard { - constructor(elements?: any, options?: ZeroClipboardOptions); - activate(element: any): void; - setText(newText: string): void; - title(newTitle: string): void; - setSize(width: number, height: number): void; +declare namespace ZC { + // Basic collection types for shorthands and interoperation + interface List { [index: number]: T; length: number; } + interface Dictionary { [key: string]: T; } + + // Generic version EventHandler containers. + // Mimicking native interfaces in lib.dom.d.ts of the same name. + interface EventListener { (ev: T): void; } + interface EventListenerObject { handleEvent(ev: T): void; } + type EventListenerOrEventListenerObject = EventListener | EventListenerObject; + + export interface ZeroClipboardStatic extends ZeroClipboardCommon { + new(elements?: Element | List): ZeroClipboardClient; + + /** + * The version of the ZeroClipboard library being used, e.g. "2.0.0". + * @type {string} + */ version: string; - moviePath: string; - trustedDomains: any; - text: string; - hoverClass: string; - activeClass: string; + /** + * Get a copy of the active configuration for ZeroClipboard. + * @return {ZeroClipboardConfig} + */ + config(): ZeroClipboardConfig; + /** + * Get a copy of the actively configured value for this configuration property for ZeroClipboard. + * @param {string} propName + * @return {any} + */ + config(propName: string): any; + config(propName: "swfPath"): string; + config(propName: "trustedDomains"): string[]; + config(propName: "cacheBust"): boolean; + config(propName: "forceEnhancedClipboard"): boolean; + config(propName: "flashLoadTimeout"): number; + config(propName: "autoActivate"): boolean; + config(propName: "bubbleEvents"): boolean; + config(propName: "fixLineEndings"): boolean; + config(propName: "containerId"): string; + config(propName: "containerClass"): string; + config(propName: "swfObjectId"): string; + config(propName: "hoverClass"): string; + config(propName: "activeClass"): string; + config(propName: "forceHandCursor"): boolean; + config(propName: "title"): string; + config(propName: "zIndex"): number; + /** + * Set the active configuration for ZeroClipboard. Returns a copy of the updated active configuration. + * @param {ZeroClipboardConfig} config + * @return {ZeroClipboardConfig} + */ + config(config: ZeroClipboardConfig): ZeroClipboardConfig; + /** + * Create the Flash bridge SWF object. + * IMPORTANT: This method should be considered private. + * @private + */ + create(): void; + /** + * Emit the "destroy" event, remove all event handlers, and destroy the Flash bridge. + */ + destroy(): void; + /** + * Focus/"activate" the provided element by moving the Flash SWF object in front of it. + * @param {Element} element + * @since 2.1.0 + */ + focus(element: Element): void; + /** + * Focus/"activate" the provided element by moving the Flash SWF object in front of it. + * @param {Element} element + * @deprecated: The preferred method to use is focus but the alias activate is available for backward compatibility's sake. + */ + activate(element: Element): void; + /** + * Blur/"deactivate" the currently focused/"activated" element, moving the Flash SWF object off the screen. + * @since 2.1.0 + */ + blur(): void; + /** + * Blur/"deactivate" the currently focused/"activated" element, moving the Flash SWF object off the screen. + * @deprecated: The preferred method to use is blur but the alias deactivate is available for backward compatibility's sake. + */ deactivate(): void; - ready: boolean; - reposition(): void; // returns false in some scenarios, but never returns true - on(eventName: string, func: Function): void; - off(eventName: string, func: Function): void; - clip(elements: any): void; - unclip(elements: any): void; - static config(options: ZeroClipboardOptions): void; - static destroy(): void; - static emit(eventName: string, args: any): void; -} + /** + * Return the currently "activated" element that the Flash SWF object is in front of it. + * @return {HTMLElement} or {null} + */ + activeElement(): HTMLElement; + /** + * Diagnostic method that describes the state of the browser, Flash Player, and ZeroClipboard. + * @return {Object} + */ + state(): Object; + /** + * Indicates if Flash Player is definitely unusable (disabled, outdated, unavailable, or deactivated). + * IMPORTANT: This method should be considered private. + * @return {boolean} + * @private + */ + isFlashUnusable(): boolean; + } -interface ZeroClipboardOptions { - /** Setting this to false would allow users to handle calling ZeroClipboard.activate(...); themselves instead of relying on our per-element mouseover handler */ - autoActivate?: boolean; + interface ZeroClipboardClient extends ZeroClipboardCommon { + /** + * A unique identifier for this ZeroClipboard client instance. + * @type {string} + */ + id: string; + /** + * Remove all event handlers and unclip all clipped elements. + */ + destroy(): void; + /** + * Set the pending data of type "text/plain" for clipboard injection. + * @param {string} data + */ + setText(data: string): void; + /** + * Set the pending data of type "text/html" for clipboard injection. + * @param {string} data + */ + setHtml(data: string): void; + /** + * Set the pending data of type "application/rtf" for clipboard injection. + * @param {string} data + */ + setRichText(data: string): void; + /** + * Register clipboard actions for new element(s) to the client. This includes automatically invoking + * ZeroClipboard.focus on the current element when it is hovered over, unless the autoActivate configuration + * property is set to false. + * @param {Element[]} elements + * @return {ZeroClipboardClient} + */ + clip(elements: List): ZeroClipboardClient; + /** + * Register clipboard actions for new element(s) to the client. This includes automatically invoking + * ZeroClipboard.focus on the current element when it is hovered over, unless the autoActivate configuration + * property is set to false. + * @param {Element} element + * @return {ZeroClipboardClient} + */ + clip(element: Element): ZeroClipboardClient; + /** + * Unregister the clipboard actions of previously registered element(s) on the page. If no elements are provided, + * ALL clipped/registered elements will be unregistered. + * @param {Element[]} elements + * @return {ZeroClipboardClient} + */ + unclip(elements: List): ZeroClipboardClient; + /** + * Unregister the clipboard actions of previously registered element(s) on the page. If no elements are provided, + * ALL clipped/registered elements will be unregistered. + * @param {Element} element + * @return {ZeroClipboardClient} + */ + unclip(elements?: Element): ZeroClipboardClient; + /** + * Get all of the elements to which this client is clipped/registered. + * @return {HTMLElement[]} + */ + elements(): HTMLElement[]; + } - /** Include a "nocache" query parameter on requests for the SWF. */ - cacheBust?: boolean; + interface ZeroClipboardEvent { + client?: ZeroClipboardClient; + type: string; + target: HTMLElement; + relatedTarget: HTMLElement; + currentTarget: HTMLObjectElement; + timeStamp: number; + } - /** Debug enabled: send console messages with deprecation warnings, etc. */ - debug?: boolean; + interface ZeroClipboardReadyEvent extends ZeroClipboardEvent { + message: string; + version: string; + } - /** Forcibly set the hand cursor ("pointer") for all clipped elements. */ - forceHandCursor?: boolean; + interface ZeroClipboardBeforeCopyEvent extends ZeroClipboardEvent { - /** URL to the movie. NOTE: For versions >= v1.3.x and < v2.x, you must use swfPath by setting moviePath! */ - moviePath?: string; + } - /** URL to the movie, relative to the page. NOTE: For versions >= v1.3.x and < v2.x, you must use swfPath by setting moviePath! */ + interface ZeroClipboardCopyEvent extends ZeroClipboardEvent { + clipboardData: { + setData(format: string, data: string): void; + setData(data: Dictionary): void; + clearData(mimeType?: string): void; + }; + } + + interface ZeroClipboardAfterCopyEvent extends ZeroClipboardEvent { + success: Dictionary; + data: Dictionary; + errors: any[]; + } + + interface ZeroClipboardDestroyEvent extends ZeroClipboardEvent { + success: Dictionary; + data: Dictionary; + } + + interface ZeroClipboardErrorEvent extends ZeroClipboardEvent { + name: string; + message: string; + minimumVersion?: string; + version?: string; + jsVersion?: string; + swfVersion?: string; + property?: string; + configuredValue?: string; + actualValue?: string; + data?: Dictionary; + errors?: any[]; + } + + interface ZeroClipboardCommon { + /** + * Set the pending data of type format for clipboard injection. + * @param {string} format + * @param {string} data + */ + setData(format: string, data: string): void; + /** + * Set the pending data of various formats for clipboard injection. This particular function signature (passing in + * an Object) will implicitly clear out any existing pending data. + * @param {Dictionary} data + */ + setData(data: Dictionary): void; + /** + * Clear the pending data of type format for clipboard injection. + * @param {string} mimeType + */ + clearData(mimeType: string): void; + /** + * Clear the pending data of ALL formats for clipboard injection. + */ + clearData(): void; + /** + * Get the pending data of type format for clipboard injection. + * @param {string} format + * @return {string} + * @since 2.1.0 + */ + getData(format: string): string; + /** + * Get a copy of the pending data of ALL formats for clipboard injection. + * @return {Dictionary} + * @since 2.1.0 + */ + getData(): Dictionary; + /** + * Add a listener function/object for an eventType. If called as a client method will be within the client instance. + * @param {string} eventType + * @param {EventListener} listener + */ + on(eventType: string, listener: EventListenerOrEventListenerObject): void; + /** + * The ready event is fired when the Flash SWF completes loading and is ready for action. Please note that you need + * to set most configuration options [with ZeroClipboard.config(...)] before ZeroClipboard.create() is invoked. + * @param {"ready"} eventType + * @param {EventListener} listener + */ + on(eventType: "ready", listener: EventListenerOrEventListenerObject): void; + /** + * On click, the Flash object will fire off a beforecopy event. This event is generally only used for "UI + * preparation" if you want to alter anything before the copy event fires. + * IMPORTANT: Handlers of this event are expected to operate synchronously if they intend to be finished before + * the "copy" event is triggered. + * @param {"beforecopy"} eventType + * @param {EventListener} listener + */ + on(eventType: "beforecopy", listener: EventListenerOrEventListenerObject): void; + /** + * On click (and after the beforecopy event), the Flash object will fire off a copy event. If the HTML object has + * data-clipboard-text or data-clipboard-target, then ZeroClipboard will take care of getting an initial set of + * data. It will then invoke any copy event handlers, in which you can call event.clipboardData.setData to set the + * text, which will complete the loop. + * IMPORTANT: If a handler of this event intends to modify the pending data for clipboard injection, it MUST + * operate synchronously in order to maintain the temporarily elevated permissions granted by the user's click + * event. The most common "gotcha" for this restriction is if someone wants to make an asynchronous XMLHttpRequest + * in response to the copy event to get the data to inject - this won't work; make it a synchronous XMLHttpRequest + * instead, or do the work in advance before the copy event is fired. + * @param {"copy"} eventType + * @param {EventListener} listener + */ + on(eventType: "copy", listener: EventListenerOrEventListenerObject): void; + /** + * The aftercopy event is fired when the text is copied [or failed to copy] to the clipboard. + * @param {"aftercopy"} eventType + * @param {EventListener} listener + */ + on(eventType: "aftercopy", listener: EventListenerOrEventListenerObject): void; + /** + * The destroy event is fired when ZeroClipboard.destroy() is invoked. + * IMPORTANT: Handlers of this event are expected to operate synchronously if they intend to be finished before the + * destruction is complete. + * @param {"destroy"} eventType + * @param {EventListener} listener + */ + on(eventType: "destroy", listener: EventListenerOrEventListenerObject): void; + /** + * The error event is fired under a number of conditions, which will be detailed as sub-sections. Some consumers + * may not consider all error types to be critical, and thus ZeroClipboard does not take it upon itself to implode + * by calling ZeroClipboard.destroy() under error conditions. However, many consumers may want to do just that. + * @param {"error"} eventType + * @param {EventListener} listener + */ + on(eventType: "error", listener: EventListenerOrEventListenerObject): void; + /** + * Add a set of eventType to listener function/object mappings. + * @param {EventListener} listenerObj + */ + on(listenerObj: { + ready?: EventListenerOrEventListenerObject; + beforecopy?: EventListenerOrEventListenerObject; + copy?: EventListenerOrEventListenerObject; + aftercopy?: EventListenerOrEventListenerObject; + destroy?: EventListenerOrEventListenerObject; + error?: EventListenerOrEventListenerObject; + }): void; + /** + * Remove a listener function/object for an eventType. + * @param {string} eventType + * @param {EventListener} listener + */ + off(eventType: string, listener: EventListenerOrEventListenerObject): void; + off(eventType: "ready", listener: EventListenerOrEventListenerObject): void; + off(eventType: "beforecopy", listener: EventListenerOrEventListenerObject): void; + off(eventType: "copy", listener: EventListenerOrEventListenerObject): void; + off(eventType: "aftercopy", listener: EventListenerOrEventListenerObject): void; + off(eventType: "destroy", listener: EventListenerOrEventListenerObject): void; + off(eventType: "error", listener: EventListenerOrEventListenerObject): void; + /** + * Remove a set of eventType to listener function/object mappings. + * @param {EventListener} listenerObj + */ + off(listenerObj: { + ready?: EventListenerOrEventListenerObject; + beforecopy?: EventListenerOrEventListenerObject; + copy?: EventListenerOrEventListenerObject; + aftercopy?: EventListenerOrEventListenerObject; + destroy?: EventListenerOrEventListenerObject; + error?: EventListenerOrEventListenerObject; + }): void; + /** + * Remove ALL listener functions/objects for ALL registered event types. + */ + off(): void; + /** + * Dispatch an event to all registered listeners. The emission of some types of events will result in side effects. + * @param {string} eventType + * @return {any} + */ + emit(eventType: string): any; + emit(eventType: "ready"): void; + emit(eventType: "beforecopy"): void; + emit(eventType: "copy"): any; + emit(eventType: "aftercopy"): void; + emit(eventType: "destroy"): void; + emit(eventType: "error"): void; + /** + * Dispatch an event to all registered listeners. The emission of some types of events will result in side effects. + * @param {string} data + * @param {string} name + * @return {any} + */ + emit(data: {type: string, name: string}): any; + /** + * Retrieves a copy of the registered listener functions/objects for the given eventType. + * @param {string} eventType + * @return {EventListener} + */ + handlers(eventType: string): EventListenerOrEventListenerObject[]; + handlers(eventType: "ready"): EventListenerOrEventListenerObject[]; + handlers(eventType: "beforecopy"): EventListenerOrEventListenerObject[]; + handlers(eventType: "copy"): EventListenerOrEventListenerObject[]; + handlers(eventType: "aftercopy"): EventListenerOrEventListenerObject[]; + handlers(eventType: "destroy"): EventListenerOrEventListenerObject[]; + handlers(eventType: "error"): EventListenerOrEventListenerObject[]; + /** + * Retrieves a copy of the map of registered listener functions/objects for ALL event types. + * @return {Object} + */ + handlers(): { + ready?: EventListenerOrEventListenerObject[]; + beforecopy?: EventListenerOrEventListenerObject[]; + copy?: EventListenerOrEventListenerObject[]; + aftercopy?: EventListenerOrEventListenerObject[]; + destroy?: EventListenerOrEventListenerObject[]; + error?: EventListenerOrEventListenerObject[]; + }; + } + + interface ZeroClipboardConfig { + /** + * SWF URL, relative to the page. Default value will be "ZeroClipboard.swf" under the same path as the ZeroClipboard JS file. + * @type {string} + */ swfPath?: string; - - /** Forcibly set the hand cursor ("pointer") for all clipped elements. */ - trustedDomains?: any; - - /** Sets the title of the div encapsulating the Flash object. */ - title?: string; - - /** The z-index used by the Flash object. */ - zIndex?: number; - - /** DEPRECATED. The class used to indicate that a clipped element is active (is being clicked). */ - activeClass?: string; - - /** DEPRECATED. The class used to indicate that a clipped element is being hovered over. */ + /** + * SWF inbound scripting policy: page domains that the SWF should trust. (single string, or array of strings) + * @type {SingleOrList} + */ + trustedDomains?: string[]; + /** + * Include a "noCache" query parameter on requests for the SWF. + * @type {boolean} + */ + cacheBust?: boolean; + /** + * Enable use of the fancy "Desktop" clipboard, even on Linux where it is known to suck. + * @type {boolean} + */ + forceEnhancedClipboard?: boolean; + /** + * How many milliseconds to wait for the Flash SWF to load and respond before assuming that + * Flash is deactivated (e.g. click-to-play) in the user's browser. If you don't care about + * how long it takes to load the SWF, you can set this to `null`. + * @type {number} + */ + flashLoadTimeout?: number; + /** + * Setting this to `false` would allow users to handle calling `ZeroClipboard.focus(...);` + * themselves instead of relying on our per-element `mouseover` handler. + * @type {boolean} + */ + autoActivate?: boolean; + /** + * Bubble synthetic events in JavaScript after they are received by the Flash object. + * @type {boolean} + */ + bubbleEvents?: boolean; + /** + * Ensure OS-compliant line endings, i.e. "\r\n" on Windows, "\n" elsewhere + * @type {boolean} + */ + fixLineEndings?: boolean; + /** + * Sets the ID of the `div` encapsulating the Flash object. + * Value is validated against the [HTML4 spec for `ID` tokens][valid_ids]. + * @type {string} + */ + containerId?: string; + /** + * Sets the class of the `div` encapsulating the Flash object. + * @type {string} + */ + containerClass?: string; + /** + * Sets the ID and name of the Flash `object` element. + * Value is validated against the [HTML4 spec for `ID` and `Name` tokens][valid_ids]. + * @type {string} + */ + swfObjectId?: string; + /** + * The class used to indicate that a clipped element is being hovered over. + * @type {string} + */ hoverClass?: string; - - /** DEPRECATED. SWF outbound scripting policy. Possible values: "never", "sameDomain", "always". */ - allowScriptAccess?: string; - - /** DEPRECATED, use trustedDomains instead! SWF inbound scripting policy: page origins that the SWF should trust. (single string or array of strings. */ - trustedOrigins?: any; - - /** DEPRECATED, use cacheBust instead! Include a "nocache" query parameter on requests for the SWF. */ - useNoCache?: boolean; + /** + * The class used to indicate that a clipped element is active (is being clicked). + * @type {string} + */ + activeClass?: string; + /** + * Forcibly set the hand cursor ("pointer") for all clipped elements. + * IMPORTANT: This configuration value CAN be modified while a SWF is actively embedded. + * @type {boolean} + */ + forceHandCursor?: boolean; + /** + * Sets the title of the `div` encapsulating the Flash object. + * IMPORTANT: This configuration value CAN be modified while a SWF is actively embedded. + * @type {string} + */ + title?: string; + /** + * The z-index used by the Flash object. + * Max value (32-bit): 2147483647. + * IMPORTANT: This configuration value CAN be modified while a SWF is actively embedded. + * @type {number} + */ + zIndex?: number; + } } -// Support AMD. -declare module "zeroclipboard" { export = ZeroClipboard; } +/** + * [ZeroClipboard description] + * @type {ZC.ZeroClipboardStatic} + */ +declare var ZeroClipboard: ZC.ZeroClipboardStatic; + +/** + * AMD and CommonJS module `zeroclipboard` + * @module + */ +declare module "zeroclipboard" { + export = ZeroClipboard; +}