webview.h

linux下开源浏览器WebKit的源码,市面上的很多商用浏览器都是移植自WebKit

/*
 * Copyright (C) 2003, 2004, 2005, 2006 Apple Computer, Inc.  All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * 1.  Redistributions of source code must retain the above copyright
 *     notice, this list of conditions and the following disclaimer. 
 * 2.  Redistributions in binary form must reproduce the above copyright
 *     notice, this list of conditions and the following disclaimer in the
 *     documentation and/or other materials provided with the distribution. 
 * 3.  Neither the name of Apple Computer, Inc. ("Apple") nor the names of
 *     its contributors may be used to endorse or promote products derived
 *     from this software without specific prior written permission. 
 *
 * THIS SOFTWARE IS PROVIDED BY APPLE AND ITS CONTRIBUTORS "AS IS" AND ANY
 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL APPLE OR ITS CONTRIBUTORS BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

#import <Cocoa/Cocoa.h>

#if MAC_OS_X_VERSION_MAX_ALLOWED <= MAC_OS_X_VERSION_10_4
#define WebNSInteger int
#else
#define WebNSInteger NSInteger
#endif

@class DOMCSSStyleDeclaration;
@class DOMDocument;
@class DOMElement;
@class DOMNode;
@class DOMRange;

@class WebArchive;
@class WebBackForwardList;
@class WebDataSource;
@class WebFrame;
@class WebFrameView;
@class WebHistoryItem;
@class WebPreferences;
@class WebScriptObject;
@class WebViewPrivate;

// Element dictionary keys
extern NSString *WebElementDOMNodeKey;          // DOMNode of the element
extern NSString *WebElementFrameKey;            // WebFrame of the element
extern NSString *WebElementImageAltStringKey;   // NSString of the ALT attribute of the image element
extern NSString *WebElementImageKey;            // NSImage of the image element
extern NSString *WebElementImageRectKey;        // NSValue of an NSRect, the rect of the image element
extern NSString *WebElementImageURLKey;         // NSURL of the image element
extern NSString *WebElementIsSelectedKey;       // NSNumber of BOOL indicating whether the element is selected or not 
extern NSString *WebElementLinkURLKey;          // NSURL of the link if the element is within an anchor
extern NSString *WebElementLinkTargetFrameKey;  // WebFrame of the target of the anchor
extern NSString *WebElementLinkTitleKey;        // NSString of the title of the anchor
extern NSString *WebElementLinkLabelKey;        // NSString of the text within the anchor

/*
    @discussion Notifications sent by WebView to mark the progress of loads.
    @constant WebViewProgressStartedNotification Posted whenever a load begins in the WebView, including
    a load that is initiated in a subframe.  After receiving this notification zero or more
    WebViewProgressEstimateChangedNotifications will be sent.  The userInfo will be nil.
    @constant WebViewProgressEstimateChangedNotification Posted whenever the value of
    estimatedProgress changes.  The userInfo will be nil.
    @constant WebViewProgressFinishedNotification Posted when the load for a WebView has finished.
    The userInfo will be nil.
*/
extern NSString *WebViewProgressStartedNotification;
extern NSString *WebViewProgressEstimateChangedNotification;
extern NSString *WebViewProgressFinishedNotification;

/*!
    @class WebView
    WebView manages the interaction between WebFrameViews and WebDataSources.  Modification
    of the policies and behavior of the WebKit is largely managed by WebViews and their
    delegates.
    
    <p>
    Typical usage:
    </p>
    <pre>
    WebView *webView;
    WebFrame *mainFrame;
    
    webView  = [[WebView alloc] initWithFrame: NSMakeRect (0,0,640,480)];
    mainFrame = [webView mainFrame];
    [mainFrame loadRequest:request];
    </pre>
    
    WebViews have the following delegates:  WebUIDelegate, WebResourceLoadDelegate,
    WebFrameLoadDelegate, and WebPolicyDelegate.
    
    WebKit depends on the WebView's WebUIDelegate for all window
    related management, including opening new windows and controlling the user interface
    elements in those windows.
    
    WebResourceLoadDelegate is used to monitor the progress of resources as they are
    loaded.  This delegate may be used to present users with a progress monitor.
    
    The WebFrameLoadDelegate receives messages when the URL in a WebFrame is
    changed.
    
    WebView's WebPolicyDelegate can make determinations about how
    content should be handled, based on the resource's URL and MIME type.
*/
@interface WebView : NSView
{
@private
    WebViewPrivate *_private;
}

/*!
    @method canShowMIMEType:
    @abstract Checks if the WebKit can show content of a certain MIME type.
    @param MIMEType The MIME type to check.
    @result YES if the WebKit can show content with MIMEtype.
*/
+ (BOOL)canShowMIMEType:(NSString *)MIMEType;


/*!
     @method canShowMIMETypeAsHTML:
     @abstract Checks if the the MIME type is a type that the WebKit will interpret as HTML.
     @param MIMEType The MIME type to check.
     @result YES if the MIMEtype in an HTML type.
*/
+ (BOOL)canShowMIMETypeAsHTML:(NSString *)MIMEType;

/*!
    @method MIMETypesShownAsHTML
    @result Returns an array of NSStrings that describe the MIME types
    WebKit will attempt to render as HTML.
*/
+ (NSArray *)MIMETypesShownAsHTML;

/*!
    @method setMIMETypesShownAsHTML:
    @discussion Sets the array of NSString MIME types that WebKit will
    attempt to render as HTML.  Typically you will retrieve the built-in
    array using MIMETypesShownAsHTML and add additional MIME types to that
    array.
*/
+ (void)setMIMETypesShownAsHTML:(NSArray *)MIMETypes;

/*!
    @method URLFromPasteboard:
    @abstract Returns a URL from a pasteboard
    @param pasteboard The pasteboard with a URL
    @result A URL if the pasteboard has one. Nil if it does not.
    @discussion This method differs than NSURL's URLFromPasteboard method in that it tries multiple pasteboard types
    including NSURLPboardType to find a URL on the pasteboard.
*/
+ (NSURL *)URLFromPasteboard:(NSPasteboard *)pasteboard;

/*!
    @method URLTitleFromPasteboard:
    @abstract Returns a URL title from a pasteboard
    @param pasteboard The pasteboard with a URL title
    @result A URL title if the pasteboard has one. Nil if it does not.
    @discussion This method returns a title that refers a URL on the pasteboard. An example of this is the link label
    which is the text inside the anchor tag.
*/
+ (NSString *)URLTitleFromPasteboard:(NSPasteboard *)pasteboard;

/*!
    @method registerURLSchemeAsLocal:
    @abstract Adds the scheme to the list of schemes to be treated as local.
    @param scheme The scheme to register
*/
+ (void)registerURLSchemeAsLocal:(NSString *)scheme;

/*!
    @method initWithFrame:frameName:groupName:
    @abstract The designated initializer for WebView.
    @discussion Initialize a WebView with the supplied parameters. This method will 
    create a main WebFrame with the view. Passing a top level frame name is useful if you
    handle a targetted frame navigation that would normally open a window in some other 
    way that still ends up creating a new WebView.
    @param frame The frame used to create the view.
    @param frameName The name to use for the top level frame. May be nil.
    @param groupName The name of the webView set to which this webView will be added.  May be nil.
    @result Returns an initialized WebView.
*/
- (id)initWithFrame:(NSRect)frame frameName:(NSString *)frameName groupName:(NSString *)groupName;

/*!
    @method close
    @abstract Closes the receiver, unloading its web page and canceling any pending loads.
    Once the receiver has closed, it will no longer respond to requests or fire delegate methods.
    (However, the -close method itself may fire delegate methods.)
    @discussion A garbage collected application is required to call close when the receiver is no longer needed.
    The close method will be called automatically when the window or hostWindow closes and shouldCloseWithWindow returns YES.
    A non-garbage collected application can still call close, providing a convenient way to prevent receiver
    from doing any more loading and firing any future delegate methods.
*/
- (void)close;

/*!
    @method setShouldCloseWithWindow:
    @abstract Set whether the receiver closes when either it's window or hostWindow closes.
    @param close YES if the receiver should close when either it's window or hostWindow closes, otherwise NO.
*/
- (void)setShouldCloseWithWindow:(BOOL)close;

/*!
    @method shouldCloseWithWindow
    @abstract Returns whether the receiver closes when either it's window or hostWindow closes.
    @discussion Defaults to YES in garbage collected applications, otherwise NO to maintain backwards compatibility.
    @result YES if the receiver closes when either it's window or hostWindow closes, otherwise NO.
*/
- (BOOL)shouldCloseWithWindow;

/*!
    @method setUIDelegate:
    @abstract Set the WebView's WebUIDelegate.
    @param delegate The WebUIDelegate to set as the delegate.
*/    
- (void)setUIDelegate:(id)delegate;

/*!
    @method UIDelegate
    @abstract Return the WebView's WebUIDelegate.
    @result The WebView's WebUIDelegate.
*/
- (id)UIDelegate;

/*!
    @method setResourceLoadDelegate:
    @abstract Set the WebView's WebResourceLoadDelegate load delegate.
    @param delegate The WebResourceLoadDelegate to set as the load delegate.
*/
- (void)setResourceLoadDelegate:(id)delegate;

/*!
    @method resourceLoadDelegate
    @result Return the WebView's WebResourceLoadDelegate.
*/    
- (id)resourceLoadDelegate;

/*!
    @method setDownloadDelegate:
    @abstract Set the WebView's WebDownloadDelegate.
    @discussion The download delegate is retained by WebDownload when any downloads are in progress.
    @param delegate The WebDownloadDelegate to set as the download delegate.
*/    
- (void)setDownloadDelegate:(id)delegate;

/*!
    @method downloadDelegate
    @abstract Return the WebView's WebDownloadDelegate.
    @result The WebView's WebDownloadDelegate.
*/    
- (id)downloadDelegate;

/*!
    @method setFrameLoadDelegate:
    @abstract Set the WebView's WebFrameLoadDelegate delegate.
    @param delegate The WebFrameLoadDelegate to set as the delegate.
*/    
- (void)setFrameLoadDelegate:(id)delegate;

/*!
    @method frameLoadDelegate
    @abstract Return the WebView's WebFrameLoadDelegate delegate.
    @result The WebView's WebFrameLoadDelegate delegate.
*/    
- (id)frameLoadDelegate;

/*!
    @method setPolicyDelegate:
    @abstract Set the WebView's WebPolicyDelegate delegate.