/******************************************************************************* * Copyright � 2009, 2011 Florian Pirchner 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: * Florian Pirchner � initial API and implementation (based on other ridgets of * compeople AG) * compeople AG - adjustments for Riena v1.2 - 3.0 *******************************************************************************/ package org.eclipse.riena.ui.ridgets; import org.eclipse.riena.ui.ridgets.listener.ILocationListener; import org.eclipse.riena.ui.ridgets.listener.IProgressListener; /** * The browser ridget displays a html page fetched from a given URL. * * @since 1.2 */ public interface IBrowserRidget extends IValueRidget { /** * Implementations represent Java-side "functions" that are invokable from JavaScript. * * @since 6.0 * @see IBrowserRidget#mapScriptFunction(String, IBrowserRidgetFunction) */ interface IBrowserRidgetFunction { /** * Executes a function, which is triggered by JavaScript from within the browser. * * @param jsParams * the parameters, passed to the JavaScript function * @return the result to return the the JavaScript caller * * @see IBrowserRidget#mapScriptFunction(String, IBrowserRidgetFunction) */ Object execute(Object[] jsParams); } /** * Property name of the url property ({@value} ). * * @see #getUrl() * @see #setUrl(String) */ String PROPERTY_URL = "url"; //$NON-NLS-1$ /** * Add a {@link ILocationListener} that is notified of URL changes of this * ridget. * <p> * Adding the same listener instance several times has no effect. * <p> * Implementation note: you should be aware that these listeners are not * notified of URL changes in these cases: * <ul> * <li>user actions that change the current page content (scripts, dom * manipulation)</li> * <li>user actions that open a new browser in a separate window (hyperlink * with '{@code target="_blank"}')</li> * <li>per design - changing the URL via API calls, such as * {@code setUrl(...)} or {@code setText(...)}, does not notfiy listeners, * to prevent endless listener-event-listener loops</li> * <li>per design - rebinding this ridget to another browser widget does not * notify listeners and is not blockable</li> * </ul> * * @param listener * a non-null {@link ILocationListener} * @since 3.0 */ void addLocationListener(ILocationListener listener); /** * Add a {@link IProgressListener} that is notified when a loading step of this ridget is finished. * <p> * Adding the same listener instance several times has no effect. * * @param listener * a non-null {@link IProgressListener} * @since 6.1 */ void addProgressListener(IProgressListener listener); /** * Return the text last set into the ridget or null. * <p> * The default value is null. * <p> * check https://bugs.eclipse.org/bugs/show_bug.cgi?id=433526 if you get a org.eclipse.swt.SWTException: Failed to change Variant type result = -2147352571 * * @since 2.0 */ String getText(); /** * Return the url of this ridget or null. * <p> * The default value is null. * * @return the url as a String. It is not guaranteed that the return value * is a valid url. For example it may be null, empty or browser * specific, such as 'about:blank'. */ String getUrl(); /** * Returns true, if an OutputMarker was added. * <p> * If an OutputMarker is added, the browser widget will not allow leaving * the page (i.e. it is not possible to folow a link). */ boolean isOutputOnly(); /** * Remove a {@link ILocationListener} from this ridget. * * @param listener * a non-null {@link ILocationListener} * @since 3.0 */ void removeLocationListener(ILocationListener listener); /** * Remove a {@link IProgressListener} from this ridget. * * @param listener * a non-null {@link IProgressListener} * @since 6.1 */ void removeProgressListener(IProgressListener listener); /** * Adds and removes the default OutputMarker. * <p> * If an OutputMarker is added, the browser widget will not allow leaving * the page (i.e. it is not possible to folow a link). * * @param outputOnly * <code>true</code> if the ridget should be 'output only' * (=cannot be edited), <code>false</code> otherwise. */ void setOutputOnly(boolean outputOnly); /** * A html String to show in the ridget. * <p> * Setting the text will also set the url value to null or 'about:blank'. * <p> * Note: currently there is no synchronisation. Invoking setText(...) while * a page is loaded asynchronously from setUrl(...) call may have undefined * results. * <p> * check https://bugs.eclipse.org/bugs/show_bug.cgi?id=433526 if you get a org.eclipse.swt.SWTException: Failed to change Variant type result = -2147352571 * * @param text * a String of HTML content. * * @since 2.0 */ void setText(String text); /** * Sets the url. * <p> * Setting the url will also set the text value to null. * * @param newUrl * a String that conforms to the constraints dictated by the * underlying widget (for example an SWT Browser with IE or * Mozilla underneath). May be null, empty, or browser specific, * such as 'about:blank'. */ void setUrl(String newUrl); /** * Executes the given script on the page in the browser. * * @param script * the script to execute * @return <code>true</code> if the script was successfully executed. * @since 6.0 */ boolean execute(String script); /** * Makes a JavaScript function available in the browser. This way it is possible to call a Java-side implementation for this function. * * @param functionName * the name under which the function can be called from within the browser. * @param controller * the function implementation * @since 6.0 * @see IBrowserRidgetFunction */ void mapScriptFunction(String functionName, IBrowserRidgetFunction controller); /** * Removes the JavaScript function, so that is not callable from within the browser anymore. If there is no function with the given name, calling this * method has no effect. * * @param functionName * the name under which the function can be called from within the browser. * @since 6.0 */ void unmapScriptFunction(String functionName); }