/*******************************************************************************
* Copyright (c) 2008, 2018 IBM Corporation and others.
*
* This program and the accompanying materials
* are made available under the terms of the Eclipse Public License 2.0
* which accompanies this distribution, and is available at
* https://www.eclipse.org/legal/epl-2.0/
*
* SPDX-License-Identifier: EPL-2.0
*
* Contributors:
* IBM Corporation - initial API and implementation
*******************************************************************************/
package org.eclipse.swt.browser;
import java.util.*;
import org.eclipse.swt.*;
/**
* Instances of this class represent java-side "functions" that
* are invokable from javascript. Browser clients define these
* functions by subclassing BrowserFunction
and
* overriding its function(Object[])
method. This
* method will be invoked whenever javascript running in the
* Browser makes a call with the function's name.
*
*
* Application code must explicitly invoke the
* BrowserFunction.dispose()
method to release the
* resources managed by each instance when those instances are no
* longer required. Since there is usually a correlation between
* the registering of BrowserFunction(s) in a Browser and the
* loading of a page in the Browser that is aware of these
* functions, the LocationListener.changed()
listener
* is often a good place to do this.
*
* Note that disposing a Browser automatically disposes all * BrowserFunctions associated with it. *
* * @see #dispose() * @see #function(Object[]) * @see org.eclipse.swt.browser.LocationListener#changed(LocationEvent) * * @since 3.5 */ public class BrowserFunction { Browser browser; String name; String functionString; int index; boolean isEvaluate, top; String token; String[] frameNames; /** * Constructs a new instance of this class, which will be invokable * by javascript running in the specified Browser. The function will * be accessible in the top-level window and all child frames. To * create a function with a reduced scope of accessibility use the *BrowserFunction
constructor that accepts frame names
* instead.
*
* You must dispose the BrowserFunction when it is no longer required.
* A common place to do this is in a LocationListener.changed()
* listener.
*
top
and frameNames
* arguments. To create a function that is globally accessible to
* the top-level window and all child frames use the
* BrowserFunction
constructor that does not accept frame
* names instead.
*
* You must dispose the BrowserFunction when it is no longer required.
* A common place to do this is in a LocationListener.changed()
* listener.
*
true
if the function should be accessible to the
* top-level window and false
otherwise
* @param frameNames the names of the child frames that the function should
* be accessible in
*
* @exception IllegalArgumentException * Note that disposing a Browser automatically disposes all * BrowserFunctions associated with it. *
*/ public void dispose () { dispose (true); } void dispose (boolean remove) { if (index < 0) return; if (remove) browser.webBrowser.destroyFunction (this); browser = null; name = functionString = null; index = -1; } /** * Subclasses should override this method. This method is invoked when * the receiver's function is called from javascript. If all of the * arguments that are passed to the javascript function call are of * supported types then this method is invoked with the argument values * converted as follows: * * javascript null or undefined ->null
* javascript number -> java.lang.Double
* javascript string -> java.lang.String
* javascript boolean -> java.lang.Boolean
* javascript array whose elements are all of supported types -> java.lang.Object[]
*
* If any of the javascript arguments are of unsupported types then the
* function invocation will fail and this method will not be called.
*
* This method must return a value with one of these supported java types to
* the javascript caller. Note that null
values are converted
* to javascript's null
value (not undefined
), and
* instances of any java.lang.Number
subclass will be converted
* to a javascript number.
*
* @param arguments the javascript arguments converted to java equivalents
* @return the value to return to the javascript caller
*
* @exception SWTException true
if this BrowserFunction has been disposed
* and false
otherwise.
* * This method gets the dispose state for the BrowserFunction. * When a BrowserFunction has been disposed it is an error to * invoke any of its methods. *
* Note that disposing a Browser automatically disposes all * BrowserFunctions associated with it. *
* @returntrue
if this BrowserFunction has been disposed
* and false
otherwise
*/
public boolean isDisposed () {
return index < 0;
}
}