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.content.pm.ActivityInfo; 20 import android.graphics.Bitmap; 21 import android.net.Uri; 22 import android.os.Message; 23 import android.view.View; 24 25 public 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 */ onProgressChanged(WebView view, int newProgress)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 */ onReceivedTitle(WebView view, String title)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 */ onReceivedIcon(WebView view, Bitmap icon)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 */ onReceivedTouchIconUrl(WebView view, String url, boolean precomposed)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 */ onCustomViewHidden()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 */ onShowCustomView(View view, CustomViewCallback callback)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 onShowCustomView(View view, int requestedOrientation, CustomViewCallback callback)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 */ onHideCustomView()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 */ onCreateWindow(WebView view, boolean isDialog, boolean isUserGesture, Message resultMsg)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 */ onRequestFocus(WebView view)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 */ onCloseWindow(WebView window)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 */ onJsAlert(WebView view, String url, String message, JsResult result)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 */ onJsConfirm(WebView view, String url, String message, JsResult result)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 */ onJsPrompt(WebView view, String url, String message, String defaultValue, JsPromptResult result)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 */ onJsBeforeUnload(WebView view, String url, String message, JsResult result)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 */ 242 // Note that the callback must always be executed at some point to ensure 243 // that the sleeping WebCore thread is woken up. onExceededDatabaseQuota(String url, String databaseIdentifier, long quota, long estimatedDatabaseSize, long totalQuota, WebStorage.QuotaUpdater quotaUpdater)244 public void onExceededDatabaseQuota(String url, String databaseIdentifier, 245 long quota, long estimatedDatabaseSize, long totalQuota, 246 WebStorage.QuotaUpdater quotaUpdater) { 247 // This default implementation passes the current quota back to WebCore. 248 // WebCore will interpret this that new quota was declined. 249 quotaUpdater.updateQuota(quota); 250 } 251 252 /** 253 * Notify the host application that the Application Cache has reached the 254 * maximum size. The client must respond by invoking the 255 * {@link WebStorage.QuotaUpdater#updateQuota(long) updateQuota(long)} 256 * method of the supplied {@link WebStorage.QuotaUpdater} instance. The 257 * minimum value that can be set for the new quota is the current quota. The 258 * default implementation responds with the current quota, so the quota will 259 * not be increased. 260 * @param requiredStorage The amount of storage required by the Application 261 * Cache operation that triggered this notification, 262 * in bytes. 263 * @param quota the current maximum Application Cache size, in bytes 264 * @param quotaUpdater An instance of {@link WebStorage.QuotaUpdater} which 265 * must be used to inform the WebView of the new quota. 266 */ 267 // Note that the callback must always be executed at some point to ensure 268 // that the sleeping WebCore thread is woken up. onReachedMaxAppCacheSize(long requiredStorage, long quota, WebStorage.QuotaUpdater quotaUpdater)269 public void onReachedMaxAppCacheSize(long requiredStorage, long quota, 270 WebStorage.QuotaUpdater quotaUpdater) { 271 quotaUpdater.updateQuota(quota); 272 } 273 274 /** 275 * Notify the host application that web content from the specified origin 276 * is attempting to use the Geolocation API, but no permission state is 277 * currently set for that origin. The host application should invoke the 278 * specified callback with the desired permission state. See 279 * {@link GeolocationPermissions} for details. 280 * @param origin The origin of the web content attempting to use the 281 * Geolocation API. 282 * @param callback The callback to use to set the permission state for the 283 * origin. 284 */ onGeolocationPermissionsShowPrompt(String origin, GeolocationPermissions.Callback callback)285 public void onGeolocationPermissionsShowPrompt(String origin, 286 GeolocationPermissions.Callback callback) {} 287 288 /** 289 * Notify the host application that a request for Geolocation permissions, 290 * made with a previous call to 291 * {@link #onGeolocationPermissionsShowPrompt(String,GeolocationPermissions.Callback) onGeolocationPermissionsShowPrompt()} 292 * has been canceled. Any related UI should therefore be hidden. 293 */ onGeolocationPermissionsHidePrompt()294 public void onGeolocationPermissionsHidePrompt() {} 295 296 /** 297 * Tell the client that a JavaScript execution timeout has occured. And the 298 * client may decide whether or not to interrupt the execution. If the 299 * client returns true, the JavaScript will be interrupted. If the client 300 * returns false, the execution will continue. Note that in the case of 301 * continuing execution, the timeout counter will be reset, and the callback 302 * will continue to occur if the script does not finish at the next check 303 * point. 304 * @return boolean Whether the JavaScript execution should be interrupted. 305 * @deprecated This method is no longer supported and will not be invoked. 306 */ 307 // This method was only called when using the JSC javascript engine. V8 became 308 // the default JS engine with Froyo and support for building with JSC was 309 // removed in b/5495373. V8 does not have a mechanism for making a callback such 310 // as this. onJsTimeout()311 public boolean onJsTimeout() { 312 return true; 313 } 314 315 /** 316 * Report a JavaScript error message to the host application. The ChromeClient 317 * should override this to process the log message as they see fit. 318 * @param message The error message to report. 319 * @param lineNumber The line number of the error. 320 * @param sourceID The name of the source file that caused the error. 321 * @deprecated Use {@link #onConsoleMessage(ConsoleMessage) onConsoleMessage(ConsoleMessage)} 322 * instead. 323 */ 324 @Deprecated onConsoleMessage(String message, int lineNumber, String sourceID)325 public void onConsoleMessage(String message, int lineNumber, String sourceID) { } 326 327 /** 328 * Report a JavaScript console message to the host application. The ChromeClient 329 * should override this to process the log message as they see fit. 330 * @param consoleMessage Object containing details of the console message. 331 * @return true if the message is handled by the client. 332 */ onConsoleMessage(ConsoleMessage consoleMessage)333 public boolean onConsoleMessage(ConsoleMessage consoleMessage) { 334 // Call the old version of this function for backwards compatability. 335 onConsoleMessage(consoleMessage.message(), consoleMessage.lineNumber(), 336 consoleMessage.sourceId()); 337 return false; 338 } 339 340 /** 341 * When not playing, video elements are represented by a 'poster' image. The 342 * image to use can be specified by the poster attribute of the video tag in 343 * HTML. If the attribute is absent, then a default poster will be used. This 344 * method allows the ChromeClient to provide that default image. 345 * 346 * @return Bitmap The image to use as a default poster, or null if no such image is 347 * available. 348 */ getDefaultVideoPoster()349 public Bitmap getDefaultVideoPoster() { 350 return null; 351 } 352 353 /** 354 * When the user starts to playback a video element, it may take time for enough 355 * data to be buffered before the first frames can be rendered. While this buffering 356 * is taking place, the ChromeClient can use this function to provide a View to be 357 * displayed. For example, the ChromeClient could show a spinner animation. 358 * 359 * @return View The View to be displayed whilst the video is loading. 360 */ getVideoLoadingProgressView()361 public View getVideoLoadingProgressView() { 362 return null; 363 } 364 365 /** Obtains a list of all visited history items, used for link coloring 366 */ getVisitedHistory(ValueCallback<String[]> callback)367 public void getVisitedHistory(ValueCallback<String[]> callback) { 368 } 369 370 /** 371 * Tell the client to open a file chooser. 372 * @param uploadFile A ValueCallback to set the URI of the file to upload. 373 * onReceiveValue must be called to wake up the thread.a 374 * @param acceptType The value of the 'accept' attribute of the input tag 375 * associated with this file picker. 376 * @param capture The value of the 'capture' attribute of the input tag 377 * associated with this file picker. 378 * @hide 379 */ openFileChooser(ValueCallback<Uri> uploadFile, String acceptType, String capture)380 public void openFileChooser(ValueCallback<Uri> uploadFile, String acceptType, String capture) { 381 uploadFile.onReceiveValue(null); 382 } 383 384 /** 385 * Tell the client that the page being viewed has an autofillable 386 * form and the user would like to set a profile up. 387 * @param msg A Message to send once the user has successfully 388 * set up a profile and to inform the WebTextView it should 389 * now autofill using that new profile. 390 * @hide 391 */ setupAutoFill(Message msg)392 public void setupAutoFill(Message msg) { } 393 394 } 395