WebChromeClient.java revision 1b6e10bccae4fd1a2457fed5d12663ba3a37fc79
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 17package android.webkit; 18 19import android.content.pm.ActivityInfo; 20import android.graphics.Bitmap; 21import android.net.Uri; 22import android.os.Message; 23import android.view.View; 24 25public class WebChromeClient { 26 27 /** 28 * Tell the host application the current progress of loading a page. 29 * @param view The WebView that initiated the callback. 30 * @param newProgress Current page loading progress, represented by 31 * an integer between 0 and 100. 32 */ 33 public void onProgressChanged(WebView view, int newProgress) {} 34 35 /** 36 * Notify the host application of a change in the document title. 37 * @param view The WebView that initiated the callback. 38 * @param title A String containing the new title of the document. 39 */ 40 public void onReceivedTitle(WebView view, String title) {} 41 42 /** 43 * Notify the host application of a new favicon for the current page. 44 * @param view The WebView that initiated the callback. 45 * @param icon A Bitmap containing the favicon for the current page. 46 */ 47 public void onReceivedIcon(WebView view, Bitmap icon) {} 48 49 /** 50 * Notify the host application of the url for an apple-touch-icon. 51 * @param view The WebView that initiated the callback. 52 * @param url The icon url. 53 * @param precomposed True if the url is for a precomposed touch icon. 54 */ 55 public void onReceivedTouchIconUrl(WebView view, String url, 56 boolean precomposed) {} 57 58 /** 59 * A callback interface used by the host application to notify 60 * the current page that its custom view has been dismissed. 61 */ 62 public interface CustomViewCallback { 63 /** 64 * Invoked when the host application dismisses the 65 * custom view. 66 */ 67 public void onCustomViewHidden(); 68 } 69 70 /** 71 * Notify the host application that the current page would 72 * like to show a custom View. This is used for Fullscreen 73 * video playback; see "HTML5 Video support" documentation on 74 * {@link WebView}. 75 * @param view is the View object to be shown. 76 * @param callback is the callback to be invoked if and when the view 77 * is dismissed. 78 */ 79 public void onShowCustomView(View view, CustomViewCallback callback) {}; 80 81 /** 82 * Notify the host application that the current page would 83 * like to show a custom View in a particular orientation. 84 * @param view is the View object to be shown. 85 * @param requestedOrientation An orientation constant as used in 86 * {@link ActivityInfo#screenOrientation ActivityInfo.screenOrientation}. 87 * @param callback is the callback to be invoked if and when the view 88 * is dismissed. 89 * @deprecated This method supports the obsolete plugin mechanism, 90 * and will not be invoked in future 91 */ 92 @Deprecated 93 public void onShowCustomView(View view, int requestedOrientation, 94 CustomViewCallback callback) {}; 95 96 /** 97 * Notify the host application that the current page would 98 * like to hide its custom view. 99 */ 100 public void onHideCustomView() {} 101 102 /** 103 * Request the host application to create a new window. If the host 104 * application chooses to honor this request, it should return true from 105 * this method, create a new WebView to host the window, insert it into the 106 * View system and send the supplied resultMsg message to its target with 107 * the new WebView as an argument. If the host application chooses not to 108 * honor the request, it should return false from this method. The default 109 * implementation of this method does nothing and hence returns false. 110 * @param view The WebView from which the request for a new window 111 * originated. 112 * @param isDialog True if the new window should be a dialog, rather than 113 * a full-size window. 114 * @param isUserGesture True if the request was initiated by a user gesture, 115 * such as the user clicking a link. 116 * @param resultMsg The message to send when once a new WebView has been 117 * created. resultMsg.obj is a 118 * {@link WebView.WebViewTransport} object. This should be 119 * used to transport the new WebView, by calling 120 * {@link WebView.WebViewTransport#setWebView(WebView) 121 * WebView.WebViewTransport.setWebView(WebView)}. 122 * @return This method should return true if the host application will 123 * create a new window, in which case resultMsg should be sent to 124 * its target. Otherwise, this method should return false. Returning 125 * false from this method but also sending resultMsg will result in 126 * undefined behavior. 127 */ 128 public boolean onCreateWindow(WebView view, boolean isDialog, 129 boolean isUserGesture, Message resultMsg) { 130 return false; 131 } 132 133 /** 134 * Request display and focus for this WebView. This may happen due to 135 * another WebView opening a link in this WebView and requesting that this 136 * WebView be displayed. 137 * @param view The WebView that needs to be focused. 138 */ 139 public void onRequestFocus(WebView view) {} 140 141 /** 142 * Notify the host application to close the given WebView and remove it 143 * from the view system if necessary. At this point, WebCore has stopped 144 * any loading in this window and has removed any cross-scripting ability 145 * in javascript. 146 * @param window The WebView that needs to be closed. 147 */ 148 public void onCloseWindow(WebView window) {} 149 150 /** 151 * Tell the client to display a javascript alert dialog. If the client 152 * returns true, WebView will assume that the client will handle the 153 * dialog. If the client returns false, it will continue execution. 154 * @param view The WebView that initiated the callback. 155 * @param url The url of the page requesting the dialog. 156 * @param message Message to be displayed in the window. 157 * @param result A JsResult to confirm that the user hit enter. 158 * @return boolean Whether the client will handle the alert dialog. 159 */ 160 public boolean onJsAlert(WebView view, String url, String message, 161 JsResult result) { 162 return false; 163 } 164 165 /** 166 * Tell the client to display a confirm dialog to the user. If the client 167 * returns true, WebView will assume that the client will handle the 168 * confirm dialog and call the appropriate JsResult method. If the 169 * client returns false, a default value of false will be returned to 170 * javascript. The default behavior is to return false. 171 * @param view The WebView that initiated the callback. 172 * @param url The url of the page requesting the dialog. 173 * @param message Message to be displayed in the window. 174 * @param result A JsResult used to send the user's response to 175 * javascript. 176 * @return boolean Whether the client will handle the confirm dialog. 177 */ 178 public boolean onJsConfirm(WebView view, String url, String message, 179 JsResult result) { 180 return false; 181 } 182 183 /** 184 * Tell the client to display a prompt dialog to the user. If the client 185 * returns true, WebView will assume that the client will handle the 186 * prompt dialog and call the appropriate JsPromptResult method. If the 187 * client returns false, a default value of false will be returned to to 188 * javascript. The default behavior is to return false. 189 * @param view The WebView that initiated the callback. 190 * @param url The url of the page requesting the dialog. 191 * @param message Message to be displayed in the window. 192 * @param defaultValue The default value displayed in the prompt dialog. 193 * @param result A JsPromptResult used to send the user's reponse to 194 * javascript. 195 * @return boolean Whether the client will handle the prompt dialog. 196 */ 197 public boolean onJsPrompt(WebView view, String url, String message, 198 String defaultValue, JsPromptResult result) { 199 return false; 200 } 201 202 /** 203 * Tell the client to display a dialog to confirm navigation away from the 204 * current page. This is the result of the onbeforeunload javascript event. 205 * If the client returns true, WebView will assume that the client will 206 * handle the confirm dialog and call the appropriate JsResult method. If 207 * the client returns false, a default value of true will be returned to 208 * javascript to accept navigation away from the current page. The default 209 * behavior is to return false. Setting the JsResult to true will navigate 210 * away from the current page, false will cancel the navigation. 211 * @param view The WebView that initiated the callback. 212 * @param url The url of the page requesting the dialog. 213 * @param message Message to be displayed in the window. 214 * @param result A JsResult used to send the user's response to 215 * javascript. 216 * @return boolean Whether the client will handle the confirm dialog. 217 */ 218 public boolean onJsBeforeUnload(WebView view, String url, String message, 219 JsResult result) { 220 return false; 221 } 222 223 /** 224 * Tell the client that the quota has been exceeded for the Web SQL Database 225 * API for a particular origin and request a new quota. The client must 226 * respond by invoking the 227 * {@link WebStorage.QuotaUpdater#updateQuota(long) updateQuota(long)} 228 * method of the supplied {@link WebStorage.QuotaUpdater} instance. The 229 * minimum value that can be set for the new quota is the current quota. The 230 * default implementation responds with the current quota, so the quota will 231 * not be increased. 232 * @param url The URL of the page that triggered the notification 233 * @param databaseIdentifier The identifier of the database where the quota 234 * was exceeded. 235 * @param quota The quota for the origin, in bytes 236 * @param estimatedDatabaseSize The estimated size of the offending 237 * database, in bytes 238 * @param totalQuota The total quota for all origins, in bytes 239 * @param quotaUpdater An instance of {@link WebStorage.QuotaUpdater} which 240 * must be used to inform the WebView of the new quota. 241 * @deprecated This method is no longer called; WebView now uses the HTML5 / JavaScript Quota 242 * Management API. 243 */ 244 @Deprecated 245 public void onExceededDatabaseQuota(String url, String databaseIdentifier, 246 long quota, long estimatedDatabaseSize, long totalQuota, 247 WebStorage.QuotaUpdater quotaUpdater) { 248 // This default implementation passes the current quota back to WebCore. 249 // WebCore will interpret this that new quota was declined. 250 quotaUpdater.updateQuota(quota); 251 } 252 253 /** 254 * Notify the host application that the Application Cache has reached the 255 * maximum size. The client must respond by invoking the 256 * {@link WebStorage.QuotaUpdater#updateQuota(long) updateQuota(long)} 257 * method of the supplied {@link WebStorage.QuotaUpdater} instance. The 258 * minimum value that can be set for the new quota is the current quota. The 259 * default implementation responds with the current quota, so the quota will 260 * not be increased. 261 * @param requiredStorage The amount of storage required by the Application 262 * Cache operation that triggered this notification, 263 * in bytes. 264 * @param quota the current maximum Application Cache size, in bytes 265 * @param quotaUpdater An instance of {@link WebStorage.QuotaUpdater} which 266 * must be used to inform the WebView of the new quota. 267 * @deprecated This method is no longer called; WebView now uses the HTML5 / JavaScript Quota 268 * Management API. 269 */ 270 @Deprecated 271 public void onReachedMaxAppCacheSize(long requiredStorage, long quota, 272 WebStorage.QuotaUpdater quotaUpdater) { 273 quotaUpdater.updateQuota(quota); 274 } 275 276 /** 277 * Notify the host application that web content from the specified origin 278 * is attempting to use the Geolocation API, but no permission state is 279 * currently set for that origin. The host application should invoke the 280 * specified callback with the desired permission state. See 281 * {@link GeolocationPermissions} for details. 282 * @param origin The origin of the web content attempting to use the 283 * Geolocation API. 284 * @param callback The callback to use to set the permission state for the 285 * origin. 286 */ 287 public void onGeolocationPermissionsShowPrompt(String origin, 288 GeolocationPermissions.Callback callback) {} 289 290 /** 291 * Notify the host application that a request for Geolocation permissions, 292 * made with a previous call to 293 * {@link #onGeolocationPermissionsShowPrompt(String,GeolocationPermissions.Callback) onGeolocationPermissionsShowPrompt()} 294 * has been canceled. Any related UI should therefore be hidden. 295 */ 296 public void onGeolocationPermissionsHidePrompt() {} 297 298 /** 299 * Notify the host application that web content is requesting permission to 300 * access the specified resources and the permission currently isn't granted 301 * or denied. The host application must invoke {@link PermissionRequest#grant(long)} 302 * or {@link PermissionRequest#deny()}. 303 * 304 * If this method isn't overridden, the permission is denied. 305 * 306 * @param request the PermissionRequest from current web content. 307 */ 308 public void onPermissionRequest(PermissionRequest request) { 309 request.deny(); 310 } 311 312 /** 313 * Notify the host application that the given permission request 314 * has been canceled. Any related UI should therefore be hidden. 315 * 316 * @param request the PermissionRequest that needs be canceled. 317 */ 318 public void onPermissionRequestCanceled(PermissionRequest request) {} 319 320 /** 321 * Tell the client that a JavaScript execution timeout has occured. And the 322 * client may decide whether or not to interrupt the execution. If the 323 * client returns true, the JavaScript will be interrupted. If the client 324 * returns false, the execution will continue. Note that in the case of 325 * continuing execution, the timeout counter will be reset, and the callback 326 * will continue to occur if the script does not finish at the next check 327 * point. 328 * @return boolean Whether the JavaScript execution should be interrupted. 329 * @deprecated This method is no longer supported and will not be invoked. 330 */ 331 // This method was only called when using the JSC javascript engine. V8 became 332 // the default JS engine with Froyo and support for building with JSC was 333 // removed in b/5495373. V8 does not have a mechanism for making a callback such 334 // as this. 335 public boolean onJsTimeout() { 336 return true; 337 } 338 339 /** 340 * Report a JavaScript error message to the host application. The ChromeClient 341 * should override this to process the log message as they see fit. 342 * @param message The error message to report. 343 * @param lineNumber The line number of the error. 344 * @param sourceID The name of the source file that caused the error. 345 * @deprecated Use {@link #onConsoleMessage(ConsoleMessage) onConsoleMessage(ConsoleMessage)} 346 * instead. 347 */ 348 @Deprecated 349 public void onConsoleMessage(String message, int lineNumber, String sourceID) { } 350 351 /** 352 * Report a JavaScript console message to the host application. The ChromeClient 353 * should override this to process the log message as they see fit. 354 * @param consoleMessage Object containing details of the console message. 355 * @return true if the message is handled by the client. 356 */ 357 public boolean onConsoleMessage(ConsoleMessage consoleMessage) { 358 // Call the old version of this function for backwards compatability. 359 onConsoleMessage(consoleMessage.message(), consoleMessage.lineNumber(), 360 consoleMessage.sourceId()); 361 return false; 362 } 363 364 /** 365 * When not playing, video elements are represented by a 'poster' image. The 366 * image to use can be specified by the poster attribute of the video tag in 367 * HTML. If the attribute is absent, then a default poster will be used. This 368 * method allows the ChromeClient to provide that default image. 369 * 370 * @return Bitmap The image to use as a default poster, or null if no such image is 371 * available. 372 */ 373 public Bitmap getDefaultVideoPoster() { 374 return null; 375 } 376 377 /** 378 * When the user starts to playback a video element, it may take time for enough 379 * data to be buffered before the first frames can be rendered. While this buffering 380 * is taking place, the ChromeClient can use this function to provide a View to be 381 * displayed. For example, the ChromeClient could show a spinner animation. 382 * 383 * @return View The View to be displayed whilst the video is loading. 384 */ 385 public View getVideoLoadingProgressView() { 386 return null; 387 } 388 389 /** Obtains a list of all visited history items, used for link coloring 390 */ 391 public void getVisitedHistory(ValueCallback<String[]> callback) { 392 } 393 394 /** 395 * Tell the client to show a file chooser. 396 * 397 * This is called to handle HTML forms with 'file' input type, in response to the 398 * user pressing the "Select File" button. 399 * To cancel the request, call <code>filePathCallback.onReceiveValue(null)</code> and 400 * return true. 401 * 402 * @param webView The WebView instance that is initiating the request. 403 * @param filePathCallback Invoke this callback to supply the list of paths to files to upload, 404 * or NULL to cancel. Must only be called if the 405 * <code>showFileChooser</code> implementations returns true. 406 * @param fileChooserParams Describes the mode of file chooser to be opened, and options to be 407 * used with it. 408 * @return true if filePathCallback will be invoked, false to use default handling. 409 * 410 * @see FileChooserParams 411 */ 412 public boolean showFileChooser(WebView webView, ValueCallback<Uri[]> filePathCallback, 413 FileChooserParams fileChooserParams) { 414 return false; 415 } 416 417 /** 418 * Parameters used in the {@link #showFileChooser} method. 419 * This is intended to be used as a read-only data struct by the application. 420 */ 421 public static class FileChooserParams { 422 // Flags for mode 423 /** Bitflag for <code>mode</code> indicating multiple files maybe selected */ 424 public static final int MODE_OPEN_MULTIPLE = 1 << 0; 425 /** Bitflag for <code>mode</code> indicating a folder maybe selected. 426 * The implementation should enumerate all files selected by this operation */ 427 public static final int MODE_OPEN_FOLDER = 1 << 1; 428 /** Bitflag for <code>mode</code> indicating a non-existant filename maybe returned */ 429 public static final int MODE_SAVE = 1 << 2; 430 431 /** 432 * Bit-field of the <code>MODE_</code> flags. 433 * 434 * 0 indicates plain single file open. 435 */ 436 public int mode; 437 438 /** 439 * Comma-seperated list of acceptable MIME types. 440 */ 441 public String acceptTypes; 442 443 /** 444 * true indicates a preference for a live media captured value (e.g. Camera, Microphone). 445 * 446 * Use <code>acceptTypes</code> to determine suitable capture devices. 447 */ 448 public boolean capture; 449 450 /** 451 * The title to use for this file selector, or null. 452 * 453 * Maybe null, in which case a default title should be used. 454 */ 455 public String title; 456 457 /** 458 * Name of a default selection if appropriate, or null. 459 */ 460 public String defaultFilename; 461 }; 462 463 /** 464 * Tell the client to open a file chooser. 465 * @param uploadFile A ValueCallback to set the URI of the file to upload. 466 * onReceiveValue must be called to wake up the thread.a 467 * @param acceptType The value of the 'accept' attribute of the input tag 468 * associated with this file picker. 469 * @param capture The value of the 'capture' attribute of the input tag 470 * associated with this file picker. 471 * 472 * @deprecated Use {@link #showFileChooser} instead. 473 * @hide This method was not published in any SDK version. 474 */ 475 @Deprecated 476 public void openFileChooser(ValueCallback<Uri> uploadFile, String acceptType, String capture) { 477 uploadFile.onReceiveValue(null); 478 } 479 480 /** 481 * Tell the client that the page being viewed has an autofillable 482 * form and the user would like to set a profile up. 483 * @param msg A Message to send once the user has successfully 484 * set up a profile and to inform the WebTextView it should 485 * now autofill using that new profile. 486 * @hide 487 */ 488 public void setupAutoFill(Message msg) { } 489 490} 491