webuidelegate.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>
#import <Foundation/NSURLRequest.h>
#import <JavaScriptCore/WebKitAvailability.h>

#if MAC_OS_X_VERSION_MAX_ALLOWED <= MAC_OS_X_VERSION_10_4
#define WebNSUInteger unsigned int
#else
#define WebNSUInteger NSUInteger
#endif

/*!
    @enum WebMenuItemTag
    @discussion Each menu item in the default menu items array passed in
    contextMenuItemsForElement:defaultMenuItems: has its tag set to one of the WebMenuItemTags.
    When iterating through the default menu items array, use the tag to differentiate between them.
*/

enum {
    WebMenuItemTagOpenLinkInNewWindow=1,
    WebMenuItemTagDownloadLinkToDisk,
    WebMenuItemTagCopyLinkToClipboard,
    WebMenuItemTagOpenImageInNewWindow,
    WebMenuItemTagDownloadImageToDisk,
    WebMenuItemTagCopyImageToClipboard,
    WebMenuItemTagOpenFrameInNewWindow,
    WebMenuItemTagCopy,
    WebMenuItemTagGoBack,
    WebMenuItemTagGoForward,
    WebMenuItemTagStop,
    WebMenuItemTagReload,
    WebMenuItemTagCut,
    WebMenuItemTagPaste,
    WebMenuItemTagSpellingGuess,
    WebMenuItemTagNoGuessesFound,
    WebMenuItemTagIgnoreSpelling,
    WebMenuItemTagLearnSpelling,
    WebMenuItemTagOther,
    WebMenuItemTagSearchInSpotlight,
    WebMenuItemTagSearchWeb,
    WebMenuItemTagLookUpInDictionary,
    WebMenuItemTagOpenWithDefaultApplication,
    WebMenuItemPDFActualSize,
    WebMenuItemPDFZoomIn,
    WebMenuItemPDFZoomOut,
    WebMenuItemPDFAutoSize,
    WebMenuItemPDFSinglePage,
    WebMenuItemPDFFacingPages,
    WebMenuItemPDFContinuous,
    WebMenuItemPDFNextPage,
    WebMenuItemPDFPreviousPage,
};

/*!
    @enum WebDragDestinationAction
    @abstract Actions that the destination of a drag can perform.
    @constant WebDragDestinationActionNone No action
    @constant WebDragDestinationActionDHTML Allows DHTML (such as JavaScript) to handle the drag
    @constant WebDragDestinationActionEdit Allows editable documents to be edited from the drag
    @constant WebDragDestinationActionLoad Allows a location change from the drag
    @constant WebDragDestinationActionAny Allows any of the above to occur
*/
typedef enum {
    WebDragDestinationActionNone    = 0,
    WebDragDestinationActionDHTML   = 1,
    WebDragDestinationActionEdit    = 2,
    WebDragDestinationActionLoad    = 4,
    WebDragDestinationActionAny     = UINT_MAX
} WebDragDestinationAction;

/*!
    @enum WebDragSourceAction
    @abstract Actions that the source of a drag can perform.
    @constant WebDragSourceActionNone No action
    @constant WebDragSourceActionDHTML Allows DHTML (such as JavaScript) to start a drag
    @constant WebDragSourceActionImage Allows an image drag to occur
    @constant WebDragSourceActionLink Allows a link drag to occur
    @constant WebDragSourceActionSelection Allows a selection drag to occur
    @constant WebDragSourceActionAny Allows any of the above to occur
*/
typedef enum {
    WebDragSourceActionNone         = 0,
    WebDragSourceActionDHTML        = 1,
    WebDragSourceActionImage        = 2,
    WebDragSourceActionLink         = 4,
    WebDragSourceActionSelection    = 8,
    WebDragSourceActionAny          = UINT_MAX
} WebDragSourceAction;

/*!
    @protocol WebOpenPanelResultListener
    @discussion This protocol is used to call back with the results of
    the file open panel requested by runOpenPanelForFileButtonWithResultListener:
*/
@protocol WebOpenPanelResultListener <NSObject>

/*!
    @method chooseFilename:
    @abstract Call this method to return a filename from the file open panel.
    @param fileName
*/
- (void)chooseFilename:(NSString *)fileName;

/*!
    @method chooseFilenames:
    @abstract Call this method to return an array of filenames from the file open panel.
    @param fileNames
*/
- (void)chooseFilenames:(NSArray *)fileNames WEBKIT_OBJC_METHOD_ANNOTATION(AVAILABLE_IN_WEBKIT_VERSION_4_0);

/*!
    @method cancel
    @abstract Call this method to indicate that the file open panel was cancelled.
*/
- (void)cancel;

@end

@class WebView;

/*!
    @category WebUIDelegate
    @discussion A class that implements WebUIDelegate provides
    window-related methods that may be used by Javascript, plugins and
    other aspects of web pages. These methods are used to open new
    windows and control aspects of existing windows.
*/
@interface NSObject (WebUIDelegate)

/*!
    @method webView:createWebViewWithRequest:
    @abstract Create a new window and begin to load the specified request.
    @discussion The newly created window is hidden, and the window operations delegate on the
    new WebViews will get a webViewShow: call.
    @param sender The WebView sending the delegate method.
    @param request The request to load.
    @result The WebView for the new window.
*/
- (WebView *)webView:(WebView *)sender createWebViewWithRequest:(NSURLRequest *)request;

/*!
    @method webViewShow:
    @param sender The WebView sending the delegate method.
    @abstract Show the window that contains the top level view of the WebView,
    ordering it frontmost.
    @discussion This will only be called just after createWindowWithRequest:
    is used to create a new window.
*/
- (void)webViewShow:(WebView *)sender;

/*!
    @method webView:createWebViewModalDialogWithRequest:
    @abstract Create a new window and begin to load the specified request.
    @discussion The newly created window is hidden, and the window operations delegate on the
    new WebViews will get a webViewShow: call.
    @param sender The WebView sending the delegate method.
    @param request The request to load.
    @result The WebView for the new window.
*/
- (WebView *)webView:(WebView *)sender createWebViewModalDialogWithRequest:(NSURLRequest *)request;

/*!
    @method webViewRunModal:
    @param sender The WebView sending the delegate method.
    @abstract Show the window that contains the top level view of the WebView,
    ordering it frontmost. The window should be run modal in the application.
    @discussion This will only be called just after createWebViewModalDialogWithRequest:
    is used to create a new window.
*/
- (void)webViewRunModal:(WebView *)sender;

/*!
    @method webViewClose:
    @abstract Close the current window. 
    @param sender The WebView sending the delegate method.
    @discussion Clients showing multiple views in one window may
    choose to close only the one corresponding to this
    WebView. Other clients may choose to ignore this method
    entirely.
*/
- (void)webViewClose:(WebView *)sender;

/*!
    @method webViewFocus:
    @abstract Focus the current window (i.e. makeKeyAndOrderFront:).
    @param The WebView sending the delegate method.
    @discussion Clients showing multiple views in one window may want to
    also do something to focus the one corresponding to this WebView.
*/
- (void)webViewFocus:(WebView *)sender;

/*!
    @method webViewUnfocus:
    @abstract Unfocus the current window.
    @param sender The WebView sending the delegate method.
    @discussion Clients showing multiple views in one window may want to
    also do something to unfocus the one corresponding to this WebView.
*/
- (void)webViewUnfocus:(WebView *)sender;

/*!
    @method webViewFirstResponder:
    @abstract Get the first responder for this window.
    @param sender The WebView sending the delegate method.
    @discussion This method should return the focused control in the
    WebView's view, if any. If the view is out of the window
    hierarchy, this might return something than calling firstResponder
    on the real NSWindow would. It's OK to return either nil or the
    real first responder if some control not in the window has focus.
*/
- (NSResponder *)webViewFirstResponder:(WebView *)sender;

/*!
    @method webView:makeFirstResponder:
    @abstract Set the first responder for this window.
    @param sender The WebView sending the delegate method.
    @param responder The responder to make first (will always be a view)
    @discussion responder will always be a view that is in the view
    subhierarchy of the top-level web view for this WebView. If the
    WebView's top level view is currently out of the view
    hierarchy, it may be desirable to save the first responder
    elsewhere, or possibly ignore this call.
*/
- (void)webView:(WebView *)sender makeFirstResponder:(NSResponder *)responder;

/*!
    @method webView:setStatusText:
    @abstract Set the window's status display, if any, to the specified string.
    @param sender The WebView sending the delegate method.
    @param text The status text to set
*/
- (void)webView:(WebView *)sender setStatusText:(NSString *)text;

/*!
    @method webViewStatusText:
    @abstract Get the currently displayed status text.
    @param sender The WebView sending the delegate method.
    @result The status text
*/
- (NSString *)webViewStatusText:(WebView *)sender;

/*!
    @method webViewAreToolbarsVisible:
    @abstract Determine whether the window's toolbars are currently visible
    @param sender The WebView sending the delegate method.
    @discussion This method should return YES if the window has any
    toolbars that are currently on, besides the status bar. If the app
    has more than one toolbar per window, for example a regular
    command toolbar and a favorites bar, it should return YES from
    this method if at least one is on.
    @result YES if at least one toolbar is visible, otherwise NO.
*/
- (BOOL)webViewAreToolbarsVisible:(WebView *)sender;

/*!
    @method webView:setToolbarsVisible:
    @param sender The WebView sending the delegate method.
    @abstract Set whether the window's toolbars are currently visible.
    @param visible New value for toolbar visibility
    @discussion Setting this to YES should turn on all toolbars
    (except for a possible status bar). Setting it to NO should turn