This repository has been archived on 2023-06-18. You can view files and clone it, but cannot push or open issues or pull requests.
ima02/resources/defects4j-checkout-closure-1f/contrib/externs/api/gadgets/opensocial.js
github-classroom[bot] e42e547e48
Initial commit
2023-04-25 11:33:41 +00:00

598 lines
19 KiB
JavaScript

/*
* Copyright 2008 Google Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/**
* @fileoverview Externs file for OpenSocial gadget libraries. Legacy API based
* on the {@code _IG_...} is not supported here.
* Note this may not be comprehensive.
*
* @see http://code.google.com/apis/gadgets/docs/reference/
* @see http://incubator.apache.org/shindig/shindig-1.1.x/shindig-features/jsdoc
* @externs
*/
// Root namespace for gadget related functionality.
var gadgets = {};
// Namespace providing operations for getting information about and modifying
// the window the gadget is placed in.
gadgets.window = {};
/**
* @param {number=} opt_height The new height for the gadget.
*/
gadgets.window.adjustHeight = function(opt_height) {};
/**
* @return {Object} Dimensions for the viewport.
*/
gadgets.window.getViewportDimensions = function() {};
/**
* @param {string} title The new title for the gadget.
*/
gadgets.window.setTitle = function(title) {};
/**
* Calculate inner content height is hard and different between
* browsers rendering in Strict vs. Quirks mode. We use a combination of
* three properties within document.body and document.documentElement:
* - scrollHeight
* - offsetHeight
* - clientHeight
* These values differ significantly between browsers and rendering modes.
* But there are patterns. It just takes a lot of time and persistence
* to figure out.
* @return {number} Height of current window.
*/
gadgets.window.getHeight = function() {};
// Namespace providing operations for making remote procedure calls for
// gadget-to-container, container-to-gadget and gadget-to-gadget communication.
gadgets.rpc = {};
/**
* Exported constant used by transports.
* @type {string}
*/
gadgets.rpc.ACK;
/**
* @param {?string} targetId The id of the target gadget, null for container.
* @param {string} serviceName The RPC service to call.
* @param {!Function=} opt_callback Function called when the RPC
* completes.
* @param {...*} var_args Variable arguments that are passed to the RPC handler.
*/
gadgets.rpc.call = function(targetId, serviceName, opt_callback, var_args) {};
/**
* Force RPC utilities to fallback to secure mechanisms for type=URL gadgets.
*/
gadgets.rpc.forceParentVerifiable = function() {};
/**
* @return {string} The RPC relay mechanism.
*/
gadgets.rpc.getRelayChannel = function() {};
/**
* @param {string} targetId The frame ID to get the relay for.
* @return {string} The relay URL of the given gadget (or container).
*/
gadgets.rpc.getRelayUrl = function(targetId) {};
/**
* Global init for RPC code.
*/
gadgets.rpc.init = function() {};
/**
* Receives and processes an RPC request. (Not to be used directly.)
* Only used by IFPC.
* @param {Array.<string>} fragment An RPC request fragment encoded as
* an array. The first 4 elements are target id, source id & call id,
* total packet number, packet id. The last element stores the actual
* JSON-encoded and URI escaped packet data.
*/
gadgets.rpc.receive = function(fragment) {};
/**
* @param {string} serviceName The RPC service to register a handler for.
* @param {!Function} handler Handler for an RPC call, return
* value will be sent back to the caller.
*/
gadgets.rpc.register = function(serviceName, handler) {};
/**
* @param {!Function} handler Handler for unknown RPC calls,
* return value will be sent back to the caller.
*/
gadgets.rpc.registerDefault = function(handler) {};
/**
* Helper method to retrieve the auth token for a given gadget.
* @param {string} targetId Name of the target frame.
* @return {string} The authentication token registered for this
* target id.
*/
gadgets.rpc.getAuthToken = function(targetId) {};
/**
* Helper method returning a canonicalized protocol://host[:port] for
* a given input URL, provided as a string. Used to compute convenient
* relay URLs and to determine whether a call is coming from the same
* domain as its receiver (bypassing the try/catch capability detection
* flow, thereby obviating Firebug and other tools reporting an exception).
* @param {string} url Base URL to canonicalize.
* @return {string} The canonicalized URL.
*/
gadgets.rpc.getOrigin = function(url) {};
/**
* Helper method returning a canonicalized protocol://host[:port] for
* the relay URL of a given target frame.
* @param {string} id Name of the target frame.
* @return {string} The canonicalized URL.
*/
gadgets.rpc.getTargetOrigin = function(id) {};
/**
* Sets the auth token of a target frame.
* @param {string} targetId Name of the target frame.
* @param {string} token The authentication token to use for all calls to or
* from this target id.
*/
gadgets.rpc.setAuthToken = function(targetId, token) {};
/**
* Sets the relay URL of a target frame.
* @param {string} targetId The id of the target gadget.
* @param {string} url Full relay URL of the target frame.
* @param {boolean=} opt_useLegacy True if this relay needs the legacy IFPC
* wire format.
*/
gadgets.rpc.setRelayUrl = function(targetId, url, opt_useLegacy) {};
/**
* Setups the gadgets.rpc library to communicate with the receiver. This method
* replaces setAuthToken and setRelayUrl.
* @param {string} targetId The id of the target gadget.
* @param {string=} opt_receiverUrl Full relay URL of the target frame.
* @param {boolean=} opt_authToken null The authentication token to use for all
* calls to or from this target id.
*/
gadgets.rpc.setupReceiver = function(targetId, opt_receiverUrl, opt_authToken) {};
/**
* @param {string} serviceName The RPC service to unregister the handler for.
*/
gadgets.rpc.unregister = function(serviceName) {};
/**
* Unregisters the default service handler. Future unknown RPC
* calls will fail silently.
*/
gadgets.rpc.unregisterDefault = function() {};
/**
* Class providing access to user preferences, module dimensions, and messages.
* @param {string=} opt_moduleId An optional module ID to get preferences for.
* @constructor
*/
gadgets.Prefs = function(opt_moduleId) {};
/**
* @param {string} key The user preference key.
* @return {Array.<string>} The array value of the preference.
*/
gadgets.Prefs.prototype.getArray = function(key) {};
/**
* @param {string} key The user preference key.
* @return {boolean} The boolean value of the preference.
*/
gadgets.Prefs.prototype.getBool = function(key) {};
/**
* @param {string} key The user preference key.
* @return {number} The float value of the preference.
*/
gadgets.Prefs.prototype.getFloat = function(key) {};
/**
* @param {string} key The user preference key.
* @return {number} The int value of the preference.
*/
gadgets.Prefs.prototype.getInt = function(key) {};
/**
* @param {string} key The user preference key.
* @return {string} The string value of the preference.
*/
gadgets.Prefs.prototype.getString = function(key) {};
/**
* @return {string} The country code.
*/
gadgets.Prefs.prototype.getCountry = function() {};
/**
* @return {string} The language code.
*/
gadgets.Prefs.prototype.getLang = function() {};
/**
* @return {number} The module's id.
*/
gadgets.Prefs.prototype.getModuleId = function() {};
/**
* @param {string} key The message key.
* @return {string} The unformatted message.
*/
gadgets.Prefs.prototype.getMsg = function(key) {};
/**
* @param {string} key The preference key.
* @param {string|number} value The preference value.
*/
gadgets.Prefs.prototype.set = function(key, value) {};
/**
* @param {string} key The preference key.
* @param {Array.<string>} array The preference array.
*/
gadgets.Prefs.prototype.setArray = function(key, array) {};
// Namespace for embedding flash content in gadgets.
gadgets.flash = {};
/**
* @return {boolean} Injects the cached Flash file into the DOM tree.
*/
gadgets.flash.embedCachedFlash = function() {};
/**
* @return {number} The major version of Flash Player or 0 if Flash is not
* supported.
*/
gadgets.flash.getMajorVersion = function() {};
/**
* @param {string} url The URL of the flash to embed.
* @param {string|Element} container The ID or object reference to the
* existing HTML container.
* @param {number} minVersion The minimum version required.
* @param {Object=} opt_params An optional object that may contain any valid
* HTML parameters that will be passed to the Flash movie.
* @return {boolean} Whether the function call completes successfully.
*/
gadgets.flash.embedFlash = function(
url, container, minVersion, opt_params) {};
// Namespace for retrieving content from remote servers via the gadgets proxy.
gadgets.io = {};
/**
* Gets the proxy version of the passed-in URL.
*
* @param {string} url The URL to get the proxy URL for
* @param {Object=} opt_params Optional Parameter Object.
* The following properties are supported:
* .REFRESH_INTERVAL The number of seconds that this
* content should be cached. Defaults to 3600.
*
* @return {string} The proxied version of the URL
*/
gadgets.io.getProxyUrl = function(url, opt_params) {};
/**
* @param {string} url The URL to request data from.
* @param {Function} callback The callback function.
* @param {Object=} opt_params Optional map of parameters sent on request, see
* gadgets.io.RequestParameters.
*/
gadgets.io.makeRequest = function(url, callback, opt_params) {};
/**
* Converts an input object into a URL-encoded data string. (key=value&...).
* @param {Object} fields The post fields you wish to encode.
* @return {string} The processed post data; this includes a trailing
* ampersand (&).
*/
gadgets.io.encodeValues = function(fields) {};
/**
* Enumeration of request parameters.
* @enum {string}
*/
gadgets.io.RequestParameters = {};
gadgets.io.RequestParameters.AUTHORIZATION;
gadgets.io.RequestParameters.CONTENT_TYPE;
gadgets.io.RequestParameters.GET_SUMMARIES;
gadgets.io.RequestParameters.HEADERS;
gadgets.io.RequestParameters.METHOD;
gadgets.io.RequestParameters.NUM_ENTRIES;
gadgets.io.RequestParameters.OAUTH_REQUEST_TOKEN;
gadgets.io.RequestParameters.OAUTH_REQUEST_TOKEN_SECRET;
gadgets.io.RequestParameters.OAUTH_SERVICE_NAME;
gadgets.io.RequestParameters.OAUTH_TOKEN_NAME;
gadgets.io.RequestParameters.OAUTH_USE_TOKEN;
gadgets.io.RequestParameters.POST_DATA;
gadgets.io.RequestParameters.REFRESH_INTERVAL;
/**
* Enumeration of content types that can be specified in
* {@link gadgets.io.RequestParameters.AUTHORIZATION}
* @enum {string}
*/
gadgets.io.AuthorizationType = {};
gadgets.io.AuthorizationType.NONE;
gadgets.io.AuthorizationType.OAUTH;
gadgets.io.AuthorizationType.SIGNED;
/**
* Enumeration of content types that can be specified in
* {@link gadgets.io.RequestParameters.CONTENT_TYPE}
* @enum {string}
*/
gadgets.io.ContentType = {};
gadgets.io.ContentType.DOM;
gadgets.io.ContentType.FEED;
gadgets.io.ContentType.JSON;
gadgets.io.ContentType.TEXT;
/**
* Enumeration of content types that can be specified in
* {@link gadgets.io.RequestParameters.METHOD}
* @enum {string}
*/
gadgets.io.MethodType = {};
gadgets.io.MethodType.DELETE;
gadgets.io.MethodType.GET;
gadgets.io.MethodType.HEAD;
gadgets.io.MethodType.POST;
gadgets.io.MethodType.PUT;
/**
* This is the response object that is passed to the callback of
* gadgets.io.makeRequest. It is never explicitly called "ResponseObject" in the
* documentation, but the documentation does refer to an object that is passed
* to the callback. This is that object.
* @see http://wiki.opensocial.org/index.php?title=Gadgets.io_(v0.9)#gadgets.io.makeRequest
*/
gadgets.io.ResponseObject = {};
/**@type {Object}*/ gadgets.io.ResponseObject.data;
/**@type {Array.<string>}*/ gadgets.io.ResponseObject.errors;
/**@type {Object}*/ gadgets.io.ResponseObject.headers;
/**@type {number}*/ gadgets.io.ResponseObject.rc;
/**@type {string}*/ gadgets.io.ResponseObject.text;
/**@type {string}*/ gadgets.io.ResponseObject.oauthApprovalUrl;
/**@type {string}*/ gadgets.io.ResponseObject.oauthError;
/**@type {string}*/ gadgets.io.ResponseObject.oauthErrorText;
// Namespace for views
gadgets.views = {};
/**
* Returns the current view.
* @return {gadgets.views.View} The current view.
*/
gadgets.views.getCurrentView = function() {};
/**
* Get parameters passed into the view
* @return {Object} Map string -> string of parameters passed in.
*/
gadgets.views.getParams = function() {};
/**
* @return {Object} Map<gadgets.views.ViewType, String, gadgets.views.View>
* A map of all the supported views. Keys each gadgets.view.View by its name.
*/
gadgets.views.getSupportedViews = function() {};
/**
* @param {gadgets.views.View|string} view The view to navigate to.
* @param {Object=} opt_params Map.<String, String>: Parameters to pass to the
* gadget after it has been navigated to on the surface.
* @param {string=} opt_ownerId The ID of the owner of the page to navigate to;
* defaults to the current owner.
*/
gadgets.views.requestNavigateTo = function(view, opt_params, opt_ownerId) {};
/**
* @constructor
*/
gadgets.views.View = function() {};
/**
* @return {string} Returns the name of this view.
*/
gadgets.views.View.prototype.getName = function() {}
/**
* @return {boolean} True if the gadget is the only visible gadget; otherwise,
* false.
*/
gadgets.views.View.prototype.isOnlyVisibleGadget = function() {};
// Namespace for utilities.
gadgets.util = {};
/**
* Escapes the input using HTML entities to make it safer.
* @param {string} str The string to escape.
* @return {string} The escaped string.
*/
gadgets.util.escapeString = function(str) {};
/**
* Reverses escapeString
* @param {string} str The string to unescape.
* @return {string} The unescaped string.
*/
gadgets.util.unescapeString = function(str) {};
/**
* Returns the parameters for a feature.
* @param {string} feature The feature name.
* @return {Object} Parameters for the feature or null.
*/
gadgets.util.getFeatureParameters = function(feature) {};
/**
* Returns whether the specified feature is supported.
* @param {string} feature The feature name.
* @return {boolean} Whether the feature is supported.
*/
gadgets.util.hasFeature = function(feature) {};
/**
* Registers a function to be called when the gadget loads.
* @param {function()} fn The function to call.
*/
gadgets.util.registerOnLoadHandler = function(fn) {};
/**
* Parses the current document's location and returns an object representing
* the parameters in the query string.
* @param {string=} opt_url Optional URL whose parameters to parse.
* Defaults to window's current URL.
* @return {Object} Parameters from the query string.
*/
gadgets.util.getUrlParameters = function(opt_url) {};
/**
* Creates a closure that is suitable for passing as a callback.
* Any number of arguments may be passed to the callback;
* they will be received in the order they are passed in.
*
* @param {Object} scope The execution scope; may be null if there is no
* need to associate a specific instance of an object with this
* callback
* @param {Function} callback The callback to invoke when this is run;
* any arguments passed in will be passed after your initial arguments
* @param {...*} var_args Initial arguments to be passed to the callback
* @returns {Function} The closure.
*/
gadgets.util.makeClosure = function(scope, callback, var_args) {};
/**
* Attach an event listener to given DOM element (Not a gadget standard)
*
* @param {Object} elem DOM element on which to attach event.
* @param {string} eventName Event type to listen for.
* @param {function()} callback Invoked when specified event occurs.
* @param {boolean} useCapture If true, initiates capture.
*/
gadgets.util.attachBrowserEvent = function(
elem, eventName, callback, useCapture) {};
//Namespace for JSON processing.
gadgets.json = {};
/**
* Convert a JSON object into a string.
* @param {Object} json
* @return {String} The JSON as a string
*/
gadgets.json.stringify = function(json) {};
/**
* Convert a string into a JSON object.
* Uses safe RegEx match before parsing.
* @param {string} s The string
* @return {Object} The JSON
*/
gadgets.json.parse = function(s) {};
//Namespace for config.
gadgets.config = {};
/**
* Registers a configurable component and its configuration parameters.
* Multiple callbacks may be registered for a single component if needed.
*
* @param {string} component The name of the component to register. Should
* be the same as the fully qualified name of the <Require> feature or
* the name of a fully qualified JavaScript object reference
* (e.g. "gadgets.io").
* @param {Object=} opt_validators Mapping of option name to validation
* functions that take the form function(data) {return isValid(data);}
* @param {Function=} opt_callback A function to be invoked when a
* configuration is registered. If passed, this function will be invoked
* immediately after a call to init has been made. Do not assume that
* dependent libraries have been configured until after init is
* complete. If you rely on this, it is better to defer calling
* dependent libraries until you can be sure that configuration is
* complete. Takes the form function(config), where config will be
* all registered config data for all components. This allows your
* component to read configuration from other components.
* @param {boolean=} opt_callOnUpdate Whether the callback shall be call
* on gadgets.config.update() as well.
*/
gadgets.config.register = function(component, opt_validators, opt_callback,
opt_callOnUpdate) {};
/**
* Retrieves configuration data on demand.
*
* @param {string=} opt_component The component to fetch. If not provided
* all configuration will be returned.
* @return {Object} The requested configuration, or an empty object if no
* configuration has been registered for that component.
*/
gadgets.config.get = function(opt_component) {};
/**
* Initializes the configuration.
*
* @param {Object} config The full set of configuration data.
* @param {Boolean=} opt_noValidation True if you want to skip validation.
*/
gadgets.config.init = function(config, opt_noValidation) {};
/**
* Creates an HTML or XHTML element.
* @param {string} tagName The type of element to construct.
* @return {Element} The newly constructed element.
*/
gadgets.util.createElement = function(tagName) {};
/**
* Creates an HTML or XHTML iframe element with attributes.
* @param {Object=} opt_attribs Optional set of attributes to attach. The
* only working attributes are spelled the same way in XHTML attribute
* naming (most strict, all-lower-case), HTML attribute naming (less strict,
* case-insensitive), and JavaScript property naming (some properties named
* incompatibly with XHTML/HTML).
* @return {Element} The DOM node representing body.
*/
gadgets.util.createIframeElement = function(opt_attribs) {};
/**
* Gets the HTML or XHTML body element.
* @return {Element} The DOM node representing body.
*/
gadgets.util.getBodyElement = function() {};