1 /*

     2  * Copyright (C) 2005 Apple Computer, Inc.  All rights reserved.

     3  *

     4  * Redistribution and use in source and binary forms, with or without

     5  * modification, are permitted provided that the following conditions

     6  * are met:

     7  *

     8  * 1.  Redistributions of source code must retain the above copyright

     9  *     notice, this list of conditions and the following disclaimer. 

    10  * 2.  Redistributions in binary form must reproduce the above copyright

    11  *     notice, this list of conditions and the following disclaimer in the

    12  *     documentation and/or other materials provided with the distribution. 

    13  * 3.  Neither the name of Apple Computer, Inc. ("Apple") nor the names of

    14  *     its contributors may be used to endorse or promote products derived

    15  *     from this software without specific prior written permission. 

    16  *

    17  * THIS SOFTWARE IS PROVIDED BY APPLE AND ITS CONTRIBUTORS "AS IS" AND ANY

    18  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED

    19  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE

    20  * DISCLAIMED. IN NO EVENT SHALL APPLE OR ITS CONTRIBUTORS BE LIABLE FOR ANY

    21  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES

    22  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;

    23  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND

    24  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT

    25  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF

    26  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

    27  */

    28 

    29 #import <WebKit/WebView.h>

    30 #import <WebKit/WebFramePrivate.h>

    31 

    32 #if MAC_OS_X_VERSION_MAX_ALLOWED <= MAC_OS_X_VERSION_10_4

    33 #define WebNSInteger int

    34 #define WebNSUInteger unsigned int

    35 #else

    36 #define WebNSInteger NSInteger

    37 #define WebNSUInteger NSUInteger

    38 #endif

    39 

    40 @class NSError;

    41 @class WebFrame;

    42 @class WebPreferences;

    43 

    44 @protocol WebFormDelegate;

    45 

    46 extern NSString *_WebCanGoBackKey;

    47 extern NSString *_WebCanGoForwardKey;

    48 extern NSString *_WebEstimatedProgressKey;

    49 extern NSString *_WebIsLoadingKey;

    50 extern NSString *_WebMainFrameIconKey;

    51 extern NSString *_WebMainFrameTitleKey;

    52 extern NSString *_WebMainFrameURLKey;

    53 extern NSString *_WebMainFrameDocumentKey;

    54 

    55 // pending public WebElementDictionary keys

    56 extern NSString *WebElementTitleKey;             // NSString of the title of the element (used by Safari)

    57 extern NSString *WebElementSpellingToolTipKey;   // NSString of a tooltip representing misspelling or bad grammar (used internally)

    58 extern NSString *WebElementIsContentEditableKey; // NSNumber indicating whether the inner non-shared node is content editable (used internally)

    59 

    60 // other WebElementDictionary keys

    61 extern NSString *WebElementLinkIsLiveKey;        // NSNumber of BOOL indictating whether the link is live or not

    62 

    63 typedef enum {

    64     WebDashboardBehaviorAlwaysSendMouseEventsToAllWindows,

    65     WebDashboardBehaviorAlwaysSendActiveNullEventsToPlugIns,

    66     WebDashboardBehaviorAlwaysAcceptsFirstMouse,

    67     WebDashboardBehaviorAllowWheelScrolling,

    68     WebDashboardBehaviorUseBackwardCompatibilityMode

    69 } WebDashboardBehavior;

    70 

    71 @interface WebController : NSTreeController {

    72     IBOutlet WebView *webView;

    73 }

    74 - (WebView *)webView;

    75 - (void)setWebView:(WebView *)newWebView;

    76 @end

    77 

    78 @interface WebView (WebViewEditingActionsPendingPublic)

    79 

    80 - (void)outdent:(id)sender;

    81 

    82 @end

    83 

    84 @interface WebView (WebPendingPublic)

    85 

    86 /*!

    87 @method searchFor:direction:caseSensitive:wrap:startInSelection:

    88  @abstract Searches a document view for a string and highlights the string if it is found.

    89  Starts the search from the current selection.  Will search across all frames.

    90  @param string The string to search for.

    91  @param forward YES to search forward, NO to seach backwards.

    92  @param caseFlag YES to for case-sensitive search, NO for case-insensitive search.

    93  @param wrapFlag YES to wrap around, NO to avoid wrapping.

    94  @param startInSelection YES to begin search in the selected text (useful for incremental searching), NO to begin search after the selected text.

    95  @result YES if found, NO if not found.

    96  */

    97 - (BOOL)searchFor:(NSString *)string direction:(BOOL)forward caseSensitive:(BOOL)caseFlag wrap:(BOOL)wrapFlag startInSelection:(BOOL)startInSelection;

    98 

    99 - (void)setMainFrameDocumentReady:(BOOL)mainFrameDocumentReady;

   100 

   101 - (void)setTabKeyCyclesThroughElements:(BOOL)cyclesElements;

   102 - (BOOL)tabKeyCyclesThroughElements;

   103 

   104 - (void)scrollDOMRangeToVisible:(DOMRange *)range;

   105 

   106 // setHoverFeedbackSuspended: can be called by clients that want to temporarily prevent the webView

   107 // from displaying feedback about mouse position. Each WebDocumentView class that displays feedback

   108 // about mouse position should honor this setting.

   109 - (void)setHoverFeedbackSuspended:(BOOL)newValue;

   110 - (BOOL)isHoverFeedbackSuspended;

   111 

   112 /*!

   113 @method setScriptDebugDelegate:

   114 @abstract Set the WebView's WebScriptDebugDelegate delegate.

   115 @param delegate The WebScriptDebugDelegate to set as the delegate.

   116 */    

   117 - (void)setScriptDebugDelegate:(id)delegate;

   118 

   119 /*!

   120 @method scriptDebugDelegate

   121 @abstract Return the WebView's WebScriptDebugDelegate.

   122 @result The WebView's WebScriptDebugDelegate.

   123 */    

   124 - (id)scriptDebugDelegate;

   125 

   126 - (BOOL)shouldClose;

   127 

   128 /*!

   129     @method aeDescByEvaluatingJavaScriptFromString:

   130     @param script The text of the JavaScript.

   131     @result The result of the script, converted to an NSAppleEventDescriptor, or nil for failure.

   132 */

   133 - (NSAppleEventDescriptor *)aeDescByEvaluatingJavaScriptFromString:(NSString *)script;

   134 

   135 // Support for displaying multiple text matches.

   136 // These methods might end up moving into a protocol, so different document types can specify

   137 // whether or not they implement the protocol. For now we'll just deal with HTML.

   138 // These methods are still in flux; don't rely on them yet.

   139 - (BOOL)canMarkAllTextMatches;

   140 - (WebNSUInteger)markAllMatchesForText:(NSString *)string caseSensitive:(BOOL)caseFlag highlight:(BOOL)highlight limit:(WebNSUInteger)limit;

   141 - (void)unmarkAllTextMatches;

   142 - (NSArray *)rectsForTextMatches;

   143 

   144 // Support for disabling registration with the undo manager. This is equivalent to the methods with the same names on NSTextView.

   145 - (BOOL)allowsUndo;

   146 - (void)setAllowsUndo:(BOOL)flag;

   147 

   148 @end

   149 

   150 @interface WebView (WebPrivate)

   151 

   152 + (BOOL)_developerExtrasEnabled;

   153 + (BOOL)_scriptDebuggerEnabled;

   154 

   155 /*!

   156     @method setBackgroundColor:

   157     @param backgroundColor Color to use as the default background.

   158     @abstract Sets what color the receiver draws under transparent page background colors and images.

   159     This color is also used when no page is loaded. A color with alpha should only be used when the receiver is

   160     in a non-opaque window, since the color is drawn using NSCompositeCopy.

   161 */

   162 - (void)setBackgroundColor:(NSColor *)backgroundColor;

   163 

   164 /*!

   165     @method backgroundColor

   166     @result Returns the background color drawn under transparent page background colors and images.

   167     This color is also used when no page is loaded. A color with alpha should only be used when the receiver is

   168     in a non-opaque window, since the color is drawn using NSCompositeCopy.

   169 */

   170 - (NSColor *)backgroundColor;

   171 

   172 /*!

   173 Could be worth adding to the API.

   174  @method loadItemsFromOtherView:

   175  @abstract Loads the view with the contents of the other view, including its backforward list.

   176  @param otherView   The WebView from which to copy contents.

   177  */

   178 - (void)_loadBackForwardListFromOtherView:(WebView *)otherView;

   179 

   180 + (NSArray *)_supportedFileExtensions;

   181 

   182 /*!

   183     @method canShowFile:

   184     @abstract Checks if the WebKit can show the content of the file at the specified path.

   185     @param path The path of the file to check

   186     @result YES if the WebKit can show the content of the file at the specified path.

   187 */

   188 + (BOOL)canShowFile:(NSString *)path;

   189 

   190 /*!

   191     @method suggestedFileExtensionForMIMEType:

   192     @param MIMEType The MIME type to check.

   193     @result The extension based on the MIME type

   194 */

   195 + (NSString *)suggestedFileExtensionForMIMEType: (NSString *)MIMEType;

   196 

   197 // May well become public

   198 - (void)_setFormDelegate:(id<WebFormDelegate>)delegate;

   199 - (id<WebFormDelegate>)_formDelegate;

   200 

   201 - (BOOL)_isClosed;

   202 - (void)_close;

   203 

   204 /*!

   205     @method _registerViewClass:representationClass:forURLScheme:

   206     @discussion Register classes that implement WebDocumentView and WebDocumentRepresentation respectively.

   207     @param viewClass The WebDocumentView class to use to render data for a given MIME type.

   208     @param representationClass The WebDocumentRepresentation class to use to represent data of the given MIME type.

   209     @param scheme The URL scheme to represent with an object of the given class.

   210 */

   211 + (void)_registerViewClass:(Class)viewClass representationClass:(Class)representationClass forURLScheme:(NSString *)URLScheme;

   212 

   213 + (void)_unregisterViewClassAndRepresentationClassForMIMEType:(NSString *)MIMEType;

   214 

   215 /*!

   216      @method _canHandleRequest:

   217      @abstract Performs a "preflight" operation that performs some

   218      speculative checks to see if a request can be used to create

   219      a WebDocumentView and WebDocumentRepresentation.

   220      @discussion The result of this method is valid only as long as no

   221      protocols or schemes are registered or unregistered, and as long as

   222      the request is not mutated (if the request is mutable). Hence, clients

   223      should be prepared to handle failures even if they have performed request

   224      preflighting by caling this method.

   225      @param request The request to preflight.

   226      @result YES if it is likely that a WebDocumentView and WebDocumentRepresentation

   227      can be created for the request, NO otherwise.

   228 */

   229 + (BOOL)_canHandleRequest:(NSURLRequest *)request;

   230 

   231 + (NSString *)_decodeData:(NSData *)data;

   232 

   233 + (void)_setAlwaysUseATSU:(BOOL)f;

   234 

   235 - (NSCachedURLResponse *)_cachedResponseForURL:(NSURL *)URL;

   236 

   237 - (void)_addScrollerDashboardRegions:(NSMutableDictionary *)regions;

   238 - (NSDictionary *)_dashboardRegions;

   239 

   240 - (void)_setDashboardBehavior:(WebDashboardBehavior)behavior to:(BOOL)flag;

   241 - (BOOL)_dashboardBehavior:(WebDashboardBehavior)behavior;

   242 

   243 + (void)_setShouldUseFontSmoothing:(BOOL)f;

   244 + (BOOL)_shouldUseFontSmoothing;

   245 

   246 - (void)_setCatchesDelegateExceptions:(BOOL)f;

   247 - (BOOL)_catchesDelegateExceptions;

   248 

   249 // These two methods are useful for a test harness that needs a consistent appearance for the focus rings

   250 // regardless of OS X version.

   251 + (void)_setUsesTestModeFocusRingColor:(BOOL)f;

   252 + (BOOL)_usesTestModeFocusRingColor;

   253 

   254 + (NSString *)_minimumRequiredSafariBuildNumber;

   255 

   256 /*!

   257     @method setAlwaysShowVerticalScroller:

   258     @result Forces the vertical scroller to be visible if flag is YES, otherwise

   259     if flag is NO the scroller with automatically show and hide as needed.

   260  */

   261 - (void)setAlwaysShowVerticalScroller:(BOOL)flag;

   262 

   263 /*!

   264     @method alwaysShowVerticalScroller

   265     @result YES if the vertical scroller is always shown

   266  */

   267 - (BOOL)alwaysShowVerticalScroller;

   268 

   269 /*!

   270     @method setAlwaysShowHorizontalScroller:

   271     @result Forces the horizontal scroller to be visible if flag is YES, otherwise

   272     if flag is NO the scroller with automatically show and hide as needed.

   273  */

   274 - (void)setAlwaysShowHorizontalScroller:(BOOL)flag;

   275 

   276 /*!

   277     @method alwaysShowHorizontalScroller

   278     @result YES if the horizontal scroller is always shown

   279  */

   280 - (BOOL)alwaysShowHorizontalScroller;

   281 

   282 /*!

   283     @method setProhibitsMainFrameScrolling:

   284     @abstract Prohibits scrolling in the WebView's main frame.  Used to "lock" a WebView

   285     to a specific scroll position.

   286   */

   287 - (void)setProhibitsMainFrameScrolling:(BOOL)prohibits;

   288 

   289 /*!

   290     @method _setAdditionalWebPlugInPaths:

   291     @abstract Sets additional plugin search paths for a specific WebView.

   292  */

   293 - (void)_setAdditionalWebPlugInPaths:(NSArray *)newPaths;

   294 

   295 /*!

   296     @method _setInViewSourceMode:

   297     @abstract Used to place a WebView into a special source-viewing mode.

   298   */

   299 - (void)_setInViewSourceMode:(BOOL)flag;

   300 

   301 /*!

   302     @method _inViewSourceMode;

   303     @abstract Whether or not the WebView is in source-view mode for HTML.

   304   */

   305 - (BOOL)_inViewSourceMode;

   306 

   307 /*!

   308     @method _attachScriptDebuggerToAllFrames

   309     @abstract Attaches a script debugger to all frames belonging to the receiver.

   310  */

   311 - (void)_attachScriptDebuggerToAllFrames;

   312 

   313 /*!

   314     @method _detachScriptDebuggerFromAllFrames

   315     @abstract Detaches any script debuggers from all frames belonging to the receiver.

   316  */

   317 - (void)_detachScriptDebuggerFromAllFrames;

   318 

   319 - (BOOL)defersCallbacks; // called by QuickTime plug-in

   320 - (void)setDefersCallbacks:(BOOL)defer; // called by QuickTime plug-in

   321 

   322 - (BOOL)usesPageCache;

   323 - (void)setUsesPageCache:(BOOL)usesPageCache;

   324 

   325 // <rdar://problem/5217124> Clients other than dashboard, don't use this.

   326 // Do not remove until Dashboard has moved off it

   327 - (void)handleAuthenticationForResource:(id)identifier challenge:(NSURLAuthenticationChallenge *)challenge fromDataSource:(WebDataSource *)dataSource;

   328 

   329 - (void)_clearUndoRedoOperations;

   330 

   331 /* Used to do fast (lower quality) scaling of images so that window resize can be quick. */

   332 - (BOOL)_inFastImageScalingMode;

   333 - (void)_setUseFastImageScalingMode:(BOOL)flag;

   334 

   335 @end

   336 

   337 @interface WebView (WebViewPrintingPrivate)

   338 /*!

   339     @method _adjustPrintingMarginsForHeaderAndFooter:

   340     @abstract Increase the top and bottom margins for the current print operation to

   341     account for the header and footer height. 

   342     @discussion Called by <WebDocument> implementors once when a print job begins. If the

   343     <WebDocument> implementor implements knowsPageRange:, this should be called from there.

   344     Otherwise this should be called from beginDocument. The <WebDocument> implementors need

   345     to also call _drawHeaderAndFooter.

   346 */

   347 - (void)_adjustPrintingMarginsForHeaderAndFooter;

   348 

   349 /*!

   350     @method _drawHeaderAndFooter

   351     @abstract Gives the WebView's UIDelegate a chance to draw a header and footer on the

   352     printed page. 

   353     @discussion This should be called by <WebDocument> implementors from an override of

   354     drawPageBorderWithSize:.

   355 */

   356 - (void)_drawHeaderAndFooter;

   357 @end

   358 

   359 @interface WebView (WebViewGrammarChecking)

   360 

   361 // FIXME: These two methods should be merged into WebViewEditing when we're not in API freeze

   362 - (BOOL)isGrammarCheckingEnabled;

   363 #ifndef BUILDING_ON_TIGER

   364 - (void)setGrammarCheckingEnabled:(BOOL)flag;

   365 

   366 // FIXME: This method should be merged into WebIBActions when we're not in API freeze

   367 - (void)toggleGrammarChecking:(id)sender;

   368 #endif

   369 @end

   370 

   371 @interface WebView (WebViewEditingInMail)

   372 - (void)_insertNewlineInQuotedContent;

   373 - (void)_replaceSelectionWithNode:(DOMNode *)node matchStyle:(BOOL)matchStyle;

   374 @end

   375 

   376 @interface NSObject (WebFrameLoadDelegatePrivate)

   377 - (void)webView:(WebView *)sender didFirstLayoutInFrame:(WebFrame *)frame;

   378 

   379 // didFinishDocumentLoadForFrame is sent when the document has finished loading, though not necessarily all

   380 // of its subresources.

   381 // FIXME 5259339: Currently this callback is not sent for (some?) pages loaded entirely from the cache.

   382 - (void)webView:(WebView *)sender didFinishDocumentLoadForFrame:(WebFrame *)frame;

   383 

   384 // Addresses 4192534.  SPI for now.

   385 - (void)webView:(WebView *)sender didHandleOnloadEventsForFrame:(WebFrame *)frame;

   386 

   387 @end

   388 

   389 @interface NSObject (WebResourceLoadDelegatePrivate)

   390 // Addresses <rdar://problem/5008925> - SPI for now

   391 - (NSCachedURLResponse *)webView:(WebView *)sender resource:(id)identifier willCacheResponse:(NSCachedURLResponse *)response fromDataSource:(WebDataSource *)dataSource;

   392 @end

   393 

   394 #undef WebNSInteger

   395 #undef WebNSUInteger