1 /* 2 * Copyright (C) 2008 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package android.webkit; 18 19 import android.annotation.Nullable; 20 import android.annotation.SystemApi; 21 import android.content.Intent; 22 import android.content.pm.ActivityInfo; 23 import android.graphics.Bitmap; 24 import android.net.Uri; 25 import android.os.Message; 26 import android.view.View; 27 28 public class WebChromeClient { 29 30 /** 31 * Tell the host application the current progress of loading a page. 32 * @param view The WebView that initiated the callback. 33 * @param newProgress Current page loading progress, represented by 34 * an integer between 0 and 100. 35 */ onProgressChanged(WebView view, int newProgress)36 public void onProgressChanged(WebView view, int newProgress) {} 37 38 /** 39 * Notify the host application of a change in the document title. 40 * @param view The WebView that initiated the callback. 41 * @param title A String containing the new title of the document. 42 */ onReceivedTitle(WebView view, String title)43 public void onReceivedTitle(WebView view, String title) {} 44 45 /** 46 * Notify the host application of a new favicon for the current page. 47 * @param view The WebView that initiated the callback. 48 * @param icon A Bitmap containing the favicon for the current page. 49 */ onReceivedIcon(WebView view, Bitmap icon)50 public void onReceivedIcon(WebView view, Bitmap icon) {} 51 52 /** 53 * Notify the host application of the url for an apple-touch-icon. 54 * @param view The WebView that initiated the callback. 55 * @param url The icon url. 56 * @param precomposed {@code true} if the url is for a precomposed touch icon. 57 */ onReceivedTouchIconUrl(WebView view, String url, boolean precomposed)58 public void onReceivedTouchIconUrl(WebView view, String url, 59 boolean precomposed) {} 60 61 /** 62 * A callback interface used by the host application to notify 63 * the current page that its custom view has been dismissed. 64 */ 65 public interface CustomViewCallback { 66 /** 67 * Invoked when the host application dismisses the 68 * custom view. 69 */ onCustomViewHidden()70 public void onCustomViewHidden(); 71 } 72 73 /** 74 * Notify the host application that the current page has entered full screen mode. After this 75 * call, web content will no longer be rendered in the WebView, but will instead be rendered 76 * in {@code view}. The host application should add this View to a Window which is configured 77 * with {@link android.view.WindowManager.LayoutParams#FLAG_FULLSCREEN} flag in order to 78 * actually display this web content full screen. 79 * 80 * <p>The application may explicitly exit fullscreen mode by invoking {@code callback} (ex. when 81 * the user presses the back button). However, this is generally not necessary as the web page 82 * will often show its own UI to close out of fullscreen. Regardless of how the WebView exits 83 * fullscreen mode, WebView will invoke {@link #onHideCustomView()}, signaling for the 84 * application to remove the custom View. 85 * 86 * <p>If this method is not overridden, WebView will report to the web page it does not support 87 * fullscreen mode and will not honor the web page's request to run in fullscreen mode. 88 * 89 * <p class="note"><b>Note:</b> if overriding this method, the application must also override 90 * {@link #onHideCustomView()}. 91 * 92 * @param view is the View object to be shown. 93 * @param callback invoke this callback to request the page to exit 94 * full screen mode. 95 */ onShowCustomView(View view, CustomViewCallback callback)96 public void onShowCustomView(View view, CustomViewCallback callback) {}; 97 98 /** 99 * Notify the host application that the current page would 100 * like to show a custom View in a particular orientation. 101 * @param view is the View object to be shown. 102 * @param requestedOrientation An orientation constant as used in 103 * {@link ActivityInfo#screenOrientation ActivityInfo.screenOrientation}. 104 * @param callback is the callback to be invoked if and when the view 105 * is dismissed. 106 * @deprecated This method supports the obsolete plugin mechanism, 107 * and will not be invoked in future 108 */ 109 @Deprecated onShowCustomView(View view, int requestedOrientation, CustomViewCallback callback)110 public void onShowCustomView(View view, int requestedOrientation, 111 CustomViewCallback callback) {}; 112 113 /** 114 * Notify the host application that the current page has exited full screen mode. The host 115 * application must hide the custom View (the View which was previously passed to {@link 116 * #onShowCustomView(View, CustomViewCallback) onShowCustomView()}). After this call, web 117 * content will render in the original WebView again. 118 * 119 * <p class="note"><b>Note:</b> if overriding this method, the application must also override 120 * {@link #onShowCustomView(View, CustomViewCallback) onShowCustomView()}. 121 */ onHideCustomView()122 public void onHideCustomView() {} 123 124 /** 125 * Request the host application to create a new window. If the host 126 * application chooses to honor this request, it should return {@code true} from 127 * this method, create a new WebView to host the window, insert it into the 128 * View system and send the supplied resultMsg message to its target with 129 * the new WebView as an argument. If the host application chooses not to 130 * honor the request, it should return {@code false} from this method. The default 131 * implementation of this method does nothing and hence returns {@code false}. 132 * <p> 133 * Applications should typically not allow windows to be created when the 134 * {@code isUserGesture} flag is false, as this may be an unwanted popup. 135 * <p> 136 * Applications should be careful how they display the new window: don't simply 137 * overlay it over the existing WebView as this may mislead the user about which 138 * site they are viewing. If your application displays the URL of the main page, 139 * make sure to also display the URL of the new window in a similar fashion. If 140 * your application does not display URLs, consider disallowing the creation of 141 * new windows entirely. 142 * <p class="note"><b>Note:</b> There is no trustworthy way to tell which page 143 * requested the new window: the request might originate from a third-party iframe 144 * inside the WebView. 145 * 146 * @param view The WebView from which the request for a new window 147 * originated. 148 * @param isDialog {@code true} if the new window should be a dialog, rather than 149 * a full-size window. 150 * @param isUserGesture {@code true} if the request was initiated by a user gesture, 151 * such as the user clicking a link. 152 * @param resultMsg The message to send when once a new WebView has been 153 * created. resultMsg.obj is a 154 * {@link WebView.WebViewTransport} object. This should be 155 * used to transport the new WebView, by calling 156 * {@link WebView.WebViewTransport#setWebView(WebView) 157 * WebView.WebViewTransport.setWebView(WebView)}. 158 * @return This method should return {@code true} if the host application will 159 * create a new window, in which case resultMsg should be sent to 160 * its target. Otherwise, this method should return {@code false}. Returning 161 * {@code false} from this method but also sending resultMsg will result in 162 * undefined behavior. 163 */ onCreateWindow(WebView view, boolean isDialog, boolean isUserGesture, Message resultMsg)164 public boolean onCreateWindow(WebView view, boolean isDialog, 165 boolean isUserGesture, Message resultMsg) { 166 return false; 167 } 168 169 /** 170 * Request display and focus for this WebView. This may happen due to 171 * another WebView opening a link in this WebView and requesting that this 172 * WebView be displayed. 173 * @param view The WebView that needs to be focused. 174 */ onRequestFocus(WebView view)175 public void onRequestFocus(WebView view) {} 176 177 /** 178 * Notify the host application to close the given WebView and remove it 179 * from the view system if necessary. At this point, WebCore has stopped 180 * any loading in this window and has removed any cross-scripting ability 181 * in javascript. 182 * <p> 183 * As with {@link #onCreateWindow}, the application should ensure that any 184 * URL or security indicator displayed is updated so that the user can tell 185 * that the page they were interacting with has been closed. 186 * 187 * @param window The WebView that needs to be closed. 188 */ onCloseWindow(WebView window)189 public void onCloseWindow(WebView window) {} 190 191 /** 192 * Tell the client to display a javascript alert dialog. If the client 193 * returns {@code true}, WebView will assume that the client will handle the 194 * dialog. If the client returns {@code false}, it will continue execution. 195 * @param view The WebView that initiated the callback. 196 * @param url The url of the page requesting the dialog. 197 * @param message Message to be displayed in the window. 198 * @param result A JsResult to confirm that the user hit enter. 199 * @return boolean Whether the client will handle the alert dialog. 200 */ onJsAlert(WebView view, String url, String message, JsResult result)201 public boolean onJsAlert(WebView view, String url, String message, 202 JsResult result) { 203 return false; 204 } 205 206 /** 207 * Tell the client to display a confirm dialog to the user. If the client 208 * returns {@code true}, WebView will assume that the client will handle the 209 * confirm dialog and call the appropriate JsResult method. If the 210 * client returns false, a default value of {@code false} will be returned to 211 * javascript. The default behavior is to return {@code false}. 212 * @param view The WebView that initiated the callback. 213 * @param url The url of the page requesting the dialog. 214 * @param message Message to be displayed in the window. 215 * @param result A JsResult used to send the user's response to 216 * javascript. 217 * @return boolean Whether the client will handle the confirm dialog. 218 */ onJsConfirm(WebView view, String url, String message, JsResult result)219 public boolean onJsConfirm(WebView view, String url, String message, 220 JsResult result) { 221 return false; 222 } 223 224 /** 225 * Tell the client to display a prompt dialog to the user. If the client 226 * returns {@code true}, WebView will assume that the client will handle the 227 * prompt dialog and call the appropriate JsPromptResult method. If the 228 * client returns false, a default value of {@code false} will be returned to to 229 * javascript. The default behavior is to return {@code false}. 230 * @param view The WebView that initiated the callback. 231 * @param url The url of the page requesting the dialog. 232 * @param message Message to be displayed in the window. 233 * @param defaultValue The default value displayed in the prompt dialog. 234 * @param result A JsPromptResult used to send the user's reponse to 235 * javascript. 236 * @return boolean Whether the client will handle the prompt dialog. 237 */ onJsPrompt(WebView view, String url, String message, String defaultValue, JsPromptResult result)238 public boolean onJsPrompt(WebView view, String url, String message, 239 String defaultValue, JsPromptResult result) { 240 return false; 241 } 242 243 /** 244 * Tell the client to display a dialog to confirm navigation away from the 245 * current page. This is the result of the onbeforeunload javascript event. 246 * If the client returns {@code true}, WebView will assume that the client will 247 * handle the confirm dialog and call the appropriate JsResult method. If 248 * the client returns {@code false}, a default value of {@code true} will be returned to 249 * javascript to accept navigation away from the current page. The default 250 * behavior is to return {@code false}. Setting the JsResult to {@code true} will navigate 251 * away from the current page, {@code false} will cancel the navigation. 252 * @param view The WebView that initiated the callback. 253 * @param url The url of the page requesting the dialog. 254 * @param message Message to be displayed in the window. 255 * @param result A JsResult used to send the user's response to 256 * javascript. 257 * @return boolean Whether the client will handle the confirm dialog. 258 */ onJsBeforeUnload(WebView view, String url, String message, JsResult result)259 public boolean onJsBeforeUnload(WebView view, String url, String message, 260 JsResult result) { 261 return false; 262 } 263 264 /** 265 * Tell the client that the quota has been exceeded for the Web SQL Database 266 * API for a particular origin and request a new quota. The client must 267 * respond by invoking the 268 * {@link WebStorage.QuotaUpdater#updateQuota(long) updateQuota(long)} 269 * method of the supplied {@link WebStorage.QuotaUpdater} instance. The 270 * minimum value that can be set for the new quota is the current quota. The 271 * default implementation responds with the current quota, so the quota will 272 * not be increased. 273 * @param url The URL of the page that triggered the notification 274 * @param databaseIdentifier The identifier of the database where the quota 275 * was exceeded. 276 * @param quota The quota for the origin, in bytes 277 * @param estimatedDatabaseSize The estimated size of the offending 278 * database, in bytes 279 * @param totalQuota The total quota for all origins, in bytes 280 * @param quotaUpdater An instance of {@link WebStorage.QuotaUpdater} which 281 * must be used to inform the WebView of the new quota. 282 * @deprecated This method is no longer called; WebView now uses the HTML5 / JavaScript Quota 283 * Management API. 284 */ 285 @Deprecated onExceededDatabaseQuota(String url, String databaseIdentifier, long quota, long estimatedDatabaseSize, long totalQuota, WebStorage.QuotaUpdater quotaUpdater)286 public void onExceededDatabaseQuota(String url, String databaseIdentifier, 287 long quota, long estimatedDatabaseSize, long totalQuota, 288 WebStorage.QuotaUpdater quotaUpdater) { 289 // This default implementation passes the current quota back to WebCore. 290 // WebCore will interpret this that new quota was declined. 291 quotaUpdater.updateQuota(quota); 292 } 293 294 /** 295 * Notify the host application that the Application Cache has reached the 296 * maximum size. The client must respond by invoking the 297 * {@link WebStorage.QuotaUpdater#updateQuota(long) updateQuota(long)} 298 * method of the supplied {@link WebStorage.QuotaUpdater} instance. The 299 * minimum value that can be set for the new quota is the current quota. The 300 * default implementation responds with the current quota, so the quota will 301 * not be increased. 302 * @param requiredStorage The amount of storage required by the Application 303 * Cache operation that triggered this notification, 304 * in bytes. 305 * @param quota the current maximum Application Cache size, in bytes 306 * @param quotaUpdater An instance of {@link WebStorage.QuotaUpdater} which 307 * must be used to inform the WebView of the new quota. 308 * @deprecated This method is no longer called; WebView now uses the HTML5 / JavaScript Quota 309 * Management API. 310 */ 311 @Deprecated onReachedMaxAppCacheSize(long requiredStorage, long quota, WebStorage.QuotaUpdater quotaUpdater)312 public void onReachedMaxAppCacheSize(long requiredStorage, long quota, 313 WebStorage.QuotaUpdater quotaUpdater) { 314 quotaUpdater.updateQuota(quota); 315 } 316 317 /** 318 * Notify the host application that web content from the specified origin 319 * is attempting to use the Geolocation API, but no permission state is 320 * currently set for that origin. The host application should invoke the 321 * specified callback with the desired permission state. See 322 * {@link GeolocationPermissions} for details. 323 * 324 * <p>Note that for applications targeting Android N and later SDKs 325 * (API level > {@link android.os.Build.VERSION_CODES#M}) 326 * this method is only called for requests originating from secure 327 * origins such as https. On non-secure origins geolocation requests 328 * are automatically denied. 329 * 330 * @param origin The origin of the web content attempting to use the 331 * Geolocation API. 332 * @param callback The callback to use to set the permission state for the 333 * origin. 334 */ onGeolocationPermissionsShowPrompt(String origin, GeolocationPermissions.Callback callback)335 public void onGeolocationPermissionsShowPrompt(String origin, 336 GeolocationPermissions.Callback callback) {} 337 338 /** 339 * Notify the host application that a request for Geolocation permissions, 340 * made with a previous call to 341 * {@link #onGeolocationPermissionsShowPrompt(String,GeolocationPermissions.Callback) onGeolocationPermissionsShowPrompt()} 342 * has been canceled. Any related UI should therefore be hidden. 343 */ onGeolocationPermissionsHidePrompt()344 public void onGeolocationPermissionsHidePrompt() {} 345 346 /** 347 * Notify the host application that web content is requesting permission to 348 * access the specified resources and the permission currently isn't granted 349 * or denied. The host application must invoke {@link PermissionRequest#grant(String[])} 350 * or {@link PermissionRequest#deny()}. 351 * 352 * If this method isn't overridden, the permission is denied. 353 * 354 * @param request the PermissionRequest from current web content. 355 */ onPermissionRequest(PermissionRequest request)356 public void onPermissionRequest(PermissionRequest request) { 357 request.deny(); 358 } 359 360 /** 361 * Notify the host application that the given permission request 362 * has been canceled. Any related UI should therefore be hidden. 363 * 364 * @param request the PermissionRequest that needs be canceled. 365 */ onPermissionRequestCanceled(PermissionRequest request)366 public void onPermissionRequestCanceled(PermissionRequest request) {} 367 368 /** 369 * Tell the client that a JavaScript execution timeout has occured. And the 370 * client may decide whether or not to interrupt the execution. If the 371 * client returns {@code true}, the JavaScript will be interrupted. If the client 372 * returns {@code false}, the execution will continue. Note that in the case of 373 * continuing execution, the timeout counter will be reset, and the callback 374 * will continue to occur if the script does not finish at the next check 375 * point. 376 * @return boolean Whether the JavaScript execution should be interrupted. 377 * @deprecated This method is no longer supported and will not be invoked. 378 */ 379 // This method was only called when using the JSC javascript engine. V8 became 380 // the default JS engine with Froyo and support for building with JSC was 381 // removed in b/5495373. V8 does not have a mechanism for making a callback such 382 // as this. 383 @Deprecated onJsTimeout()384 public boolean onJsTimeout() { 385 return true; 386 } 387 388 /** 389 * Report a JavaScript error message to the host application. The ChromeClient 390 * should override this to process the log message as they see fit. 391 * @param message The error message to report. 392 * @param lineNumber The line number of the error. 393 * @param sourceID The name of the source file that caused the error. 394 * @deprecated Use {@link #onConsoleMessage(ConsoleMessage) onConsoleMessage(ConsoleMessage)} 395 * instead. 396 */ 397 @Deprecated onConsoleMessage(String message, int lineNumber, String sourceID)398 public void onConsoleMessage(String message, int lineNumber, String sourceID) { } 399 400 /** 401 * Report a JavaScript console message to the host application. The ChromeClient 402 * should override this to process the log message as they see fit. 403 * @param consoleMessage Object containing details of the console message. 404 * @return {@code true} if the message is handled by the client. 405 */ onConsoleMessage(ConsoleMessage consoleMessage)406 public boolean onConsoleMessage(ConsoleMessage consoleMessage) { 407 // Call the old version of this function for backwards compatability. 408 onConsoleMessage(consoleMessage.message(), consoleMessage.lineNumber(), 409 consoleMessage.sourceId()); 410 return false; 411 } 412 413 /** 414 * When not playing, video elements are represented by a 'poster' image. The 415 * image to use can be specified by the poster attribute of the video tag in 416 * HTML. If the attribute is absent, then a default poster will be used. This 417 * method allows the ChromeClient to provide that default image. 418 * 419 * @return Bitmap The image to use as a default poster, or {@code null} if no such image is 420 * available. 421 */ 422 @Nullable getDefaultVideoPoster()423 public Bitmap getDefaultVideoPoster() { 424 return null; 425 } 426 427 /** 428 * Obtains a View to be displayed while buffering of full screen video is taking 429 * place. The host application can override this method to provide a View 430 * containing a spinner or similar. 431 * 432 * @return View The View to be displayed whilst the video is loading. 433 */ 434 @Nullable getVideoLoadingProgressView()435 public View getVideoLoadingProgressView() { 436 return null; 437 } 438 439 /** Obtains a list of all visited history items, used for link coloring 440 */ getVisitedHistory(ValueCallback<String[]> callback)441 public void getVisitedHistory(ValueCallback<String[]> callback) { 442 } 443 444 /** 445 * Tell the client to show a file chooser. 446 * 447 * This is called to handle HTML forms with 'file' input type, in response to the 448 * user pressing the "Select File" button. 449 * To cancel the request, call <code>filePathCallback.onReceiveValue(null)</code> and 450 * return {@code true}. 451 * 452 * @param webView The WebView instance that is initiating the request. 453 * @param filePathCallback Invoke this callback to supply the list of paths to files to upload, 454 * or {@code null} to cancel. Must only be called if the 455 * {@link #onShowFileChooser} implementation returns {@code true}. 456 * @param fileChooserParams Describes the mode of file chooser to be opened, and options to be 457 * used with it. 458 * @return {@code true} if filePathCallback will be invoked, {@code false} to use default 459 * handling. 460 * 461 * @see FileChooserParams 462 */ onShowFileChooser(WebView webView, ValueCallback<Uri[]> filePathCallback, FileChooserParams fileChooserParams)463 public boolean onShowFileChooser(WebView webView, ValueCallback<Uri[]> filePathCallback, 464 FileChooserParams fileChooserParams) { 465 return false; 466 } 467 468 /** 469 * Parameters used in the {@link #onShowFileChooser} method. 470 */ 471 public static abstract class FileChooserParams { 472 /** Open single file. Requires that the file exists before allowing the user to pick it. */ 473 public static final int MODE_OPEN = 0; 474 /** Like Open but allows multiple files to be selected. */ 475 public static final int MODE_OPEN_MULTIPLE = 1; 476 /** Like Open but allows a folder to be selected. The implementation should enumerate 477 all files selected by this operation. 478 This feature is not supported at the moment. 479 @hide */ 480 public static final int MODE_OPEN_FOLDER = 2; 481 /** Allows picking a nonexistent file and saving it. */ 482 public static final int MODE_SAVE = 3; 483 484 /** 485 * Parse the result returned by the file picker activity. This method should be used with 486 * {@link #createIntent}. Refer to {@link #createIntent} for how to use it. 487 * 488 * @param resultCode the integer result code returned by the file picker activity. 489 * @param data the intent returned by the file picker activity. 490 * @return the Uris of selected file(s) or {@code null} if the resultCode indicates 491 * activity canceled or any other error. 492 */ 493 @Nullable parseResult(int resultCode, Intent data)494 public static Uri[] parseResult(int resultCode, Intent data) { 495 return WebViewFactory.getProvider().getStatics().parseFileChooserResult(resultCode, data); 496 } 497 498 /** 499 * Returns file chooser mode. 500 */ getMode()501 public abstract int getMode(); 502 503 /** 504 * Returns an array of acceptable MIME types. The returned MIME type 505 * could be partial such as audio/*. The array will be empty if no 506 * acceptable types are specified. 507 */ getAcceptTypes()508 public abstract String[] getAcceptTypes(); 509 510 /** 511 * Returns preference for a live media captured value (e.g. Camera, Microphone). 512 * True indicates capture is enabled, {@code false} disabled. 513 * 514 * Use <code>getAcceptTypes</code> to determine suitable capture devices. 515 */ isCaptureEnabled()516 public abstract boolean isCaptureEnabled(); 517 518 /** 519 * Returns the title to use for this file selector. If {@code null} a default title should 520 * be used. 521 */ 522 @Nullable getTitle()523 public abstract CharSequence getTitle(); 524 525 /** 526 * The file name of a default selection if specified, or {@code null}. 527 */ 528 @Nullable getFilenameHint()529 public abstract String getFilenameHint(); 530 531 /** 532 * Creates an intent that would start a file picker for file selection. 533 * The Intent supports choosing files from simple file sources available 534 * on the device. Some advanced sources (for example, live media capture) 535 * may not be supported and applications wishing to support these sources 536 * or more advanced file operations should build their own Intent. 537 * 538 * <p>How to use: 539 * <ol> 540 * <li>Build an intent using {@link #createIntent}</li> 541 * <li>Fire the intent using {@link android.app.Activity#startActivityForResult}.</li> 542 * <li>Check for ActivityNotFoundException and take a user friendly action if thrown.</li> 543 * <li>Listen the result using {@link android.app.Activity#onActivityResult}</li> 544 * <li>Parse the result using {@link #parseResult} only if media capture was not 545 * requested.</li> 546 * <li>Send the result using filePathCallback of {@link 547 * WebChromeClient#onShowFileChooser}</li> 548 * </ol> 549 * 550 * @return an Intent that supports basic file chooser sources. 551 */ createIntent()552 public abstract Intent createIntent(); 553 } 554 555 /** 556 * Tell the client to open a file chooser. 557 * @param uploadFile A ValueCallback to set the URI of the file to upload. 558 * onReceiveValue must be called to wake up the thread.a 559 * @param acceptType The value of the 'accept' attribute of the input tag 560 * associated with this file picker. 561 * @param capture The value of the 'capture' attribute of the input tag 562 * associated with this file picker. 563 * 564 * @deprecated Use {@link #onShowFileChooser} instead. 565 * @hide This method was not published in any SDK version. 566 */ 567 @SystemApi 568 @Deprecated openFileChooser(ValueCallback<Uri> uploadFile, String acceptType, String capture)569 public void openFileChooser(ValueCallback<Uri> uploadFile, String acceptType, String capture) { 570 uploadFile.onReceiveValue(null); 571 } 572 } 573