org.eclipse.swt.browser.BrowserFunction Maven / Gradle / Ivy
/*******************************************************************************
* Copyright (c) 2009, 2011 EclipseSource and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* EclipseSource - initial API and implementation
******************************************************************************/
package org.eclipse.swt.browser;
import org.eclipse.swt.SWT;
import org.eclipse.swt.SWTException;
import org.eclipse.swt.events.DisposeEvent;
import org.eclipse.swt.events.DisposeListener;
/**
* 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.
*
* Note that disposing a Browser automatically disposes all
* BrowserFunctions associated with it.
*
*
* @see #dispose()
* @see #function(Object[])
*
* @since 1.3
*/
public class BrowserFunction {
Browser browser;
String name;
boolean disposed;
/**
* Constructs a new instance of this class, which will be invokable
* by javascript running in the specified Browser.
*
* You must dispose the BrowserFunction when it is no longer required.
*
* @param browser the browser whose javascript can invoke this function
* @param name the name that javascript will use to invoke this function
*
* @exception IllegalArgumentException
* - ERROR_NULL_ARGUMENT - if the browser is null
* - ERROR_NULL_ARGUMENT - if the name is null
*
*
* @exception SWTException
* - ERROR_WIDGET_DISPOSED - if the browser has been disposed
* - ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
*
*
* @see #dispose()
*/
public BrowserFunction( Browser browser, String name ) {
this( browser, name, true );
}
BrowserFunction( Browser browser, String name, boolean create ) {
if( browser == null ) {
SWT.error( SWT.ERROR_NULL_ARGUMENT );
}
if( name == null ) {
SWT.error( SWT.ERROR_NULL_ARGUMENT );
}
if( browser.isDisposed() ) {
SWT.error( SWT.ERROR_WIDGET_DISPOSED );
}
browser.checkWidget();
this.browser = browser;
this.browser.addDisposeListener( new DisposeListener() {
public void widgetDisposed( DisposeEvent event ) {
dispose( false );
}
} );
this.name = name;
if( create ) {
browser.createFunction( this );
}
}
/**
* Disposes of the resources associated with this BrowserFunction.
* Applications must dispose of all BrowserFunctions that they create.
*
* Note that disposing a Browser automatically disposes all
* BrowserFunctions associated with it.
*
*/
public void dispose() {
dispose( true );
}
void dispose( boolean remove ) {
if( !disposed ) {
if( remove ) {
browser.destroyFunction( this );
}
browser = null;
name = null;
disposed = true;
}
}
/**
* 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 types to
* the javascript caller (note that any subclass of java.lang.Number
* will be successfully 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
* - ERROR_THREAD_INVALID_ACCESS when called from the wrong thread
* - ERROR_FUNCTION_DISPOSED when the BrowserFunction has been disposed
*
*/
public Object function( Object[] arguments ) {
if( disposed ) {
SWT.error( SWT.ERROR_FUNCTION_DISPOSED );
}
browser.checkWidget();
return null;
}
/**
* Returns the Browser whose pages can invoke this BrowserFunction.
*
* @return the Browser associated with this BrowserFunction
*
* @exception SWTException
* - ERROR_THREAD_INVALID_ACCESS when called from the wrong thread
* - ERROR_FUNCTION_DISPOSED when the BrowserFunction has been disposed
*
*/
public Browser getBrowser() {
if( disposed ) {
SWT.error( SWT.ERROR_FUNCTION_DISPOSED );
}
browser.checkWidget();
return browser;
}
/**
* Returns the name that javascript can use to invoke this BrowserFunction.
*
* @return the BrowserFunction's name
*
* @exception SWTException
* - ERROR_THREAD_INVALID_ACCESS when called from the wrong thread
* - ERROR_FUNCTION_DISPOSED when the BrowserFunction has been disposed
*
*/
public String getName() {
if( disposed ) {
SWT.error( SWT.ERROR_FUNCTION_DISPOSED );
}
browser.checkWidget();
return name;
}
/**
* Returns 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.
*
* @return true if this BrowserFunction has been disposed
* and false otherwise
*/
public boolean isDisposed () {
return disposed;
}
}