Reviewed by Darin
[WebKit-https.git] / WebKit / WebView / WebViewPrivate.h
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 @class NSError;
33 @class WebFrame;
34 @class WebPreferences;
35 @class WebCoreSettings;
36
37 @protocol WebFormDelegate;
38
39 typedef struct _WebResourceDelegateImplementationCache {
40     uint delegateImplementsDidCancelAuthenticationChallenge:1;
41     uint delegateImplementsDidReceiveAuthenticationChallenge:1;
42     uint delegateImplementsDidReceiveResponse:1;
43     uint delegateImplementsDidReceiveContentLength:1;
44     uint delegateImplementsDidFinishLoadingFromDataSource:1;
45     uint delegateImplementsWillSendRequest:1;
46     uint delegateImplementsIdentifierForRequest:1;
47 } WebResourceDelegateImplementationCache;
48
49 extern NSString *_WebCanGoBackKey;
50 extern NSString *_WebCanGoForwardKey;
51 extern NSString *_WebEstimatedProgressKey;
52 extern NSString *_WebIsLoadingKey;
53 extern NSString *_WebMainFrameIconKey;
54 extern NSString *_WebMainFrameTitleKey;
55 extern NSString *_WebMainFrameURLKey;
56 extern NSString *_WebMainFrameDocumentKey;
57
58 extern NSString *WebElementTitleKey;   // NSString of the title of the element (pending public, used by Safari)
59
60 typedef enum {
61     WebDashboardBehaviorAlwaysSendMouseEventsToAllWindows,
62     WebDashboardBehaviorAlwaysSendActiveNullEventsToPlugIns,
63     WebDashboardBehaviorAlwaysAcceptsFirstMouse,
64     WebDashboardBehaviorAllowWheelScrolling
65 } WebDashboardBehavior;
66
67 @interface WebController : NSTreeController {
68     IBOutlet WebView *webView;
69 }
70 - (WebView *)webView;
71 - (void)setWebView:(WebView *)newWebView;
72 @end
73
74 @interface WebView (WebPendingPublic)
75
76 - (void)setMainFrameDocumentReady:(BOOL)mainFrameDocumentReady;
77
78 - (void)setTabKeyCyclesThroughElements:(BOOL)cyclesElements;
79 - (BOOL)tabKeyCyclesThroughElements;
80
81 - (void)scrollDOMRangeToVisible:(DOMRange *)range;
82
83 /*!
84 @method setScriptDebugDelegate:
85 @abstract Set the WebView's WebScriptDebugDelegate delegate.
86 @param delegate The WebScriptDebugDelegate to set as the delegate.
87 */    
88 - (void)setScriptDebugDelegate:(id)delegate;
89
90 /*!
91 @method scriptDebugDelegate
92 @abstract Return the WebView's WebScriptDebugDelegate.
93 @result The WebView's WebScriptDebugDelegate.
94 */    
95 - (id)scriptDebugDelegate;
96
97 - (BOOL)shouldClose;
98
99 /*!
100     @method aeDescByEvaluatingJavaScriptFromString:
101     @param script The text of the JavaScript.
102     @result The result of the script, converted to an NSAppleEventDescriptor, or nil for failure.
103 */
104 - (NSAppleEventDescriptor *)aeDescByEvaluatingJavaScriptFromString:(NSString *)script;
105
106 // Support for displaying multiple text matches.
107 // These methods might end up moving into a protocol, so different document types can specify
108 // whether or not they implement the protocol. For now we'll just deal with HTML.
109 // These methods are still in flux; don't rely on them yet.
110 - (unsigned)markAllMatchesForText:(NSString *)string caseSensitive:(BOOL)caseFlag highlight:(BOOL)highlight limit:(unsigned)limit;
111 - (void)unmarkAllTextMatches;
112 - (NSArray *)rectsForTextMatches;
113
114 @end
115
116 @interface WebView (WebPrivate)
117
118 + (BOOL)_developerExtrasEnabled;
119 + (BOOL)_scriptDebuggerEnabled;
120
121 /*!
122     @method setBackgroundColor:
123     @param backgroundColor Color to use as the default background.
124     @abstract Sets what color the receiver draws under transparent page background colors and images.
125     This color is also used when no page is loaded. A color with alpha should only be used when the receiver is
126     in a non-opaque window, since the color is drawn using NSCompositeCopy.
127 */
128 - (void)setBackgroundColor:(NSColor *)backgroundColor;
129
130 /*!
131     @method backgroundColor
132     @result Returns the background color drawn under transparent page background colors and images.
133     This color is also used when no page is loaded. A color with alpha should only be used when the receiver is
134     in a non-opaque window, since the color is drawn using NSCompositeCopy.
135 */
136 - (NSColor *)backgroundColor;
137
138 /*!
139 Could be worth adding to the API.
140  @method loadItemsFromOtherView:
141  @abstract Loads the view with the contents of the other view, including its backforward list.
142  @param otherView   The WebView from which to copy contents.
143  */
144 - (void)_loadBackForwardListFromOtherView:(WebView *)otherView;
145
146 + (NSArray *)_supportedFileExtensions;
147
148 /*!
149     @method canShowFile:
150     @abstract Checks if the WebKit can show the content of the file at the specified path.
151     @param path The path of the file to check
152     @result YES if the WebKit can show the content of the file at the specified path.
153 */
154 + (BOOL)canShowFile:(NSString *)path;
155
156 /*!
157     @method suggestedFileExtensionForMIMEType:
158     @param MIMEType The MIME type to check.
159     @result The extension based on the MIME type
160 */
161 + (NSString *)suggestedFileExtensionForMIMEType: (NSString *)MIMEType;
162
163
164 // May well become public
165 - (void)_setFormDelegate:(id<WebFormDelegate>)delegate;
166 - (id<WebFormDelegate>)_formDelegate;
167
168 - (void)_close;
169
170 /*!
171     @method _registerViewClass:representationClass:forURLScheme:
172     @discussion Register classes that implement WebDocumentView and WebDocumentRepresentation respectively.
173     @param viewClass The WebDocumentView class to use to render data for a given MIME type.
174     @param representationClass The WebDocumentRepresentation class to use to represent data of the given MIME type.
175     @param scheme The URL scheme to represent with an object of the given class.
176 */
177 + (void)_registerViewClass:(Class)viewClass representationClass:(Class)representationClass forURLScheme:(NSString *)URLScheme;
178
179 + (void)_unregisterViewClassAndRepresentationClassForMIMEType:(NSString *)MIMEType;
180
181 /*!
182      @method _canHandleRequest:
183      @abstract Performs a "preflight" operation that performs some
184      speculative checks to see if a request can be used to create
185      a WebDocumentView and WebDocumentRepresentation.
186      @discussion The result of this method is valid only as long as no
187      protocols or schemes are registered or unregistered, and as long as
188      the request is not mutated (if the request is mutable). Hence, clients
189      should be prepared to handle failures even if they have performed request
190      preflighting by caling this method.
191      @param request The request to preflight.
192      @result YES if it is likely that a WebDocumentView and WebDocumentRepresentation
193      can be created for the request, NO otherwise.
194 */
195 + (BOOL)_canHandleRequest:(NSURLRequest *)request;
196
197 + (NSString *)_decodeData:(NSData *)data;
198
199 + (void)_setAlwaysUseATSU:(BOOL)f;
200
201 - (NSCachedURLResponse *)_cachedResponseForURL:(NSURL *)URL;
202
203 - (void)_addScrollerDashboardRegions:(NSMutableDictionary *)regions;
204 - (NSDictionary *)_dashboardRegions;
205
206 - (void)_setDashboardBehavior:(WebDashboardBehavior)behavior to:(BOOL)flag;
207 - (void)handleAuthenticationForResource:(id)identifier challenge:(NSURLAuthenticationChallenge *)challenge fromDataSource:(WebDataSource *)dataSource;
208 - (BOOL)_dashboardBehavior:(WebDashboardBehavior)behavior;
209
210 + (void)_setShouldUseFontSmoothing:(BOOL)f;
211 + (BOOL)_shouldUseFontSmoothing;
212
213 + (NSString *)_minimumRequiredSafariBuildNumber;
214
215 /*!
216     @method setAlwaysShowVerticalScroller:
217     @result Forces the vertical scroller to be visible if flag is YES, otherwise
218     if flag is NO the scroller with automatically show and hide as needed.
219  */
220 - (void)setAlwaysShowVerticalScroller:(BOOL)flag;
221
222 /*!
223     @method alwaysShowVerticalScroller
224     @result YES if the vertical scroller is always shown
225  */
226 - (BOOL)alwaysShowVerticalScroller;
227
228 /*!
229     @method setAlwaysShowHorizontalScroller:
230     @result Forces the horizontal scroller to be visible if flag is YES, otherwise
231     if flag is NO the scroller with automatically show and hide as needed.
232  */
233 - (void)setAlwaysShowHorizontalScroller:(BOOL)flag;
234
235 /*!
236     @method alwaysShowHorizontalScroller
237     @result YES if the horizontal scroller is always shown
238  */
239 - (BOOL)alwaysShowHorizontalScroller;
240
241 /*!
242     @method setProhibitsMainFrameScrolling:
243     @abstract Prohibits scrolling in the WebView's main frame.  Used to "lock" a WebView
244     to a specific scroll position.
245   */
246 - (void)setProhibitsMainFrameScrolling:(BOOL)prohibits;
247
248 /*!
249     @method _setAdditionalWebPlugInPaths:
250     @abstract Sets additional plugin search paths for a specific WebView.
251  */
252 - (void)_setAdditionalWebPlugInPaths:(NSArray *)newPaths;
253
254 /*!
255     @method _setInViewSourceMode:
256     @abstract Used to place a WebView into a special source-viewing mode.
257   */
258 - (void)_setInViewSourceMode:(BOOL)flag;
259
260 /*!
261     @method _inViewSourceMode;
262     @abstract Whether or not the WebView is in source-view mode for HTML.
263   */
264 - (BOOL)_inViewSourceMode;
265
266 /*!
267     @method _attachScriptDebuggerToAllFrames
268     @abstract Attaches a script debugger to all frames belonging to the receiver.
269  */
270 - (void)_attachScriptDebuggerToAllFrames;
271
272 /*!
273     @method _detachScriptDebuggerFromAllFrames
274     @abstract Detaches any script debuggers from all frames belonging to the receiver.
275  */
276 - (void)_detachScriptDebuggerFromAllFrames;
277
278 @end
279
280 @interface WebView (WebViewPrintingPrivate)
281 /*!
282     @method _adjustPrintingMarginsForHeaderAndFooter:
283     @abstract Increase the top and bottom margins for the current print operation to
284     account for the header and footer height. 
285     @discussion Called by <WebDocument> implementors once when a print job begins. If the
286     <WebDocument> implementor implements knowsPageRange:, this should be called from there.
287     Otherwise this should be called from beginDocument. The <WebDocument> implementors need
288     to also call _drawHeaderAndFooter.
289 */
290 - (void)_adjustPrintingMarginsForHeaderAndFooter;
291
292 /*!
293     @method _drawHeaderAndFooter
294     @abstract Gives the WebView's UIDelegate a chance to draw a header and footer on the
295     printed page. 
296     @discussion This should be called by <WebDocument> implementors from an override of
297     drawPageBorderWithSize:.
298 */
299 - (void)_drawHeaderAndFooter;
300 @end
301
302 #if !BUILDING_ON_TIGER
303 @interface WebView (WebViewGrammarChecking)
304
305 // FIXME: These two methods should be merged into WebViewEditing when we're not in API freeze
306 - (BOOL)isGrammarCheckingEnabled;
307 - (void)setGrammarCheckingEnabled:(BOOL)flag;
308
309 // FIXME: This method should be merged into WebIBActions when we're not in API freeze
310 - (void)toggleGrammarChecking:(id)sender;
311 @end
312 #endif
313
314 @interface WebView (WebViewEditingInMail)
315 - (void)_insertNewlineInQuotedContent;
316 - (BOOL)_selectWordBeforeMenuEvent;
317 - (void)_setSelectWordBeforeMenuEvent:(BOOL)flag;
318 - (void)_replaceSelectionWithNode:(DOMNode *)node matchStyle:(BOOL)matchStyle;
319 @end
320
321 @interface _WebSafeForwarder : NSObject
322 {
323     id target; // Non-retained. Don't retain delegates.
324     id defaultTarget;
325     Class templateClass;
326 }
327 - (id)initWithTarget:(id)t defaultTarget:(id)dt templateClass:(Class)aClass;
328 + (id)safeForwarderWithTarget:(id)t defaultTarget:(id)dt templateClass:(Class)aClass;
329 @end
330
331 @interface NSObject (WebFrameLoadDelegatePrivate)
332 - (void)webView:(WebView *)sender didFirstLayoutInFrame:(WebFrame *)frame;
333 // Addresses 4192534.  Private API for now.
334 - (void)webView:(WebView *)sender didHandleOnloadEventsForFrame:(WebFrame *)frame;
335 @end