src/xwalk/runtime/android/core/src/org/xwalk/core/XWalkView.java

   1 // Copyright (c) 2014 Intel Corporation. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 package org.xwalk.core;
   6
   7 import android.app.Activity;
   8 import android.content.Context;
   9 import android.content.Intent;
  10 import android.os.Bundle;
  11 import android.util.AttributeSet;
  12 import android.webkit.ValueCallback;
  13
  14 import org.xwalk.core.internal.XWalkNavigationHistoryInternal;
  15 import org.xwalk.core.internal.XWalkPreferencesInternal;
  16 import org.xwalk.core.internal.XWalkResourceClientInternal;
  17 import org.xwalk.core.internal.XWalkUIClientInternal;
  18 import org.xwalk.core.internal.XWalkViewInternal;
  19
  20 /**
  21  * <p>XWalkView represents an Android view for web apps/pages. Thus most of attributes
  22  * for Android view are valid for this class. Since it internally uses
  23  * <a href="http://developer.android.com/reference/android/view/SurfaceView.html">
  24  * android.view.SurfaceView</a> for rendering web pages by default, it can't be resized,
  25  * rotated, transformed and animated due to the limitations of SurfaceView.
  26  * Alternatively, if the preference key {@link XWalkPreferences#ANIMATABLE_XWALK_VIEW}
  27  * is set to True, XWalkView can be transformed and animated because
  28  * <a href="http://developer.android.com/reference/android/view/TextureView.html">
  29  * TextureView</a> is intentionally used to render web pages for animation support.
  30  * Besides, XWalkView won't be rendered if it's invisible.</p>
  31  *
  32  * <p>XWalkView needs hardware acceleration to render web pages. As a result, the
  33  * AndroidManifest.xml of the caller's app must be appended with the attribute
  34  * "android:hardwareAccelerated" and its value must be set as "true".</p>
  35  * <pre>
  36  * &lt;application android:name="android.app.Application" android:label="XWalkUsers"
  37  *     android:hardwareAccelerated="true"&gt;
  38  * </pre>
  39  *
  40  * <p>Crosswalk provides 2 major callback classes, namely {@link XWalkResourceClient} and
  41  * {@link XWalkUIClient} for listening to the events related to resource loading and UI.
  42  * By default, Crosswalk has a default implementation. Callers can override them if needed.</p>
  43  *
  44  * <p>Unlike other Android views, this class has to listen to system events like intents and activity result.
  45  * The web engine inside this view need to get and handle them.
  46  * With contianer activity's lifecycle change, XWalkView will pause all timers and other
  47  * components like videos when activity paused, resume back them when activity resumed.
  48  * When activity is about to destroy, XWalkView will destroy itself as well.
  49  * Embedders can also call onHide() and pauseTimers() to explicitly pause XWalkView.
  50  * Similarily with onShow(), resumeTimers() and onDestroy().
  51  *
  52  * For example:</p>
  53  *
  54  * <pre>
  55  *   import android.app.Activity;
  56  *   import android.os.Bundle;
  57  *
  58  *   import org.xwalk.core.XWalkResourceClient;
  59  *   import org.xwalk.core.XWalkUIClient;
  60  *   import org.xwalk.core.XWalkView;
  61  *
  62  *   public class MyActivity extends Activity {
  63  *       XWalkView mXwalkView;
  64  *
  65  *       class MyResourceClient extends XWalkResourceClient {
  66  *           MyResourceClient(XWalkView view) {
  67  *               super(view);
  68  *           }
  69  *
  70  *           &#64;Override
  71  *           WebResourceResponse shouldInterceptLoadRequest(XWalkView view, String url) {
  72  *               // Handle it here.
  73  *               ...
  74  *           }
  75  *       }
  76  *
  77  *       class MyUIClient extends XWalkUIClient {
  78  *           MyUIClient(XWalkView view) {
  79  *               super(view);
  80  *           }
  81  *
  82  *           &#64;Override
  83  *           void onFullscreenToggled(XWalkView view, String url) {
  84  *               // Handle it here.
  85  *               ...
  86  *           }
  87  *       }
  88  *
  89  *       &#64;Override
  90  *       protected void onCreate(Bundle savedInstanceState) {
  91  *           mXwalkView = new XWalkView(this, null);
  92  *           setContentView(mXwalkView);
  93  *           mXwalkView.setResourceClient(new MyResourceClient(mXwalkView));
  94  *           mXwalkView.setUIClient(new MyUIClient(mXwalkView));
  95  *           mXwalkView.load("http://www.crosswalk-project.org", null);
  96  *       }
  97  *
  98  *       &#64;Override
  99  *       protected void onPause() {
 100  *           super.onPause();
 101  *           if (mXwalkView != null) {
 102  *               mXwalkView.pauseTimers();
 103  *               mXwalkView.onHide();
 104  *           }
 105  *       }
 106  *
 107  *       &#64;Override
 108  *       protected void onResume() {
 109  *           super.onResume();
 110  *           if (mXwalkView != null) {
 111  *               mXwalkView.resumeTimers();
 112  *               mXwalkView.onShow();
 113  *           }
 114  *       }
 115  *
 116  *       &#64;Override
 117  *       protected void onDestroy() {
 118  *           super.onDestroy();
 119  *           if (mXwalkView != null) {
 120  *               mXwalkView.onDestroy();
 121  *           }
 122  *       }
 123  *
 124  *       &#64;Override
 125  *       protected void onActivityResult(int requestCode, int resultCode, Intent data) {
 126  *           if (mXwalkView != null) {
 127  *               mXwalkView.onActivityResult(requestCode, resultCode, data);
 128  *           }
 129  *       }
 130  *
 131  *       &#64;Override
 132  *       protected void onNewIntent(Intent intent) {
 133  *           if (mXwalkView != null) {
 134  *               mXwalkView.onNewIntent(intent);
 135  *           }
 136  *       }
 137  *   }
 138  * </pre>
 139  */
 140 public class XWalkView extends XWalkViewInternal {
 141
 142     /**
 143      * Normal reload mode as default.
 144      * @since 1.0
 145      */
 146     public static final int RELOAD_NORMAL = 0;
 147     /**
 148      * Reload mode with bypassing the cache.
 149      * @since 1.0
 150      */
 151     public static final int RELOAD_IGNORE_CACHE = 1;
 152
 153     /**
 154      * Constructor for inflating via XML.
 155      * @param context  a Context object used to access application assets.
 156      * @param attrs    an AttributeSet passed to our parent.
 157      * @since 1.0
 158      */
 159     public XWalkView(Context context, AttributeSet attrs) {
 160         super(context, attrs);
 161     }
 162
 163     /**
 164      * Constructor for Crosswalk runtime. In shared mode, context isi
 165      * different from activity. In embedded mode, they're same.
 166      * @param context  a Context object used to access application assets
 167      * @param activity the activity for this XWalkView.
 168      * @since 1.0
 169      */
 170     public XWalkView(Context context, Activity activity) {
 171         super(context, activity);
 172     }
 173
 174     /**
 175      * Load a web page/app from a given base URL or a content.
 176      * If url is null or empty and content is null or empty, then this function
 177      * will do nothing.
 178      * If content is not null, load the web page/app from the content.
 179      * If content is not null and the url is not set, return "about:blank" ifi
 180      * calling {@link XWalkView#getUrl()}.
 181      * If content is null, try to load the content from the url.
 182      *
 183      * It supports URL schemes like 'http:', 'https:' and 'file:'.
 184      * It can also load files from Android assets, e.g. 'file:///android_asset/'.
 185      * @param url the url for web page/app.
 186      * @param content the content for the web page/app. Could be empty.
 187      * @since 1.0
 188      */
 189     public void load(String url, String content) {
 190         super.load(url, content);
 191     }
 192
 193     /**
 194      * Load a web app from a given manifest.json file. If content is not null,
 195      * load the manifest.json from the content. If content is null, try to load
 196      * the manifest.json from the url. Note that url should not be null if the
 197      * launched path defined in manifest.json is relative.
 198      *
 199      * It supports URL schemes like 'http:', 'https:' and 'file:'.
 200      * It can also load files from Android assets, e.g. 'file:///android_asset/'.
 201      * @param url the url for manifest.json.
 202      * @param content the content for manifest.json.
 203      * @since 1.0
 204      */
 205     public void loadAppFromManifest(String url, String content) {
 206         super.loadAppFromManifest(url, content);
 207     }
 208
 209     /**
 210      * Reload a web app with a given mode.
 211      * @param mode the reload mode.
 212      * @since 1.0
 213      */
 214     public void reload(int mode) {
 215         super.reload(mode);
 216     }
 217
 218     /**
 219      * Stop current loading progress.
 220      * @since 1.0
 221      */
 222     public void stopLoading() {
 223         super.stopLoading();
 224     }
 225
 226     /**
 227      * Get the url of current web page/app. This may be different from what's passed
 228      * by caller.
 229      * @return the url for current web page/app.
 230      * @since 1.0
 231      */
 232     public String getUrl() {
 233         return super.getUrl();
 234     }
 235
 236     /**
 237      * Get the title of current web page/app. This may be different from what's passed
 238      * by caller.
 239      * @return the title for current web page/app.
 240      * @since 1.0
 241      */
 242     public String getTitle() {
 243         return super.getTitle();
 244     }
 245
 246     /**
 247      * Get the original url specified by caller.
 248      * @return the original url.
 249      * @since 1.0
 250      */
 251     public String getOriginalUrl() {
 252         return super.getOriginalUrl();
 253     }
 254
 255     /**
 256      * Get the navigation history for current XWalkView. It's synchronized with
 257      * this XWalkView if any backward/forward and navigation operations.
 258      * @return the navigation history.
 259      * @since 1.0
 260      */
 261     public XWalkNavigationHistory getNavigationHistory() {
 262         XWalkNavigationHistoryInternal history = super.getNavigationHistory();
 263         if (history == null || history instanceof XWalkNavigationHistory) {
 264             return (XWalkNavigationHistory) history;
 265         }
 266
 267         return new XWalkNavigationHistory(history);
 268     }
 269
 270     /**
 271      * Injects the supplied Java object into this XWalkView.
 272      * Each method defined in the class of the object should be
 273      * marked with {@link JavascriptInterface} if it's called by JavaScript.
 274      * @param object the supplied Java object, called by JavaScript.
 275      * @param name the name injected in JavaScript.
 276      * @since 1.0
 277      */
 278     public void addJavascriptInterface(Object object, String name) {
 279         super.addJavascriptInterface(object, name);
 280     }
 281
 282     /**
 283      * Evaluate a fragment of JavaScript code and get the result via callback.
 284      * @param script the JavaScript string.
 285      * @param callback the callback to handle the evaluated result.
 286      * @since 1.0
 287      */
 288     public void evaluateJavascript(String script, ValueCallback<String> callback) {
 289         super.evaluateJavascript(script, callback);
 290     }
 291
 292     /**
 293      * Clear the resource cache. Note that the cache is per-application, so this
 294      * will clear the cache for all XWalkViews used.
 295      * @param includeDiskFiles indicate whether to clear disk files for cache.
 296      * @since 1.0
 297      */
 298     public void clearCache(boolean includeDiskFiles) {
 299         super.clearCache(includeDiskFiles);
 300     }
 301
 302     /**
 303      * Indicate that a HTML element is occupying the whole screen.
 304      * @return true if any HTML element is occupying the whole screen.
 305      * @since 1.0
 306      */
 307     public boolean hasEnteredFullscreen() {
 308         return super.hasEnteredFullscreen();
 309     }
 310
 311     /**
 312      * Leave fullscreen mode if it's. Do nothing if it's not
 313      * in fullscreen.
 314      * @since 1.0
 315      */
 316     public void leaveFullscreen() {
 317         super.leaveFullscreen();
 318     }
 319
 320     /**
 321      * Pause all layout, parsing and JavaScript timers for all XWalkView instances.
 322      * It will be called when the container Activity get paused. It can also be explicitly
 323      * called to pause timers.
 324      *
 325      * Note that it will globally impact all XWalkView instances, not limited to
 326      * just this XWalkView.
 327      *
 328      * @since 1.0
 329      */
 330     public void pauseTimers() {
 331         super.pauseTimers();
 332     }
 333
 334     /**
 335      * Resume all layout, parsing and JavaScript timers for all XWalkView instances.
 336      * It will be called when the container Activity get resumed. It can also be explicitly
 337      * called to resume timers.
 338      *
 339      * Note that it will globally impact all XWalkView instances, not limited to
 340      * just this XWalkView.
 341      *
 342      * @since 1.0
 343      */
 344     public void resumeTimers() {
 345         super.resumeTimers();
 346     }
 347
 348     /**
 349      * Pause many other things except JavaScript timers inside rendering engine,
 350      * like video player, modal dialogs, etc. See {@link #pauseTimers} about pausing
 351      * JavaScript timers.
 352      * It will be called when the container Activity get paused. It can also be explicitly
 353      * called to pause above things.
 354      * @since 1.0
 355      */
 356     public void onHide() {
 357         super.onHide();
 358     }
 359
 360     /**
 361      * Resume video player, modal dialogs. Embedders are in charge of calling
 362      * this during resuming this activity if they call onHide.
 363      * It will be called when the container Activity get resumed. It can also be explicitly
 364      * called to resume above things.
 365      * @since 1.0
 366      */
 367     public void onShow() {
 368         super.onShow();
 369     }
 370
 371     /**
 372      * Release internal resources occupied by this XWalkView.
 373      * It will be called when the container Activity get destroyed. It can also be explicitly
 374      * called to release resources.
 375      * @since 1.0
 376      */
 377     public void onDestroy() {
 378         super.onDestroy();
 379     }
 380
 381     /**
 382      * Pass through activity result to XWalkView. Many internal facilities need this
 383      * to handle activity result like JavaScript dialog, Crosswalk extensions, etc.
 384      * See <a href="http://developer.android.com/reference/android/app/Activity.html">
 385      * android.app.Activity.onActivityResult()</a>.
 386      * @param requestCode passed from android.app.Activity.onActivityResult().
 387      * @param resultCode passed from android.app.Activity.onActivityResult().
 388      * @param data passed from android.app.Activity.onActivityResult().
 389      * @since 1.0
 390      */
 391     public void onActivityResult(int requestCode, int resultCode, Intent data) {
 392         super.onActivityResult(requestCode, resultCode, data);
 393     }
 394
 395     /**
 396      * Pass through intents to XWalkView. Many internal facilities need this
 397      * to receive the intents like web notification. See
 398      * <a href="http://developer.android.com/reference/android/app/Activity.html">
 399      * android.app.Activity.onNewIntent()</a>.
 400      * @param intent passed from android.app.Activity.onNewIntent().
 401      * @since 1.0
 402      */
 403     public boolean onNewIntent(Intent intent) {
 404         return super.onNewIntent(intent);
 405     }
 406
 407     /**
 408      * Save current internal state of this XWalkView. This can help restore this state
 409      * afterwards restoring.
 410      * @param outState the saved state for restoring.
 411      * @since 1.0
 412      */
 413     public boolean saveState(Bundle outState) {
 414         return super.saveState(outState);
 415     }
 416
 417     /**
 418      * Restore the state from the saved bundle data.
 419      * @param inState the state saved from saveState().
 420      * @return true if it can restore the state.
 421      * @since 1.0
 422      */
 423     public boolean restoreState(Bundle inState) {
 424         return super.restoreState(inState);
 425     }
 426
 427     /**
 428      * Get the API version of Crosswalk embedding API.
 429      * @return the string of API level.
 430      * @since 1.0
 431      */
 432     // TODO(yongsheng): make it static?
 433     public String getAPIVersion() {
 434         return super.getAPIVersion();
 435     }
 436
 437     /**
 438      * Get the Crosswalk version.
 439      * @return the string of Crosswalk.
 440      * @since 1.0
 441      */
 442     // TODO(yongsheng): make it static?
 443     public String getXWalkVersion() {
 444         return super.getXWalkVersion();
 445     }
 446
 447     /**
 448      * Embedders use this to customize their handlers to events/callbacks related
 449      * to UI.
 450      * @param client the XWalkUIClient defined by callers.
 451      * @since 1.0
 452      */
 453     public void setUIClient(XWalkUIClient client) {
 454         super.setUIClient(client);
 455     }
 456
 457     /**
 458      * Embedders use this to customize their handlers to events/callbacks related
 459      * to resource loading.
 460      * @param client the XWalkResourceClient defined by callers.
 461      * @since 1.0
 462      */
 463     public void setResourceClient(XWalkResourceClient client) {
 464         super.setResourceClient(client);
 465     }
 466 }