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