+ Typical usage: +
++ WebView *webView; + WebFrame *mainFrame; + + webView = [[WebView alloc] initWithFrame: NSMakeRect (0,0,640,480)]; + mainFrame = [webView mainFrame]; + [mainFrame loadRequest:request]; ++ + 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 +*/ +[ + object, + oleautomation, + hidden, + uuid(174BBEFD-058E-49c7-91DF-6F110AA4AC28), + pointer_default(unique) +] +interface IWebView : IUnknown +{ + /*! + @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; + */ + HRESULT canShowMIMEType([in] BSTR mimeType, [out, retval] BOOL* canShow); + + /*! + @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; + */ + HRESULT canShowMIMETypeAsHTML([in] BSTR mimeType, [out, retval] BOOL* canShow); + + /*! + @method MIMETypesShownAsHTML + @result Returns an array of NSStrings that describe the MIME types + WebKit will attempt to render as HTML. + + (NSArray *)MIMETypesShownAsHTML; + */ + HRESULT MIMETypesShownAsHTML([out, retval] IEnumVARIANT** enumVariant); + + /*! + @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; + */ + HRESULT setMIMETypesShownAsHTML([in, size_is(cMimeTypes)] BSTR* mimeTypes, [in] int cMimeTypes); + + /*! + @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; + */ + HRESULT URLFromPasteboard([in] IDataObject* pasteboard, [out, retval] BSTR* url); + + /*! + @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; + */ + HRESULT URLTitleFromPasteboard([in] IDataObject* pasteboard, [out, retval] BSTR* urlTitle); + + /*! + @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; + */ + HRESULT initWithFrame([in] RECT frame, [in] BSTR frameName, [in] BSTR groupName); + + /*! + @method setUIDelegate: + @abstract Set the WebView's WebUIDelegate. + @param delegate The WebUIDelegate to set as the delegate. + - (void)setUIDelegate:(id)delegate; + */ + HRESULT setUIDelegate([in] IWebUIDelegate* d); + + /*! + @method UIDelegate + @abstract Return the WebView's WebUIDelegate. + @result The WebView's WebUIDelegate. + - (id)UIDelegate; + */ + HRESULT uiDelegate([retval, out] IWebUIDelegate** d); + + /*! + @method setResourceLoadDelegate: + @abstract Set the WebView's WebResourceLoadDelegate load delegate. + @param delegate The WebResourceLoadDelegate to set as the load delegate. + - (void)setResourceLoadDelegate:(id)delegate; + */ + HRESULT setResourceLoadDelegate([in] IWebResourceLoadDelegate* d); + + /*! + @method resourceLoadDelegate + @result Return the WebView's WebResourceLoadDelegate. + - (id)resourceLoadDelegate; + */ + HRESULT resourceLoadDelegate([retval, out] IWebResourceLoadDelegate** d); + + /*! + @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; + */ + HRESULT setDownloadDelegate([in] IWebDownloadDelegate* d); + + /*! + @method downloadDelegate + @abstract Return the WebView's WebDownloadDelegate. + @result The WebView's WebDownloadDelegate. + - (id)downloadDelegate; + */ + HRESULT downloadDelegate([retval, out] IWebDownloadDelegate** d); + + /*! + @method setFrameLoadDelegate: + @abstract Set the WebView's WebFrameLoadDelegate delegate. + @param delegate The WebFrameLoadDelegate to set as the delegate. + - (void)setFrameLoadDelegate:(id)delegate; + */ + HRESULT setFrameLoadDelegate([in] IWebFrameLoadDelegate* d); + + /*! + @method frameLoadDelegate + @abstract Return the WebView's WebFrameLoadDelegate delegate. + @result The WebView's WebFrameLoadDelegate delegate. + - (id)frameLoadDelegate; + */ + HRESULT frameLoadDelegate([retval, out] IWebFrameLoadDelegate** d); + + /*! + @method setPolicyDelegate: + @abstract Set the WebView's WebPolicyDelegate delegate. + @param delegate The WebPolicyDelegate to set as the delegate. + - (void)setPolicyDelegate:(id)delegate; + */ + HRESULT setPolicyDelegate([in] IWebPolicyDelegate* d); + + /*! + @method policyDelegate + @abstract Return the WebView's WebPolicyDelegate. + @result The WebView's WebPolicyDelegate. + - (id)policyDelegate; + */ + HRESULT policyDelegate([retval, out] IWebPolicyDelegate** d); + + /*! + @method mainFrame + @abstract Return the top level frame. + @discussion Note that even document that are not framesets will have a + mainFrame. + @result The main frame. + - (WebFrame *)mainFrame; + */ + HRESULT mainFrame([retval, out] IWebFrame** frame); + + /*! + @method focusedFrame + @abstract Return the frame that has the current focus. + */ + HRESULT focusedFrame([retval, out] IWebFrame** frame); + + /*! + @method backForwardList + @result The backforward list for this webView. + - (WebBackForwardList *)backForwardList; + */ + HRESULT backForwardList([retval, out] IWebBackForwardList** list); + + /*! + @method setMaintainsBackForwardList: + @abstract Enable or disable the use of a backforward list for this webView. + @param flag Turns use of the back forward list on or off + - (void)setMaintainsBackForwardList:(BOOL)flag; + */ + HRESULT setMaintainsBackForwardList([in] BOOL flag); + + /*! + @method goBack + @abstract Go back to the previous URL in the backforward list. + @result YES if able to go back in the backforward list, NO otherwise. + - (BOOL)goBack; + */ + HRESULT goBack([out, retval] BOOL* succeeded); + + /*! + @method goForward + @abstract Go forward to the next URL in the backforward list. + @result YES if able to go forward in the backforward list, NO otherwise. + - (BOOL)goForward; + */ + HRESULT goForward([out, retval] BOOL* succeeded); + + /*! + @method goToBackForwardItem: + @abstract Go back or forward to an item in the backforward list. + @result YES if able to go to the item, NO otherwise. + - (BOOL)goToBackForwardItem:(WebHistoryItem *)item; + */ + HRESULT goToBackForwardItem([in] IWebHistoryItem* item, [out, retval] BOOL* succeeded); + + /*! + @method setTextSizeMultiplier: + @abstract Change the size of the text rendering in views managed by this webView. + @param multiplier A fractional percentage value, 1.0 is 100%. + - (void)setTextSizeMultiplier:(float)multiplier; + */ + HRESULT setTextSizeMultiplier([in] float multiplier); + + /*! + @method textSizeMultiplier + @result The text size multipler. + - (float)textSizeMultiplier; + */ + HRESULT textSizeMultiplier([out, retval] float* multiplier); + + /*! + @method setApplicationNameForUserAgent: + @abstract Set the application name. + @discussion This name will be used in user-agent strings + that are chosen for best results in rendering web pages. + @param applicationName The application name + - (void)setApplicationNameForUserAgent:(NSString *)applicationName; + */ + HRESULT setApplicationNameForUserAgent([in] BSTR applicationName); + + /*! + @method applicationNameForUserAgent + @result The name of the application as used in the user-agent string. + - (NSString *)applicationNameForUserAgent; + */ + HRESULT applicationNameForUserAgent([out, retval] BSTR* applicationName); + + /*! + @method setCustomUserAgent: + @abstract Set the user agent. + @discussion Setting this means that the webView should use this user-agent string + instead of constructing a user-agent string for each URL. Setting it to nil + causes the webView to construct the user-agent string for each URL + for best results rendering web pages. + @param userAgentString The user agent description + - (void)setCustomUserAgent:(NSString *)userAgentString; + */ + HRESULT setCustomUserAgent([in] BSTR userAgentString); + + /*! + @method customUserAgent + @result The custom user-agent string or nil if no custom user-agent string has been set. + - (NSString *)customUserAgent; + */ + HRESULT customUserAgent([out, retval] BSTR* userAgentString); + + /*! + @method userAgentForURL: + @abstract Get the appropriate user-agent string for a particular URL. + @param URL The URL. + @result The user-agent string for the supplied URL. + - (NSString *)userAgentForURL:(NSURL *)URL; + */ + HRESULT userAgentForURL([in] BSTR url, [out, retval] BSTR* userAgent); + + /*! + @method supportsTextEncoding + @abstract Find out if the current web page supports text encodings. + @result YES if the document view of the current web page can + support different text encodings. + - (BOOL)supportsTextEncoding; + */ + HRESULT supportsTextEncoding([out, retval] BOOL* supports); + + /*! + @method setCustomTextEncodingName: + @discussion Make the page display with a different text encoding; stops any load in progress. + The text encoding passed in overrides the normal text encoding smarts including + what's specified in a web page's header or HTTP response. + The text encoding automatically goes back to the default when the top level frame + changes to a new location. + Setting the text encoding name to nil makes the webView use default encoding rules. + @param encoding The text encoding name to use to display a page or nil. + - (void)setCustomTextEncodingName:(NSString *)encodingName; + */ + HRESULT setCustomTextEncodingName([in] BSTR encodingName); + + /*! + @method customTextEncodingName + @result The custom text encoding name or nil if no custom text encoding name has been set. + - (NSString *)customTextEncodingName; + */ + HRESULT customTextEncodingName([out, retval] BSTR* encodingName); + + /*! + @method setMediaStyle: + @discussion Set the media style for the WebView. The mediaStyle will override the normal value + of the CSS media property. Setting the value to nil will restore the normal value. + @param mediaStyle The value to use for the CSS media property. + - (void)setMediaStyle:(NSString *)mediaStyle; + */ + HRESULT setMediaStyle([in] BSTR media); + + /*! + @method mediaStyle + @result mediaStyle The value to use for the CSS media property, as set by setMediaStyle:. It + will be nil unless set by that method. + - (NSString *)mediaStyle; + */ + HRESULT mediaStyle([out, retval] BSTR* media); + + /*! + @method stringByEvaluatingJavaScriptFromString: + @param script The text of the JavaScript. + @result The result of the script, converted to a string, or nil for failure. + - (NSString *)stringByEvaluatingJavaScriptFromString:(NSString *)script; + */ + HRESULT stringByEvaluatingJavaScriptFromString([in] BSTR script, [out, retval] BSTR* result); + + /*! + @method windowScriptObject + @discussion windowScriptObject return a WebScriptObject that represents the + window object from the script environment. + @result Returns the window object from the script environment. + - (WebScriptObject *)windowScriptObject; + */ + HRESULT windowScriptObject([out, retval] IWebScriptObject** webScriptObject); + + /*! + @method setPreferences: + @param preferences The preferences to use for the webView. + @abstract Override the standard setting for the webView. + - (void)setPreferences: (WebPreferences *)prefs; + */ + HRESULT setPreferences([in] IWebPreferences* prefs); + + /*! + @method preferences + @result Returns the preferences used by this webView. + @discussion This method will return [WebPreferences standardPreferences] if no + other instance of WebPreferences has been set. + - (WebPreferences *)preferences; + */ + HRESULT preferences([out, retval] IWebPreferences** prefs); + + /*! + @method setPreferencesIdentifier: + @param anIdentifier The string to use a prefix for storing values for this WebView in the user + defaults database. + @discussion If the WebPreferences for this WebView are stored in the user defaults database, the + string set in this method will be used a key prefix. + - (void)setPreferencesIdentifier:(NSString *)anIdentifier; + */ + HRESULT setPreferencesIdentifier([in] BSTR anIdentifier); + + /*! + @method preferencesIdentifier + @result Returns the WebPreferences key prefix. + - (NSString *)preferencesIdentifier; + */ + HRESULT preferencesIdentifier([out, retval] BSTR* anIdentifier); + + /*! + @method setHostWindow: + @param hostWindow The host window for the web view. + @discussion Parts of WebKit (such as plug-ins and JavaScript) depend on a window to function + properly. Set a host window so these parts continue to function even when the web view is + not in an actual window. + - (void)setHostWindow:(NSWindow *)hostWindow; + */ + HRESULT setHostWindow([in] OLE_HANDLE window); + + /*! + @method hostWindow + @result The host window for the web view. + - (NSWindow *)hostWindow; + */ + HRESULT hostWindow([out, retval] OLE_HANDLE* window); + + /*! + @method searchFor:direction:caseSensitive: + @abstract Searches a document view for a string and highlights the string if it is found. + Starts the search from the current selection. Will search across all frames. + @param string The string to search for. + @param forward YES to search forward, NO to seach backwards. + @param caseFlag YES to for case-sensitive search, NO for case-insensitive search. + @result YES if found, NO if not found. + - (BOOL)searchFor:(NSString *)string direction:(BOOL)forward caseSensitive:(BOOL)caseFlag wrap:(BOOL)wrapFlag; + */ + HRESULT searchFor([in] BSTR str, [in] BOOL forward, [in] BOOL caseFlag, [in] BOOL wrapFlag, [out, retval] BOOL* found); + + /*! + @method registerViewClass:representationClass:forMIMEType: + @discussion Register classes that implement WebDocumentView and WebDocumentRepresentation respectively. + A document class may register for a primary MIME type by excluding + a subtype, i.e. "video/" will match the document class with + all video types. More specific matching takes precedence + over general matching. + @param viewClass The WebDocumentView class to use to render data for a given MIME type. + @param representationClass The WebDocumentRepresentation class to use to represent data of the given MIME type. + @param MIMEType The MIME type to represent with an object of the given class. + + (void)registerViewClass:(Class)viewClass representationClass:(Class)representationClass forMIMEType:(NSString *)MIMEType; + */ + HRESULT registerViewClass([in] IWebDocumentView* view, [in] IWebDocumentRepresentation* representation, [in] BSTR forMIMEType); + + /*! + @method setGroupName: + @param groupName The name of the group for this WebView. + @discussion JavaScript may access named frames within the same group. + - (void)setGroupName:(NSString *)groupName; + */ + HRESULT setGroupName([in] BSTR groupName); + + /*! + @method groupName + @discussion The group name for this WebView. + - (NSString *)groupName; + */ + HRESULT groupName([out, retval] BSTR* groupName); + + /*! + @method estimatedProgress + @discussion An estimate of the percent complete for a document load. This + value will range from 0 to 1.0 and, once a load completes, will remain at 1.0 + until a new load starts, at which point it will be reset to 0. The value is an + estimate based on the total number of bytes expected to be received + for a document, including all it's possible subresources. For more accurate progress + indication it is recommended that you implement a WebFrameLoadDelegate and a + WebResourceLoadDelegate. + - (double)estimatedProgress; + */ + HRESULT estimatedProgress([out, retval] double* estimatedProgress); + + /*! + @method isLoading + @discussion Returns YES if there are any pending loads. + - (BOOL)isLoading; + */ + HRESULT isLoading([out, retval] BOOL* isLoading); + + /*! + @method elementAtPoint: + @param point A point in the coordinates of the WebView + @result An element dictionary describing the point + - (NSDictionary *)elementAtPoint:(NSPoint)point; + */ + HRESULT elementAtPoint([in] LPPOINT point, [out, retval] IPropertyBag** elementDictionary); + + /*! + @method pasteboardTypesForSelection + @abstract Returns the pasteboard types that WebView can use for the current selection + - (NSArray *)pasteboardTypesForSelection; + */ + HRESULT pasteboardTypesForSelection([out, retval] IEnumVARIANT** enumVariant); + + /*! + @method writeSelectionWithPasteboardTypes:toPasteboard: + @abstract Writes the current selection to the pasteboard + @param types The types that WebView will write to the pasteboard + @param pasteboard The pasteboard to write to + - (void)writeSelectionWithPasteboardTypes:(NSArray *)types toPasteboard:(NSPasteboard *)pasteboard; + */ + HRESULT writeSelectionWithPasteboardTypes([in, size_is(cTypes)] BSTR* types, [in] int cTypes, [in] IDataObject* pasteboard); + + /*! + @method pasteboardTypesForElement: + @abstract Returns the pasteboard types that WebView can use for an element + @param element The element + - (NSArray *)pasteboardTypesForElement:(NSDictionary *)element; + */ + HRESULT pasteboardTypesForElement([in] IPropertyBag* elementDictionary, [out, retval] IEnumVARIANT** enumVariant); + + /*! + @method writeElement:withPasteboardTypes:toPasteboard: + @abstract Writes an element to the pasteboard + @param element The element to write to the pasteboard + @param types The types that WebView will write to the pasteboard + @param pasteboard The pasteboard to write to + - (void)writeElement:(NSDictionary *)element withPasteboardTypes:(NSArray *)types toPasteboard:(NSPasteboard *)pasteboard; + */ + HRESULT writeElement([in] IPropertyBag* elementDictionary, [in, size_is(cWithPasteboardTypes)] BSTR* withPasteboardTypes, [in] int cWithPasteboardTypes, [in] IDataObject* pasteboard); + + /*! + @method selectedText + @abstract Returns the selection as a string + */ + HRESULT selectedText([out, retval] BSTR* text); + + /*! + @method centerSelectionInVisibleArea + @abstract Centers the selected text in the WebView + - (void)centerSelectionInVisibleArea:(id)sender; + */ + HRESULT centerSelectionInVisibleArea([in] IUnknown* sender); + + /*! + @method moveDragCaretToPoint: + @param point A point in the coordinates of the WebView + @discussion This method moves the caret that shows where something being dragged will be dropped. It may cause the WebView to scroll + to make the new position of the drag caret visible. + - (void)moveDragCaretToPoint:(NSPoint)point; + */ + HRESULT moveDragCaretToPoint([in] LPPOINT point); + + /*! + @method removeDragCaret + @abstract Removes the drag caret from the WebView + - (void)removeDragCaret; + */ + HRESULT removeDragCaret(); + + /*! + @method setDrawsBackground: + @param drawsBackround YES to cause the receiver to draw a default white background, NO otherwise. + @abstract Sets whether the receiver draws a default white background when the loaded page has no background specified. + - (void)setDrawsBackground:(BOOL)drawsBackround; + */ + HRESULT setDrawsBackground([in] BOOL drawsBackground); + + /*! + @method drawsBackground + @result Returns YES if the receiver draws a default white background, NO otherwise. + - (BOOL)drawsBackground; + */ + HRESULT drawsBackground([out, retval] BOOL* drawsBackground); + + /*! + @method setMainFrameURL: + @param URLString The URL to load in the mainFrame. + - (void)setMainFrameURL:(NSString *)URLString; + */ + HRESULT setMainFrameURL([in] BSTR urlString); + + /*! + @method mainFrameURL + @result Returns the main frame's current URL. + - (NSString *)mainFrameURL; + */ + HRESULT mainFrameURL([out, retval] BSTR* urlString); + + /*! + @method mainFrameDocument + @result Returns the main frame's DOMDocument. + - (DOMDocument *)mainFrameDocument; + */ + HRESULT mainFrameDocument([out, retval] IDOMDocument** document); + + /*! + @method mainFrameTitle + @result Returns the main frame's title if any, otherwise an empty string. + - (NSString *)mainFrameTitle; + */ + HRESULT mainFrameTitle([out, retval] BSTR* title); + + /*! + @method mainFrameIcon + @discussion The methods returns the site icon for the current page loaded in the mainFrame. + @result Returns the main frame's icon if any, otherwise nil. + - (NSImage *)mainFrameIcon; + */ + HRESULT mainFrameIcon([out, retval] OLE_HANDLE* hBitmap); +} + +/* + @interface WebView (WebIBActions)