[SCM] WebKit Debian packaging branch, debian/unstable, updated. debian/1.1.15-1-40151-g37bb677
rjw
rjw at 268f45cc-cd09-0410-ab3c-d52691b4dbfc
Sat Sep 26 05:53:09 UTC 2009
The following commit has been merged in the debian/unstable branch:
commit e801e239d715b0e8d2cd505ed5e1a322b646d085
Author: rjw <rjw at 268f45cc-cd09-0410-ab3c-d52691b4dbfc>
Date: Wed Dec 12 03:20:27 2001 +0000
More changes to the WebView API.
git-svn-id: http://svn.webkit.org/repository/webkit/trunk@494 268f45cc-cd09-0410-ab3c-d52691b4dbfc
diff --git a/WebKit/WebView.subproj/IFWebController.h b/WebKit/WebView.subproj/IFWebController.h
index 9525f73..e2196d9 100644
--- a/WebKit/WebView.subproj/IFWebController.h
+++ b/WebKit/WebView.subproj/IFWebController.h
@@ -6,27 +6,108 @@
*/
#import <Cocoa/Cocoa.h>
- at interface WKWebController : NSObject <WKLoadHandler, WKScriptContextHandler, WKFrameSetHandler, WKCredentialsHandler, WKLocationChangeHandler, WKContextMenuHandler>
+#ifdef READY_FOR_PRIMETIME
+
+/*
+ WKWebController manages the interaction between WKWebView and WKWebDataSource.
+ Intances of WKWebController retain their view and data source.
+
+ [As in the appkit classes NSWindow and NSWindowController, it will be necessary
+ to have non-retained back pointers from WKWebView and WKWebDataSource to their
+ controller. Not retaining the controller will prevent cycles. Of course, not
+ retaining is bad, as it can lead to dangling references. We could invert the reference
+ graph and add ...inView: and ...inDataSource: to the API, but that's ugly. If it's
+ good enough for the appkit, it's good enough for us. Ugh.]
+
+ .--(p)WKWebController --.
+ | . . |
+ | . . |
+ \|/ . . \|/
+ (p)WKWebViewDelegate <-- (c)WKWebView (c)WKWebDataSource --> (p)WKWebDataSourceDelegate
+
+ (c) indicates a class, (p) indicates a protocol. The solid lines indicate an
+ retain reference. The dotted lines indicate a non-retained reference.
+
+ The WKWebController implements required behavior. WKWebView and WKWebDataSource
+ cannot function without a controller.
+
+ Delegates implement optional behavior. WKWebView doesn't require a WKWebViewDelegate,
+ nor does WKWebDataSource require a WKWebDataSourceDelegate.
+
+ It it expected that alternate implementations of WKWebController will be written for
+ alternate views of the web page described by WKWebDataSource. For example, a
+ view that draws the DOM tree would require both a subclass of NSView and an
+ implementation of WKWebController. It is also possible that a web crawler
+ may implement a WKWebController with no corresponding view.
+
+ WKConcreteWebController may be subclassed to modify the behavior of the standard
+ WKWebView and WKWebDataSource.
+*/
+
+
+/*
+ WKWebController implements all the behavior that ties together WKWebView
+ and WKWebDataSource. See each inherited protocol for a more complete
+ description.
+
+ [Don and I both agree that all these little protocols are useful to cleanly
+ describe snippets of behavior, but do we explicity reference them anywhere,
+ or do we just use the umbrella protocol?]
+*/
+ at protocol WKWebController <WKLoadHandler, WKScriptContextHandler, WKFrameSetHandler, WKCredentialsHandler, WKLocationChangeHandler>
+
+- (void)setDataSource: (WKWebDataSource *)dataSource;
+- (WKWebDataSource *)dataSource
+
+- (void)setView: (WKWebView *)view;
+- (WKWebView *)view;
+
+ at end
+
+
+/*
+ WKWebViewDelegates implement protocols that modify the behavior of
+ WKWebViews. A WKWebView does not require a delegate.
+*/
+ at protocol WKWebViewDelegate <WKContextMenuHandler>
@end
+
+/*
+ WKWebDataSourceDelegate implement protocols that modify the behavior of
+ WKWebDataSources. A WKWebDataSources does not require a delegate.
+*/
+ at protocol WKWebDataSourceDelegate <?>
+ at end
+
+
+// Is WKConcreteWebController the right name? The name fits with the
+// scheme used by Foundation, although Foundation's concrete classes
+// typically aren't public.
+ at interface WKConcreteWebController : NSObject <WKWebController>
+- initWithView: (WKWebView *) dataSource: (WKWebDataSource *)dataSource;
+ at end
+
+
// See the comments in WKWebPageView above for more description about this protocol.
@protocol WKLocationChangeHandler
-- (BOOL)locationWillChange;
+
+- (void)loadingStarted;
- (void)loadingCancelled;
- (void)loadingStopped;
- (void)loadingFinished;
-- (void)loadingStarted;
+
+- (void)loadedPageTitle: (NSString *)title;
+
@end
@protocol WKContextMenuHandler
-/*
- We decided to implement this in terms of a fixed set of types rather
- than per node.
-
- What items should be supported in the default context menus?
-*/
+// Returns the array of menu items for this node that will be displayed in the context menu.
+// Typically this would be implemented by returning the results of WKWebView defaultContextMenuItemsForNode:
+// after making any desired changes or additions.
+- (NSArray *)contextMenuItemsForNode: (WKDOMNode *);
@end
/*
@@ -56,7 +137,9 @@
typically for non-base URLs this should be done after a URL (i.e. image)
has been completely downloaded.
*/
-- (void)receivedDataForLocation: (WKLoadProgress *)progress;
+- (void)receivedProgress: (WKLoadProgress *)progress forLocation: (NSString *)lcoation;
+
+- (void)timeoutForLocation: (NSString *)location partialProgress: (WKLoadProgress *)progress;
@end
@@ -69,13 +152,32 @@
@interface WKLoadProgress
{
int bytesSoFar; // 0 if this is the start of load
- int totalLoaded; // -1 if this is not known.
+ int totalToLoad; // -1 if this is not known.
// bytesSoFar == totalLoaded when complete
- NSString *location; // Needs to be a string, not URL.
- LOAD_TYPES type; // load types, either image, css, jscript, or html
+ WK_LOAD_TYPES type; // load types, either image, css, jscript, or html
+}
+ at end
+
+/*
+ Error handling:
+ error conditions:
+ timeout
+ unrecognized/handled mime-type
+ javascript errors
+ invalid url
+ parsing errors
+
+*/
+ at interface WKError
+{
+ NSString *description;
+ int code;
}
@end
+ at protocol WKWebDataSourceErrorHandler
+- error: (WKError *)error;
+ at end
/*
@@ -85,6 +187,7 @@
*/
@protocol WKScriptContextHandler
+// setStatusText and statusText are used by Javascript's status bar text methods.
- (void)setStatusText: (NSString *)text;
- (NSString *)statusText;
@@ -99,11 +202,10 @@
*/
@protocol WKFrameSetHandler
- (NSArray *)frameNames;
-- (WKFrame *)findFrameNamed: (NSString *)name;
+- (id <WKFrame>) findFrameNamed: (NSString *)name;
- (BOOL)frameExists: (NSString *)name;
-- (BOOL)openURLInFrame: (WKFrame *)aFrame url: (NSURL *)url;
+- (void)openURL: (NSURL *)url inFrame: (id <WKFrame>) frame;
@end
- at protocol WKFrame
-//
- at end
+#endif
+
diff --git a/WebKit/WebView.subproj/IFWebDataSource.h b/WebKit/WebView.subproj/IFWebDataSource.h
index 42c6bff..6d3f53b 100644
--- a/WebKit/WebView.subproj/IFWebDataSource.h
+++ b/WebKit/WebView.subproj/IFWebDataSource.h
@@ -17,19 +17,9 @@
Typical usage of a WKWebDataSource.
WKWebDataSource *dataSource = [[WKWebDataSource alloc] initWithURL: url];
-
- [dataSource setFrameSetHandler: (WKFrameSetHandler *)myManager];
- [dataSource setScriptContextHandler: (WKScriptContextHandler *)myContext];
- [dataSource setLoadHandler: (WKLoadHandler *)myLoadHandler];
- [dataSource setCredentialsHandler: (WKCredentialsHandler *)myCredentialsHandler];
- ...
- or
- ...
- [dataSource setController: (WKWebController *)myController];
+ id <WKWebController>myController = [[MyControllerClass alloc] init];
+ [myController setDataSource: dataSource];
- Questions:
- Multiple protocols or controller?
- Should we use CF XML data types, or our own?
*/
#ifdef READY_FOR_PRIMETIME
@@ -41,40 +31,60 @@
}
-// Can these init methods return nil? e.g. if URL is invalid, or should they
-// throw exceptions?
-- initWithURL: (NSURL *)url;
+// Returns nil if object cannot be initialized due to a malformed URL (RFC 1808).
+- initWithURL: (NSURL *)inputUrl;
+
- initWithData: (NSData *)data;
- initWithString: (NSString *)string;
-// ?? How do you create subclasses of WKURILoader, how is this
-// expected to be used?
+// Ken, need some help with one.
- initWithLoader: (WKURILoader *)loader;
-// ?? We don't have a NS streams API!!
-- initWithStream: (NSStream *)stream
+
+// Set the controller for this data source. NOTE: The controller is not retained by the
+// data source.
+// Perhaps setController: should be private?
+- (void)setController: (id <WKWebController>)controller;
+- (id <WKWebController>)controller;
+
// May return nil if not initialized with a URL.
-- (NSURL *)url;
+- (NSURL *)inputURL;
+
+
+// The inputURL may resolve to a different URL as a result of
+// either a client side refresh <META HTTP-EQUIV="refresh" ...> or
+// a DNS redirect. Both of these implicit actions should not
+// require a new data source. The resolvedURL is the URL that is
+// ultimately used to fetch page data.
+// [We need more brain cells applied to this issue.]
+- (NSURL *)resolvedURL;
+
-// Start actually getting (if initialized with a URL) and parsing data.
-- (void)startLoading;
+// Start actually getting (if initialized with a URL) and parsing data. If the data source
+// is still performing a previous load it will be stopped.
+// If forceRefresh is YES the document will load from the net, not the cache.
+- (void)startLoading: (BOOL)forceRefresh;
+
+
+// Cancels any pending loads. A data source is conceptually only ever loading
+// one document at a time, although one document may have many related
+// resources. stopLoading will stop all loads related to the data source.
+// Returns NO if the data source is not currently loading.
+- (void)stopLoading;
+
+
+// Returns YES if there are any pending loads.
+- (BOOL)isLoading;
-// Cancel any pending loads.
-- (BOOL)stopLoading;
// Get DOM access to the document.
- (WKDOMDocument *)document;
+
// Get the actual source of the docment.
- (NSString *)documentText;
-// Get a 'pretty' version of the document, created by traversal of the DOM.
-- (NSString *)formattedDocumentText;
-
-// Get the currently focused node. Is this appropriate for the model, or
-// should this be handled by the view?
-- (WKDOMNode *)activeNode;
// URL reference point, these should probably not be public for 1.0.
- setBase: (NSURL *)url;
@@ -82,81 +92,33 @@
- setBaseTarget: (NSURL *)url;
- (NSURL *)baseTarget;
+
- (NSString *)encoding;
+
// Style sheet
- (void)setUserStyleSheet: (NSURL *)url;
- (void)setUserStyleSheet: (NSString *)sheet;
-// Searching, to support find in clients. regular expressions?
-- (WKSearchState *)findTextBegin;
-- (NSString *)findTextNext: (WKRegularExpression *)exp direction: (BOOL)forward state: (WKSearchState *)state;
-- (NSString *)findTextNext: (NSString *)string direction: (BOOL)forward caseSensitive: (BOOL)case state: (WKSearchState *)state;
-
-// Selection
-- (NSString *)selectedText;
-- (WKDOMRange *)selectedRange;
-- (void)setSelection: (WKDOMRange *range);
-- (BOOL)hasSelection;
-- (void)selectAll;
-
-#ifdef HAVE_WKCONTROLLER
-- (void)setController: (WKWebController *)controller;
-#else
-- (void)setLoadHandler: (WKLoadHandler *)fmanager;
-- (void)setFrameSetHandler: (WKFrameSetHandler *)fmanager;
-- (void)setScriptContextHandler: (WKScriptContextHandler *)context;
-#endif
-
-- executeScript: (NSString *)string;
-// Same as above except uses the node as 'this' value
-- executeScript: (NSString *)string withNode: (WKDOMNode *)node;
-// This API reflects the KDE API, but is it sufficient?
-- (BOOL)scheduleScript: (NSString *)string withNode: (WKDOMNode *)node
-- executeScheduledScript;
+// Searching, to support find in clients. regular expressions?
+- (WKSearchState *)beginSearch;
+- (NSString *)searchFor: (NSString *)string direction: (BOOL)forward caseSensitive: (BOOL)case state: (WKSearchState *)state;
// a.k.a shortcut icons, http://msdn.microsoft.com/workshop/Author/dhtml/howto/ShortcutIcon.asp.
-// This may be removed to a category to prevent unnecessary linkage to the AppKit. Note, however
-// that this means WebCore, specifically KWQ, also doesn't have dependencies on the AppKit.
+// This method may be moved to a category to prevent unnecessary linkage to the AppKit. Note, however
+// that WebCore also has dependencies on the appkit.
- (NSImage *)icon;
+
// Is page secure, e.g. https, ftps
-// Should this perhaps be on the URL?
-// This would the be implemented like this
-// return [[self url] isSecure];
- (BOOL)isPageSecure;
-// ---------------------- Convenience methods ----------------------
-- (NSString *)pageTitle;
-// ---------------------------------------------------------------
+// Returns nil or the page title.
+- (NSString *)pageTitle;
-/*
- Notifications?
- In general, how often should we notify? We should use notifications
- if we anticipate multiple clients, no return types, and generally
- asynchronous or indirect behaviour.
-
- notifications:
- WKSelectionChangedNotification
- WKNodeActivatedNotification
- WKDocumentChangedNotification
-
- Error handling:
- exceptions?
- nil returns?
- errors by notification?
-
- error conditions:
- timeout
- unrecognized/handled mime-type
- javascript errors
- invalid url
- parsing errors
-
-*/
@end
diff --git a/WebKit/WebView.subproj/IFWebView.h b/WebKit/WebView.subproj/IFWebView.h
index e15db15..1a113ad 100644
--- a/WebKit/WebView.subproj/IFWebView.h
+++ b/WebKit/WebView.subproj/IFWebView.h
@@ -14,70 +14,53 @@
Typical usage of a WKWebView.
NSURL *url = [NSURL URLWithString: @"http://www.apple.com"];
- ...
WKWebDataSource *dataSource = [[WKWebDataSource alloc] initWithURL: url];
WKWebView *view = [[WKWebView alloc] initWithFrame: myFrame];
- [view setDataSource: dataSource];
- [[view dataSource] startLoading];
- ...
- or
- ...
- WKWebDataSource *dataSource = [[WKWebDataSource alloc] initWithURL: url];
- WKWebView *view = [[WKWebView alloc] initWithFrame: myFrame DataSource: url];
- [[view dataSource] startLoading];
+ WKConcreteWebController *controller = [[WKConcreteWebController alloc] initWithView: view dataSource: dataSource];
+
+ [[[view controller] dataSource] startLoading];
+
...
+
or
+
...
+
WKWebView *view = [[WKWebView alloc] initWithFrame: myFrame url: url];
- [[view dataSource] startLoading];
+ [[[view controller] dataSource] startLoading];
+
- What is the behaviour of the view after it has been initialized and -startLoading is called?
+ What is the behaviour of the view after it has been initialized and
+ startLoading: is called?
- 1. When the data source is set (i.e. -setDataSource:) -locationWillChange will be sent
- to the view's controller. It may veto by returning NO. Note that if the convenience initializers
- are used no controller will have been set, and thus no chance to veto will be provided.
+ 1. No WKLocationChangedHandler messages will be sent until
+ startLoading: is called. After startLoading is called a loadingStarted
+ message will be sent to the controller. The view will remain unchanged
+ until the controller receives a receivedDataForLocation: message
+ from the data source.
+
+ If stopLoading is called before receipt of a receivedDataForLocation:, loading will
+ abort, the view will be unchanged, and the controller will receive a loadingCancelled
+ message.
- 2. The view will do nothing until receipt of its first -receivedDataForURL: message
- from its data source. Thus the view will not change its content before users have
- a chance to cancel slow URLs.
-
- During this time, if -stopLoading is called on the data source, loading will
- abort. If the loading is stopped the contents of the window will be unchanged.
- [This implies that the data source should revert to the previous data source.
- Will that be problematic?.] The controller will receive a -loadingCancelled message
- if the load is aborted during this period.
-
- Controllers should initiate progress indicators at this point (how?).
+ Controllers should initiate progress indicators upon receipt of loadingStarted,
+ and terminate when either a loadingCancelled or loadingStopped is received.
- 3. After receipt of it first -receivedDataForURL: it will clear its contents
- and perform its first layout. At this point a loadingStarted message will
- be sent to the client.
+ 2. After the controller receives it's first receivedDataForLocation: the contents of
+ the view will be cleared and layout may begin.
- 4. Upon every subsequent receipts of -finishedReceivingDataForURL: messages it
- will perform additional layouts. Note that these may be coalesced, depending
- on the interval the messages are received. During this time the load may
- be stopped. The layout may be incomplete if the load is stopped before all
- the referenced documents are loaded. If the layout is stopped during this
- period the controller will received a -loadingStopped message.
+ 3. Upon subsequent receipt of receivedDataForLocation: messages the controller
+ may trigger a document layout. Note that layouts may be coalesced. If stopLoading
+ is called before the document has fully loaded, the layout will be incomplete, and a
+ loadingStopped message will be sent to the controller
- 5. When -documentReceived is received the loading and initial layout is complete.
- Controllers should terminate progress indicators at this point. At this point
- controller will receive a -loadingFinished message.
-
- What is the behavior of the view when a link is clicked?
-
- See above. The behavior is exactly as above.
-
-
- ***
-
- The control behavior and view/model interdependencies of WK are manifested by several
- protocols (so far: WKLoadHandler, WKScriptContextHandler, WKFrameSetHandler). This
- behavior is encapsulated in a WKWebController class. Behavior that may be extended/overriden
- is described with several protocols: WKLocationChangeHandler and WKContextMenuHandler.
- WKWebController also implements these protocols.
-
- ***
+ 4. When the controller receives a receivedDataForLocation: with a WKLoadProgress that
+ contains bytesSoFar==totalToLoad the location specified is completely loaded. Clients
+ may display the location string to indicate completion of a loaded resource.
+ When the controller receives a loadingFinished message the main document and all it
+ resources have been loaded. Controllers should terminate progress indicators at
+ this point.
+
*/
@interface WKWebView : NSView
{
@@ -86,22 +69,31 @@
}
- initWithFrame: (NSRect)frame;
-- initWithFrame: (NSRect)frame dataSource: (NSWebPageDataSource *)dataSource;
+
+// Convenience method. initWithFrame:url: will create a controller and data source.
- initWithFrame: (NSRect)frame url: (NSURL *)url;
-- (NSWebPageDataSource *)dataSource;
-- (void)setDataSource: (NSWebPageDataSource *)ds;
-// Either creates a new datasource or reuses the same datasource for
-// URLs that are qualified, i.e. URLs with an anchor target.
-- (BOOL)setURL: (NSURL *)url;
+// Set and get the delegate.
+- (void)setDelegate: (id <WKWebViewDelegate>)delegate;
+- (id <WKWebViewDelegate>)delegate;
+
+
+// Set and get the controller. Note that the controller is not retained.
+// Perhaps setController: should be private?
+- (void)setController: (id <WKWebController>)controller;
+- (id <WKWebController>)controller;
+
// This method should not be public until we have a more completely
// understood way to subclass WKWebView.
- (void)layout;
+
+// Stop animating animated GIFs, etc.
- (void)stopAnimations;
+
// Font API
- (void)setFontSizes: (NSArray *)sizes;
- (NSArray *)fontSize;
@@ -111,32 +103,40 @@
- (void)setFixedFont: (NSSFont *)font;
- (NSFont *)fixedFont;
-// Drag and drop links and images. Others?
-- (void)setDragFromEnabled: (BOOL)flag;
-- (BOOL)dragFromEnabled;
-- (void)setDragToEnabled: (BOOL)flag;
-- (BOOL)dragToEnabled;
+// Drag and drop links and images. Others?
+- (void)setCanDragFrom: (BOOL)flag;
+- (BOOL)canDragFrom;
+- (void)setCanDragTo: (BOOL)flag;
+- (BOOL)canDragTo;
-#ifdef HAVE_WKCONTROLLER
-- (void)setController: (WKWebController *)controller;
-#else
-- (void)setLocationChangeHandler: (WKLocationChangeHandler *)client;
-- (void)setContextMenuHandler: (WKContextMenuHandler *)handler;
-#endif
+// Returns an array of built-in context menu items for this node.
+// Generally called by WKContextMenuHandlers from contextMenuItemsForNode:
+- (NSArray *)defaultContextMenuItemsForNode: (WKDOMNode *);
- (void)setEnableContextMenus: (BOOL)flag;
- (BOOL)contextMenusEnabled;
-- (void)setDefaultContextMenu: (NSMenu *)menu;
-- (NSMenu *)defaultContextMenu;
-// MCJ thinks we need high level find API.
+
+// Most folks want selection API on the view. Don suggested we mirror the
+// NSText API. NSText represents selection as a range. What does this mean
+// in the context of an HTML page? What is the selection range in a table?
+// What can you do with the selection range? I'm not sure if can get away
+// with this simplistic API. We may have to use something similar to the
+// DOM selection API. I'm also still uncomfortable putting this API on the
+// view.
+- (void)setSelectedRange:(NSRange)aRange;
+- (NSRange)selectedRange;
+
+
+// MCJ thinks we need high level find API on view.
+
@end
/*
- Other areas still to consider:
+ Areas still to consider:
ALT image text and link URLs
Should this be built-in? or able to be overriden?
diff --git a/WebKit/WebView.subproj/WKWebController.h b/WebKit/WebView.subproj/WKWebController.h
index 9525f73..e2196d9 100644
--- a/WebKit/WebView.subproj/WKWebController.h
+++ b/WebKit/WebView.subproj/WKWebController.h
@@ -6,27 +6,108 @@
*/
#import <Cocoa/Cocoa.h>
- at interface WKWebController : NSObject <WKLoadHandler, WKScriptContextHandler, WKFrameSetHandler, WKCredentialsHandler, WKLocationChangeHandler, WKContextMenuHandler>
+#ifdef READY_FOR_PRIMETIME
+
+/*
+ WKWebController manages the interaction between WKWebView and WKWebDataSource.
+ Intances of WKWebController retain their view and data source.
+
+ [As in the appkit classes NSWindow and NSWindowController, it will be necessary
+ to have non-retained back pointers from WKWebView and WKWebDataSource to their
+ controller. Not retaining the controller will prevent cycles. Of course, not
+ retaining is bad, as it can lead to dangling references. We could invert the reference
+ graph and add ...inView: and ...inDataSource: to the API, but that's ugly. If it's
+ good enough for the appkit, it's good enough for us. Ugh.]
+
+ .--(p)WKWebController --.
+ | . . |
+ | . . |
+ \|/ . . \|/
+ (p)WKWebViewDelegate <-- (c)WKWebView (c)WKWebDataSource --> (p)WKWebDataSourceDelegate
+
+ (c) indicates a class, (p) indicates a protocol. The solid lines indicate an
+ retain reference. The dotted lines indicate a non-retained reference.
+
+ The WKWebController implements required behavior. WKWebView and WKWebDataSource
+ cannot function without a controller.
+
+ Delegates implement optional behavior. WKWebView doesn't require a WKWebViewDelegate,
+ nor does WKWebDataSource require a WKWebDataSourceDelegate.
+
+ It it expected that alternate implementations of WKWebController will be written for
+ alternate views of the web page described by WKWebDataSource. For example, a
+ view that draws the DOM tree would require both a subclass of NSView and an
+ implementation of WKWebController. It is also possible that a web crawler
+ may implement a WKWebController with no corresponding view.
+
+ WKConcreteWebController may be subclassed to modify the behavior of the standard
+ WKWebView and WKWebDataSource.
+*/
+
+
+/*
+ WKWebController implements all the behavior that ties together WKWebView
+ and WKWebDataSource. See each inherited protocol for a more complete
+ description.
+
+ [Don and I both agree that all these little protocols are useful to cleanly
+ describe snippets of behavior, but do we explicity reference them anywhere,
+ or do we just use the umbrella protocol?]
+*/
+ at protocol WKWebController <WKLoadHandler, WKScriptContextHandler, WKFrameSetHandler, WKCredentialsHandler, WKLocationChangeHandler>
+
+- (void)setDataSource: (WKWebDataSource *)dataSource;
+- (WKWebDataSource *)dataSource
+
+- (void)setView: (WKWebView *)view;
+- (WKWebView *)view;
+
+ at end
+
+
+/*
+ WKWebViewDelegates implement protocols that modify the behavior of
+ WKWebViews. A WKWebView does not require a delegate.
+*/
+ at protocol WKWebViewDelegate <WKContextMenuHandler>
@end
+
+/*
+ WKWebDataSourceDelegate implement protocols that modify the behavior of
+ WKWebDataSources. A WKWebDataSources does not require a delegate.
+*/
+ at protocol WKWebDataSourceDelegate <?>
+ at end
+
+
+// Is WKConcreteWebController the right name? The name fits with the
+// scheme used by Foundation, although Foundation's concrete classes
+// typically aren't public.
+ at interface WKConcreteWebController : NSObject <WKWebController>
+- initWithView: (WKWebView *) dataSource: (WKWebDataSource *)dataSource;
+ at end
+
+
// See the comments in WKWebPageView above for more description about this protocol.
@protocol WKLocationChangeHandler
-- (BOOL)locationWillChange;
+
+- (void)loadingStarted;
- (void)loadingCancelled;
- (void)loadingStopped;
- (void)loadingFinished;
-- (void)loadingStarted;
+
+- (void)loadedPageTitle: (NSString *)title;
+
@end
@protocol WKContextMenuHandler
-/*
- We decided to implement this in terms of a fixed set of types rather
- than per node.
-
- What items should be supported in the default context menus?
-*/
+// Returns the array of menu items for this node that will be displayed in the context menu.
+// Typically this would be implemented by returning the results of WKWebView defaultContextMenuItemsForNode:
+// after making any desired changes or additions.
+- (NSArray *)contextMenuItemsForNode: (WKDOMNode *);
@end
/*
@@ -56,7 +137,9 @@
typically for non-base URLs this should be done after a URL (i.e. image)
has been completely downloaded.
*/
-- (void)receivedDataForLocation: (WKLoadProgress *)progress;
+- (void)receivedProgress: (WKLoadProgress *)progress forLocation: (NSString *)lcoation;
+
+- (void)timeoutForLocation: (NSString *)location partialProgress: (WKLoadProgress *)progress;
@end
@@ -69,13 +152,32 @@
@interface WKLoadProgress
{
int bytesSoFar; // 0 if this is the start of load
- int totalLoaded; // -1 if this is not known.
+ int totalToLoad; // -1 if this is not known.
// bytesSoFar == totalLoaded when complete
- NSString *location; // Needs to be a string, not URL.
- LOAD_TYPES type; // load types, either image, css, jscript, or html
+ WK_LOAD_TYPES type; // load types, either image, css, jscript, or html
+}
+ at end
+
+/*
+ Error handling:
+ error conditions:
+ timeout
+ unrecognized/handled mime-type
+ javascript errors
+ invalid url
+ parsing errors
+
+*/
+ at interface WKError
+{
+ NSString *description;
+ int code;
}
@end
+ at protocol WKWebDataSourceErrorHandler
+- error: (WKError *)error;
+ at end
/*
@@ -85,6 +187,7 @@
*/
@protocol WKScriptContextHandler
+// setStatusText and statusText are used by Javascript's status bar text methods.
- (void)setStatusText: (NSString *)text;
- (NSString *)statusText;
@@ -99,11 +202,10 @@
*/
@protocol WKFrameSetHandler
- (NSArray *)frameNames;
-- (WKFrame *)findFrameNamed: (NSString *)name;
+- (id <WKFrame>) findFrameNamed: (NSString *)name;
- (BOOL)frameExists: (NSString *)name;
-- (BOOL)openURLInFrame: (WKFrame *)aFrame url: (NSURL *)url;
+- (void)openURL: (NSURL *)url inFrame: (id <WKFrame>) frame;
@end
- at protocol WKFrame
-//
- at end
+#endif
+
diff --git a/WebKit/WebView.subproj/WKWebDataSource.h b/WebKit/WebView.subproj/WKWebDataSource.h
index 42c6bff..6d3f53b 100644
--- a/WebKit/WebView.subproj/WKWebDataSource.h
+++ b/WebKit/WebView.subproj/WKWebDataSource.h
@@ -17,19 +17,9 @@
Typical usage of a WKWebDataSource.
WKWebDataSource *dataSource = [[WKWebDataSource alloc] initWithURL: url];
-
- [dataSource setFrameSetHandler: (WKFrameSetHandler *)myManager];
- [dataSource setScriptContextHandler: (WKScriptContextHandler *)myContext];
- [dataSource setLoadHandler: (WKLoadHandler *)myLoadHandler];
- [dataSource setCredentialsHandler: (WKCredentialsHandler *)myCredentialsHandler];
- ...
- or
- ...
- [dataSource setController: (WKWebController *)myController];
+ id <WKWebController>myController = [[MyControllerClass alloc] init];
+ [myController setDataSource: dataSource];
- Questions:
- Multiple protocols or controller?
- Should we use CF XML data types, or our own?
*/
#ifdef READY_FOR_PRIMETIME
@@ -41,40 +31,60 @@
}
-// Can these init methods return nil? e.g. if URL is invalid, or should they
-// throw exceptions?
-- initWithURL: (NSURL *)url;
+// Returns nil if object cannot be initialized due to a malformed URL (RFC 1808).
+- initWithURL: (NSURL *)inputUrl;
+
- initWithData: (NSData *)data;
- initWithString: (NSString *)string;
-// ?? How do you create subclasses of WKURILoader, how is this
-// expected to be used?
+// Ken, need some help with one.
- initWithLoader: (WKURILoader *)loader;
-// ?? We don't have a NS streams API!!
-- initWithStream: (NSStream *)stream
+
+// Set the controller for this data source. NOTE: The controller is not retained by the
+// data source.
+// Perhaps setController: should be private?
+- (void)setController: (id <WKWebController>)controller;
+- (id <WKWebController>)controller;
+
// May return nil if not initialized with a URL.
-- (NSURL *)url;
+- (NSURL *)inputURL;
+
+
+// The inputURL may resolve to a different URL as a result of
+// either a client side refresh <META HTTP-EQUIV="refresh" ...> or
+// a DNS redirect. Both of these implicit actions should not
+// require a new data source. The resolvedURL is the URL that is
+// ultimately used to fetch page data.
+// [We need more brain cells applied to this issue.]
+- (NSURL *)resolvedURL;
+
-// Start actually getting (if initialized with a URL) and parsing data.
-- (void)startLoading;
+// Start actually getting (if initialized with a URL) and parsing data. If the data source
+// is still performing a previous load it will be stopped.
+// If forceRefresh is YES the document will load from the net, not the cache.
+- (void)startLoading: (BOOL)forceRefresh;
+
+
+// Cancels any pending loads. A data source is conceptually only ever loading
+// one document at a time, although one document may have many related
+// resources. stopLoading will stop all loads related to the data source.
+// Returns NO if the data source is not currently loading.
+- (void)stopLoading;
+
+
+// Returns YES if there are any pending loads.
+- (BOOL)isLoading;
-// Cancel any pending loads.
-- (BOOL)stopLoading;
// Get DOM access to the document.
- (WKDOMDocument *)document;
+
// Get the actual source of the docment.
- (NSString *)documentText;
-// Get a 'pretty' version of the document, created by traversal of the DOM.
-- (NSString *)formattedDocumentText;
-
-// Get the currently focused node. Is this appropriate for the model, or
-// should this be handled by the view?
-- (WKDOMNode *)activeNode;
// URL reference point, these should probably not be public for 1.0.
- setBase: (NSURL *)url;
@@ -82,81 +92,33 @@
- setBaseTarget: (NSURL *)url;
- (NSURL *)baseTarget;
+
- (NSString *)encoding;
+
// Style sheet
- (void)setUserStyleSheet: (NSURL *)url;
- (void)setUserStyleSheet: (NSString *)sheet;
-// Searching, to support find in clients. regular expressions?
-- (WKSearchState *)findTextBegin;
-- (NSString *)findTextNext: (WKRegularExpression *)exp direction: (BOOL)forward state: (WKSearchState *)state;
-- (NSString *)findTextNext: (NSString *)string direction: (BOOL)forward caseSensitive: (BOOL)case state: (WKSearchState *)state;
-
-// Selection
-- (NSString *)selectedText;
-- (WKDOMRange *)selectedRange;
-- (void)setSelection: (WKDOMRange *range);
-- (BOOL)hasSelection;
-- (void)selectAll;
-
-#ifdef HAVE_WKCONTROLLER
-- (void)setController: (WKWebController *)controller;
-#else
-- (void)setLoadHandler: (WKLoadHandler *)fmanager;
-- (void)setFrameSetHandler: (WKFrameSetHandler *)fmanager;
-- (void)setScriptContextHandler: (WKScriptContextHandler *)context;
-#endif
-
-- executeScript: (NSString *)string;
-// Same as above except uses the node as 'this' value
-- executeScript: (NSString *)string withNode: (WKDOMNode *)node;
-// This API reflects the KDE API, but is it sufficient?
-- (BOOL)scheduleScript: (NSString *)string withNode: (WKDOMNode *)node
-- executeScheduledScript;
+// Searching, to support find in clients. regular expressions?
+- (WKSearchState *)beginSearch;
+- (NSString *)searchFor: (NSString *)string direction: (BOOL)forward caseSensitive: (BOOL)case state: (WKSearchState *)state;
// a.k.a shortcut icons, http://msdn.microsoft.com/workshop/Author/dhtml/howto/ShortcutIcon.asp.
-// This may be removed to a category to prevent unnecessary linkage to the AppKit. Note, however
-// that this means WebCore, specifically KWQ, also doesn't have dependencies on the AppKit.
+// This method may be moved to a category to prevent unnecessary linkage to the AppKit. Note, however
+// that WebCore also has dependencies on the appkit.
- (NSImage *)icon;
+
// Is page secure, e.g. https, ftps
-// Should this perhaps be on the URL?
-// This would the be implemented like this
-// return [[self url] isSecure];
- (BOOL)isPageSecure;
-// ---------------------- Convenience methods ----------------------
-- (NSString *)pageTitle;
-// ---------------------------------------------------------------
+// Returns nil or the page title.
+- (NSString *)pageTitle;
-/*
- Notifications?
- In general, how often should we notify? We should use notifications
- if we anticipate multiple clients, no return types, and generally
- asynchronous or indirect behaviour.
-
- notifications:
- WKSelectionChangedNotification
- WKNodeActivatedNotification
- WKDocumentChangedNotification
-
- Error handling:
- exceptions?
- nil returns?
- errors by notification?
-
- error conditions:
- timeout
- unrecognized/handled mime-type
- javascript errors
- invalid url
- parsing errors
-
-*/
@end
diff --git a/WebKit/WebView.subproj/WKWebView.h b/WebKit/WebView.subproj/WKWebView.h
index e15db15..1a113ad 100644
--- a/WebKit/WebView.subproj/WKWebView.h
+++ b/WebKit/WebView.subproj/WKWebView.h
@@ -14,70 +14,53 @@
Typical usage of a WKWebView.
NSURL *url = [NSURL URLWithString: @"http://www.apple.com"];
- ...
WKWebDataSource *dataSource = [[WKWebDataSource alloc] initWithURL: url];
WKWebView *view = [[WKWebView alloc] initWithFrame: myFrame];
- [view setDataSource: dataSource];
- [[view dataSource] startLoading];
- ...
- or
- ...
- WKWebDataSource *dataSource = [[WKWebDataSource alloc] initWithURL: url];
- WKWebView *view = [[WKWebView alloc] initWithFrame: myFrame DataSource: url];
- [[view dataSource] startLoading];
+ WKConcreteWebController *controller = [[WKConcreteWebController alloc] initWithView: view dataSource: dataSource];
+
+ [[[view controller] dataSource] startLoading];
+
...
+
or
+
...
+
WKWebView *view = [[WKWebView alloc] initWithFrame: myFrame url: url];
- [[view dataSource] startLoading];
+ [[[view controller] dataSource] startLoading];
+
- What is the behaviour of the view after it has been initialized and -startLoading is called?
+ What is the behaviour of the view after it has been initialized and
+ startLoading: is called?
- 1. When the data source is set (i.e. -setDataSource:) -locationWillChange will be sent
- to the view's controller. It may veto by returning NO. Note that if the convenience initializers
- are used no controller will have been set, and thus no chance to veto will be provided.
+ 1. No WKLocationChangedHandler messages will be sent until
+ startLoading: is called. After startLoading is called a loadingStarted
+ message will be sent to the controller. The view will remain unchanged
+ until the controller receives a receivedDataForLocation: message
+ from the data source.
+
+ If stopLoading is called before receipt of a receivedDataForLocation:, loading will
+ abort, the view will be unchanged, and the controller will receive a loadingCancelled
+ message.
- 2. The view will do nothing until receipt of its first -receivedDataForURL: message
- from its data source. Thus the view will not change its content before users have
- a chance to cancel slow URLs.
-
- During this time, if -stopLoading is called on the data source, loading will
- abort. If the loading is stopped the contents of the window will be unchanged.
- [This implies that the data source should revert to the previous data source.
- Will that be problematic?.] The controller will receive a -loadingCancelled message
- if the load is aborted during this period.
-
- Controllers should initiate progress indicators at this point (how?).
+ Controllers should initiate progress indicators upon receipt of loadingStarted,
+ and terminate when either a loadingCancelled or loadingStopped is received.
- 3. After receipt of it first -receivedDataForURL: it will clear its contents
- and perform its first layout. At this point a loadingStarted message will
- be sent to the client.
+ 2. After the controller receives it's first receivedDataForLocation: the contents of
+ the view will be cleared and layout may begin.
- 4. Upon every subsequent receipts of -finishedReceivingDataForURL: messages it
- will perform additional layouts. Note that these may be coalesced, depending
- on the interval the messages are received. During this time the load may
- be stopped. The layout may be incomplete if the load is stopped before all
- the referenced documents are loaded. If the layout is stopped during this
- period the controller will received a -loadingStopped message.
+ 3. Upon subsequent receipt of receivedDataForLocation: messages the controller
+ may trigger a document layout. Note that layouts may be coalesced. If stopLoading
+ is called before the document has fully loaded, the layout will be incomplete, and a
+ loadingStopped message will be sent to the controller
- 5. When -documentReceived is received the loading and initial layout is complete.
- Controllers should terminate progress indicators at this point. At this point
- controller will receive a -loadingFinished message.
-
- What is the behavior of the view when a link is clicked?
-
- See above. The behavior is exactly as above.
-
-
- ***
-
- The control behavior and view/model interdependencies of WK are manifested by several
- protocols (so far: WKLoadHandler, WKScriptContextHandler, WKFrameSetHandler). This
- behavior is encapsulated in a WKWebController class. Behavior that may be extended/overriden
- is described with several protocols: WKLocationChangeHandler and WKContextMenuHandler.
- WKWebController also implements these protocols.
-
- ***
+ 4. When the controller receives a receivedDataForLocation: with a WKLoadProgress that
+ contains bytesSoFar==totalToLoad the location specified is completely loaded. Clients
+ may display the location string to indicate completion of a loaded resource.
+ When the controller receives a loadingFinished message the main document and all it
+ resources have been loaded. Controllers should terminate progress indicators at
+ this point.
+
*/
@interface WKWebView : NSView
{
@@ -86,22 +69,31 @@
}
- initWithFrame: (NSRect)frame;
-- initWithFrame: (NSRect)frame dataSource: (NSWebPageDataSource *)dataSource;
+
+// Convenience method. initWithFrame:url: will create a controller and data source.
- initWithFrame: (NSRect)frame url: (NSURL *)url;
-- (NSWebPageDataSource *)dataSource;
-- (void)setDataSource: (NSWebPageDataSource *)ds;
-// Either creates a new datasource or reuses the same datasource for
-// URLs that are qualified, i.e. URLs with an anchor target.
-- (BOOL)setURL: (NSURL *)url;
+// Set and get the delegate.
+- (void)setDelegate: (id <WKWebViewDelegate>)delegate;
+- (id <WKWebViewDelegate>)delegate;
+
+
+// Set and get the controller. Note that the controller is not retained.
+// Perhaps setController: should be private?
+- (void)setController: (id <WKWebController>)controller;
+- (id <WKWebController>)controller;
+
// This method should not be public until we have a more completely
// understood way to subclass WKWebView.
- (void)layout;
+
+// Stop animating animated GIFs, etc.
- (void)stopAnimations;
+
// Font API
- (void)setFontSizes: (NSArray *)sizes;
- (NSArray *)fontSize;
@@ -111,32 +103,40 @@
- (void)setFixedFont: (NSSFont *)font;
- (NSFont *)fixedFont;
-// Drag and drop links and images. Others?
-- (void)setDragFromEnabled: (BOOL)flag;
-- (BOOL)dragFromEnabled;
-- (void)setDragToEnabled: (BOOL)flag;
-- (BOOL)dragToEnabled;
+// Drag and drop links and images. Others?
+- (void)setCanDragFrom: (BOOL)flag;
+- (BOOL)canDragFrom;
+- (void)setCanDragTo: (BOOL)flag;
+- (BOOL)canDragTo;
-#ifdef HAVE_WKCONTROLLER
-- (void)setController: (WKWebController *)controller;
-#else
-- (void)setLocationChangeHandler: (WKLocationChangeHandler *)client;
-- (void)setContextMenuHandler: (WKContextMenuHandler *)handler;
-#endif
+// Returns an array of built-in context menu items for this node.
+// Generally called by WKContextMenuHandlers from contextMenuItemsForNode:
+- (NSArray *)defaultContextMenuItemsForNode: (WKDOMNode *);
- (void)setEnableContextMenus: (BOOL)flag;
- (BOOL)contextMenusEnabled;
-- (void)setDefaultContextMenu: (NSMenu *)menu;
-- (NSMenu *)defaultContextMenu;
-// MCJ thinks we need high level find API.
+
+// Most folks want selection API on the view. Don suggested we mirror the
+// NSText API. NSText represents selection as a range. What does this mean
+// in the context of an HTML page? What is the selection range in a table?
+// What can you do with the selection range? I'm not sure if can get away
+// with this simplistic API. We may have to use something similar to the
+// DOM selection API. I'm also still uncomfortable putting this API on the
+// view.
+- (void)setSelectedRange:(NSRange)aRange;
+- (NSRange)selectedRange;
+
+
+// MCJ thinks we need high level find API on view.
+
@end
/*
- Other areas still to consider:
+ Areas still to consider:
ALT image text and link URLs
Should this be built-in? or able to be overriden?
diff --git a/WebKit/WebView.subproj/WebController.h b/WebKit/WebView.subproj/WebController.h
index 9525f73..e2196d9 100644
--- a/WebKit/WebView.subproj/WebController.h
+++ b/WebKit/WebView.subproj/WebController.h
@@ -6,27 +6,108 @@
*/
#import <Cocoa/Cocoa.h>
- at interface WKWebController : NSObject <WKLoadHandler, WKScriptContextHandler, WKFrameSetHandler, WKCredentialsHandler, WKLocationChangeHandler, WKContextMenuHandler>
+#ifdef READY_FOR_PRIMETIME
+
+/*
+ WKWebController manages the interaction between WKWebView and WKWebDataSource.
+ Intances of WKWebController retain their view and data source.
+
+ [As in the appkit classes NSWindow and NSWindowController, it will be necessary
+ to have non-retained back pointers from WKWebView and WKWebDataSource to their
+ controller. Not retaining the controller will prevent cycles. Of course, not
+ retaining is bad, as it can lead to dangling references. We could invert the reference
+ graph and add ...inView: and ...inDataSource: to the API, but that's ugly. If it's
+ good enough for the appkit, it's good enough for us. Ugh.]
+
+ .--(p)WKWebController --.
+ | . . |
+ | . . |
+ \|/ . . \|/
+ (p)WKWebViewDelegate <-- (c)WKWebView (c)WKWebDataSource --> (p)WKWebDataSourceDelegate
+
+ (c) indicates a class, (p) indicates a protocol. The solid lines indicate an
+ retain reference. The dotted lines indicate a non-retained reference.
+
+ The WKWebController implements required behavior. WKWebView and WKWebDataSource
+ cannot function without a controller.
+
+ Delegates implement optional behavior. WKWebView doesn't require a WKWebViewDelegate,
+ nor does WKWebDataSource require a WKWebDataSourceDelegate.
+
+ It it expected that alternate implementations of WKWebController will be written for
+ alternate views of the web page described by WKWebDataSource. For example, a
+ view that draws the DOM tree would require both a subclass of NSView and an
+ implementation of WKWebController. It is also possible that a web crawler
+ may implement a WKWebController with no corresponding view.
+
+ WKConcreteWebController may be subclassed to modify the behavior of the standard
+ WKWebView and WKWebDataSource.
+*/
+
+
+/*
+ WKWebController implements all the behavior that ties together WKWebView
+ and WKWebDataSource. See each inherited protocol for a more complete
+ description.
+
+ [Don and I both agree that all these little protocols are useful to cleanly
+ describe snippets of behavior, but do we explicity reference them anywhere,
+ or do we just use the umbrella protocol?]
+*/
+ at protocol WKWebController <WKLoadHandler, WKScriptContextHandler, WKFrameSetHandler, WKCredentialsHandler, WKLocationChangeHandler>
+
+- (void)setDataSource: (WKWebDataSource *)dataSource;
+- (WKWebDataSource *)dataSource
+
+- (void)setView: (WKWebView *)view;
+- (WKWebView *)view;
+
+ at end
+
+
+/*
+ WKWebViewDelegates implement protocols that modify the behavior of
+ WKWebViews. A WKWebView does not require a delegate.
+*/
+ at protocol WKWebViewDelegate <WKContextMenuHandler>
@end
+
+/*
+ WKWebDataSourceDelegate implement protocols that modify the behavior of
+ WKWebDataSources. A WKWebDataSources does not require a delegate.
+*/
+ at protocol WKWebDataSourceDelegate <?>
+ at end
+
+
+// Is WKConcreteWebController the right name? The name fits with the
+// scheme used by Foundation, although Foundation's concrete classes
+// typically aren't public.
+ at interface WKConcreteWebController : NSObject <WKWebController>
+- initWithView: (WKWebView *) dataSource: (WKWebDataSource *)dataSource;
+ at end
+
+
// See the comments in WKWebPageView above for more description about this protocol.
@protocol WKLocationChangeHandler
-- (BOOL)locationWillChange;
+
+- (void)loadingStarted;
- (void)loadingCancelled;
- (void)loadingStopped;
- (void)loadingFinished;
-- (void)loadingStarted;
+
+- (void)loadedPageTitle: (NSString *)title;
+
@end
@protocol WKContextMenuHandler
-/*
- We decided to implement this in terms of a fixed set of types rather
- than per node.
-
- What items should be supported in the default context menus?
-*/
+// Returns the array of menu items for this node that will be displayed in the context menu.
+// Typically this would be implemented by returning the results of WKWebView defaultContextMenuItemsForNode:
+// after making any desired changes or additions.
+- (NSArray *)contextMenuItemsForNode: (WKDOMNode *);
@end
/*
@@ -56,7 +137,9 @@
typically for non-base URLs this should be done after a URL (i.e. image)
has been completely downloaded.
*/
-- (void)receivedDataForLocation: (WKLoadProgress *)progress;
+- (void)receivedProgress: (WKLoadProgress *)progress forLocation: (NSString *)lcoation;
+
+- (void)timeoutForLocation: (NSString *)location partialProgress: (WKLoadProgress *)progress;
@end
@@ -69,13 +152,32 @@
@interface WKLoadProgress
{
int bytesSoFar; // 0 if this is the start of load
- int totalLoaded; // -1 if this is not known.
+ int totalToLoad; // -1 if this is not known.
// bytesSoFar == totalLoaded when complete
- NSString *location; // Needs to be a string, not URL.
- LOAD_TYPES type; // load types, either image, css, jscript, or html
+ WK_LOAD_TYPES type; // load types, either image, css, jscript, or html
+}
+ at end
+
+/*
+ Error handling:
+ error conditions:
+ timeout
+ unrecognized/handled mime-type
+ javascript errors
+ invalid url
+ parsing errors
+
+*/
+ at interface WKError
+{
+ NSString *description;
+ int code;
}
@end
+ at protocol WKWebDataSourceErrorHandler
+- error: (WKError *)error;
+ at end
/*
@@ -85,6 +187,7 @@
*/
@protocol WKScriptContextHandler
+// setStatusText and statusText are used by Javascript's status bar text methods.
- (void)setStatusText: (NSString *)text;
- (NSString *)statusText;
@@ -99,11 +202,10 @@
*/
@protocol WKFrameSetHandler
- (NSArray *)frameNames;
-- (WKFrame *)findFrameNamed: (NSString *)name;
+- (id <WKFrame>) findFrameNamed: (NSString *)name;
- (BOOL)frameExists: (NSString *)name;
-- (BOOL)openURLInFrame: (WKFrame *)aFrame url: (NSURL *)url;
+- (void)openURL: (NSURL *)url inFrame: (id <WKFrame>) frame;
@end
- at protocol WKFrame
-//
- at end
+#endif
+
diff --git a/WebKit/WebView.subproj/WebDataSource.h b/WebKit/WebView.subproj/WebDataSource.h
index 42c6bff..6d3f53b 100644
--- a/WebKit/WebView.subproj/WebDataSource.h
+++ b/WebKit/WebView.subproj/WebDataSource.h
@@ -17,19 +17,9 @@
Typical usage of a WKWebDataSource.
WKWebDataSource *dataSource = [[WKWebDataSource alloc] initWithURL: url];
-
- [dataSource setFrameSetHandler: (WKFrameSetHandler *)myManager];
- [dataSource setScriptContextHandler: (WKScriptContextHandler *)myContext];
- [dataSource setLoadHandler: (WKLoadHandler *)myLoadHandler];
- [dataSource setCredentialsHandler: (WKCredentialsHandler *)myCredentialsHandler];
- ...
- or
- ...
- [dataSource setController: (WKWebController *)myController];
+ id <WKWebController>myController = [[MyControllerClass alloc] init];
+ [myController setDataSource: dataSource];
- Questions:
- Multiple protocols or controller?
- Should we use CF XML data types, or our own?
*/
#ifdef READY_FOR_PRIMETIME
@@ -41,40 +31,60 @@
}
-// Can these init methods return nil? e.g. if URL is invalid, or should they
-// throw exceptions?
-- initWithURL: (NSURL *)url;
+// Returns nil if object cannot be initialized due to a malformed URL (RFC 1808).
+- initWithURL: (NSURL *)inputUrl;
+
- initWithData: (NSData *)data;
- initWithString: (NSString *)string;
-// ?? How do you create subclasses of WKURILoader, how is this
-// expected to be used?
+// Ken, need some help with one.
- initWithLoader: (WKURILoader *)loader;
-// ?? We don't have a NS streams API!!
-- initWithStream: (NSStream *)stream
+
+// Set the controller for this data source. NOTE: The controller is not retained by the
+// data source.
+// Perhaps setController: should be private?
+- (void)setController: (id <WKWebController>)controller;
+- (id <WKWebController>)controller;
+
// May return nil if not initialized with a URL.
-- (NSURL *)url;
+- (NSURL *)inputURL;
+
+
+// The inputURL may resolve to a different URL as a result of
+// either a client side refresh <META HTTP-EQUIV="refresh" ...> or
+// a DNS redirect. Both of these implicit actions should not
+// require a new data source. The resolvedURL is the URL that is
+// ultimately used to fetch page data.
+// [We need more brain cells applied to this issue.]
+- (NSURL *)resolvedURL;
+
-// Start actually getting (if initialized with a URL) and parsing data.
-- (void)startLoading;
+// Start actually getting (if initialized with a URL) and parsing data. If the data source
+// is still performing a previous load it will be stopped.
+// If forceRefresh is YES the document will load from the net, not the cache.
+- (void)startLoading: (BOOL)forceRefresh;
+
+
+// Cancels any pending loads. A data source is conceptually only ever loading
+// one document at a time, although one document may have many related
+// resources. stopLoading will stop all loads related to the data source.
+// Returns NO if the data source is not currently loading.
+- (void)stopLoading;
+
+
+// Returns YES if there are any pending loads.
+- (BOOL)isLoading;
-// Cancel any pending loads.
-- (BOOL)stopLoading;
// Get DOM access to the document.
- (WKDOMDocument *)document;
+
// Get the actual source of the docment.
- (NSString *)documentText;
-// Get a 'pretty' version of the document, created by traversal of the DOM.
-- (NSString *)formattedDocumentText;
-
-// Get the currently focused node. Is this appropriate for the model, or
-// should this be handled by the view?
-- (WKDOMNode *)activeNode;
// URL reference point, these should probably not be public for 1.0.
- setBase: (NSURL *)url;
@@ -82,81 +92,33 @@
- setBaseTarget: (NSURL *)url;
- (NSURL *)baseTarget;
+
- (NSString *)encoding;
+
// Style sheet
- (void)setUserStyleSheet: (NSURL *)url;
- (void)setUserStyleSheet: (NSString *)sheet;
-// Searching, to support find in clients. regular expressions?
-- (WKSearchState *)findTextBegin;
-- (NSString *)findTextNext: (WKRegularExpression *)exp direction: (BOOL)forward state: (WKSearchState *)state;
-- (NSString *)findTextNext: (NSString *)string direction: (BOOL)forward caseSensitive: (BOOL)case state: (WKSearchState *)state;
-
-// Selection
-- (NSString *)selectedText;
-- (WKDOMRange *)selectedRange;
-- (void)setSelection: (WKDOMRange *range);
-- (BOOL)hasSelection;
-- (void)selectAll;
-
-#ifdef HAVE_WKCONTROLLER
-- (void)setController: (WKWebController *)controller;
-#else
-- (void)setLoadHandler: (WKLoadHandler *)fmanager;
-- (void)setFrameSetHandler: (WKFrameSetHandler *)fmanager;
-- (void)setScriptContextHandler: (WKScriptContextHandler *)context;
-#endif
-
-- executeScript: (NSString *)string;
-// Same as above except uses the node as 'this' value
-- executeScript: (NSString *)string withNode: (WKDOMNode *)node;
-// This API reflects the KDE API, but is it sufficient?
-- (BOOL)scheduleScript: (NSString *)string withNode: (WKDOMNode *)node
-- executeScheduledScript;
+// Searching, to support find in clients. regular expressions?
+- (WKSearchState *)beginSearch;
+- (NSString *)searchFor: (NSString *)string direction: (BOOL)forward caseSensitive: (BOOL)case state: (WKSearchState *)state;
// a.k.a shortcut icons, http://msdn.microsoft.com/workshop/Author/dhtml/howto/ShortcutIcon.asp.
-// This may be removed to a category to prevent unnecessary linkage to the AppKit. Note, however
-// that this means WebCore, specifically KWQ, also doesn't have dependencies on the AppKit.
+// This method may be moved to a category to prevent unnecessary linkage to the AppKit. Note, however
+// that WebCore also has dependencies on the appkit.
- (NSImage *)icon;
+
// Is page secure, e.g. https, ftps
-// Should this perhaps be on the URL?
-// This would the be implemented like this
-// return [[self url] isSecure];
- (BOOL)isPageSecure;
-// ---------------------- Convenience methods ----------------------
-- (NSString *)pageTitle;
-// ---------------------------------------------------------------
+// Returns nil or the page title.
+- (NSString *)pageTitle;
-/*
- Notifications?
- In general, how often should we notify? We should use notifications
- if we anticipate multiple clients, no return types, and generally
- asynchronous or indirect behaviour.
-
- notifications:
- WKSelectionChangedNotification
- WKNodeActivatedNotification
- WKDocumentChangedNotification
-
- Error handling:
- exceptions?
- nil returns?
- errors by notification?
-
- error conditions:
- timeout
- unrecognized/handled mime-type
- javascript errors
- invalid url
- parsing errors
-
-*/
@end
diff --git a/WebKit/WebView.subproj/WebFrameView.h b/WebKit/WebView.subproj/WebFrameView.h
index e15db15..1a113ad 100644
--- a/WebKit/WebView.subproj/WebFrameView.h
+++ b/WebKit/WebView.subproj/WebFrameView.h
@@ -14,70 +14,53 @@
Typical usage of a WKWebView.
NSURL *url = [NSURL URLWithString: @"http://www.apple.com"];
- ...
WKWebDataSource *dataSource = [[WKWebDataSource alloc] initWithURL: url];
WKWebView *view = [[WKWebView alloc] initWithFrame: myFrame];
- [view setDataSource: dataSource];
- [[view dataSource] startLoading];
- ...
- or
- ...
- WKWebDataSource *dataSource = [[WKWebDataSource alloc] initWithURL: url];
- WKWebView *view = [[WKWebView alloc] initWithFrame: myFrame DataSource: url];
- [[view dataSource] startLoading];
+ WKConcreteWebController *controller = [[WKConcreteWebController alloc] initWithView: view dataSource: dataSource];
+
+ [[[view controller] dataSource] startLoading];
+
...
+
or
+
...
+
WKWebView *view = [[WKWebView alloc] initWithFrame: myFrame url: url];
- [[view dataSource] startLoading];
+ [[[view controller] dataSource] startLoading];
+
- What is the behaviour of the view after it has been initialized and -startLoading is called?
+ What is the behaviour of the view after it has been initialized and
+ startLoading: is called?
- 1. When the data source is set (i.e. -setDataSource:) -locationWillChange will be sent
- to the view's controller. It may veto by returning NO. Note that if the convenience initializers
- are used no controller will have been set, and thus no chance to veto will be provided.
+ 1. No WKLocationChangedHandler messages will be sent until
+ startLoading: is called. After startLoading is called a loadingStarted
+ message will be sent to the controller. The view will remain unchanged
+ until the controller receives a receivedDataForLocation: message
+ from the data source.
+
+ If stopLoading is called before receipt of a receivedDataForLocation:, loading will
+ abort, the view will be unchanged, and the controller will receive a loadingCancelled
+ message.
- 2. The view will do nothing until receipt of its first -receivedDataForURL: message
- from its data source. Thus the view will not change its content before users have
- a chance to cancel slow URLs.
-
- During this time, if -stopLoading is called on the data source, loading will
- abort. If the loading is stopped the contents of the window will be unchanged.
- [This implies that the data source should revert to the previous data source.
- Will that be problematic?.] The controller will receive a -loadingCancelled message
- if the load is aborted during this period.
-
- Controllers should initiate progress indicators at this point (how?).
+ Controllers should initiate progress indicators upon receipt of loadingStarted,
+ and terminate when either a loadingCancelled or loadingStopped is received.
- 3. After receipt of it first -receivedDataForURL: it will clear its contents
- and perform its first layout. At this point a loadingStarted message will
- be sent to the client.
+ 2. After the controller receives it's first receivedDataForLocation: the contents of
+ the view will be cleared and layout may begin.
- 4. Upon every subsequent receipts of -finishedReceivingDataForURL: messages it
- will perform additional layouts. Note that these may be coalesced, depending
- on the interval the messages are received. During this time the load may
- be stopped. The layout may be incomplete if the load is stopped before all
- the referenced documents are loaded. If the layout is stopped during this
- period the controller will received a -loadingStopped message.
+ 3. Upon subsequent receipt of receivedDataForLocation: messages the controller
+ may trigger a document layout. Note that layouts may be coalesced. If stopLoading
+ is called before the document has fully loaded, the layout will be incomplete, and a
+ loadingStopped message will be sent to the controller
- 5. When -documentReceived is received the loading and initial layout is complete.
- Controllers should terminate progress indicators at this point. At this point
- controller will receive a -loadingFinished message.
-
- What is the behavior of the view when a link is clicked?
-
- See above. The behavior is exactly as above.
-
-
- ***
-
- The control behavior and view/model interdependencies of WK are manifested by several
- protocols (so far: WKLoadHandler, WKScriptContextHandler, WKFrameSetHandler). This
- behavior is encapsulated in a WKWebController class. Behavior that may be extended/overriden
- is described with several protocols: WKLocationChangeHandler and WKContextMenuHandler.
- WKWebController also implements these protocols.
-
- ***
+ 4. When the controller receives a receivedDataForLocation: with a WKLoadProgress that
+ contains bytesSoFar==totalToLoad the location specified is completely loaded. Clients
+ may display the location string to indicate completion of a loaded resource.
+ When the controller receives a loadingFinished message the main document and all it
+ resources have been loaded. Controllers should terminate progress indicators at
+ this point.
+
*/
@interface WKWebView : NSView
{
@@ -86,22 +69,31 @@
}
- initWithFrame: (NSRect)frame;
-- initWithFrame: (NSRect)frame dataSource: (NSWebPageDataSource *)dataSource;
+
+// Convenience method. initWithFrame:url: will create a controller and data source.
- initWithFrame: (NSRect)frame url: (NSURL *)url;
-- (NSWebPageDataSource *)dataSource;
-- (void)setDataSource: (NSWebPageDataSource *)ds;
-// Either creates a new datasource or reuses the same datasource for
-// URLs that are qualified, i.e. URLs with an anchor target.
-- (BOOL)setURL: (NSURL *)url;
+// Set and get the delegate.
+- (void)setDelegate: (id <WKWebViewDelegate>)delegate;
+- (id <WKWebViewDelegate>)delegate;
+
+
+// Set and get the controller. Note that the controller is not retained.
+// Perhaps setController: should be private?
+- (void)setController: (id <WKWebController>)controller;
+- (id <WKWebController>)controller;
+
// This method should not be public until we have a more completely
// understood way to subclass WKWebView.
- (void)layout;
+
+// Stop animating animated GIFs, etc.
- (void)stopAnimations;
+
// Font API
- (void)setFontSizes: (NSArray *)sizes;
- (NSArray *)fontSize;
@@ -111,32 +103,40 @@
- (void)setFixedFont: (NSSFont *)font;
- (NSFont *)fixedFont;
-// Drag and drop links and images. Others?
-- (void)setDragFromEnabled: (BOOL)flag;
-- (BOOL)dragFromEnabled;
-- (void)setDragToEnabled: (BOOL)flag;
-- (BOOL)dragToEnabled;
+// Drag and drop links and images. Others?
+- (void)setCanDragFrom: (BOOL)flag;
+- (BOOL)canDragFrom;
+- (void)setCanDragTo: (BOOL)flag;
+- (BOOL)canDragTo;
-#ifdef HAVE_WKCONTROLLER
-- (void)setController: (WKWebController *)controller;
-#else
-- (void)setLocationChangeHandler: (WKLocationChangeHandler *)client;
-- (void)setContextMenuHandler: (WKContextMenuHandler *)handler;
-#endif
+// Returns an array of built-in context menu items for this node.
+// Generally called by WKContextMenuHandlers from contextMenuItemsForNode:
+- (NSArray *)defaultContextMenuItemsForNode: (WKDOMNode *);
- (void)setEnableContextMenus: (BOOL)flag;
- (BOOL)contextMenusEnabled;
-- (void)setDefaultContextMenu: (NSMenu *)menu;
-- (NSMenu *)defaultContextMenu;
-// MCJ thinks we need high level find API.
+
+// Most folks want selection API on the view. Don suggested we mirror the
+// NSText API. NSText represents selection as a range. What does this mean
+// in the context of an HTML page? What is the selection range in a table?
+// What can you do with the selection range? I'm not sure if can get away
+// with this simplistic API. We may have to use something similar to the
+// DOM selection API. I'm also still uncomfortable putting this API on the
+// view.
+- (void)setSelectedRange:(NSRange)aRange;
+- (NSRange)selectedRange;
+
+
+// MCJ thinks we need high level find API on view.
+
@end
/*
- Other areas still to consider:
+ Areas still to consider:
ALT image text and link URLs
Should this be built-in? or able to be overriden?
diff --git a/WebKit/WebView.subproj/WebView.h b/WebKit/WebView.subproj/WebView.h
index 9525f73..e2196d9 100644
--- a/WebKit/WebView.subproj/WebView.h
+++ b/WebKit/WebView.subproj/WebView.h
@@ -6,27 +6,108 @@
*/
#import <Cocoa/Cocoa.h>
- at interface WKWebController : NSObject <WKLoadHandler, WKScriptContextHandler, WKFrameSetHandler, WKCredentialsHandler, WKLocationChangeHandler, WKContextMenuHandler>
+#ifdef READY_FOR_PRIMETIME
+
+/*
+ WKWebController manages the interaction between WKWebView and WKWebDataSource.
+ Intances of WKWebController retain their view and data source.
+
+ [As in the appkit classes NSWindow and NSWindowController, it will be necessary
+ to have non-retained back pointers from WKWebView and WKWebDataSource to their
+ controller. Not retaining the controller will prevent cycles. Of course, not
+ retaining is bad, as it can lead to dangling references. We could invert the reference
+ graph and add ...inView: and ...inDataSource: to the API, but that's ugly. If it's
+ good enough for the appkit, it's good enough for us. Ugh.]
+
+ .--(p)WKWebController --.
+ | . . |
+ | . . |
+ \|/ . . \|/
+ (p)WKWebViewDelegate <-- (c)WKWebView (c)WKWebDataSource --> (p)WKWebDataSourceDelegate
+
+ (c) indicates a class, (p) indicates a protocol. The solid lines indicate an
+ retain reference. The dotted lines indicate a non-retained reference.
+
+ The WKWebController implements required behavior. WKWebView and WKWebDataSource
+ cannot function without a controller.
+
+ Delegates implement optional behavior. WKWebView doesn't require a WKWebViewDelegate,
+ nor does WKWebDataSource require a WKWebDataSourceDelegate.
+
+ It it expected that alternate implementations of WKWebController will be written for
+ alternate views of the web page described by WKWebDataSource. For example, a
+ view that draws the DOM tree would require both a subclass of NSView and an
+ implementation of WKWebController. It is also possible that a web crawler
+ may implement a WKWebController with no corresponding view.
+
+ WKConcreteWebController may be subclassed to modify the behavior of the standard
+ WKWebView and WKWebDataSource.
+*/
+
+
+/*
+ WKWebController implements all the behavior that ties together WKWebView
+ and WKWebDataSource. See each inherited protocol for a more complete
+ description.
+
+ [Don and I both agree that all these little protocols are useful to cleanly
+ describe snippets of behavior, but do we explicity reference them anywhere,
+ or do we just use the umbrella protocol?]
+*/
+ at protocol WKWebController <WKLoadHandler, WKScriptContextHandler, WKFrameSetHandler, WKCredentialsHandler, WKLocationChangeHandler>
+
+- (void)setDataSource: (WKWebDataSource *)dataSource;
+- (WKWebDataSource *)dataSource
+
+- (void)setView: (WKWebView *)view;
+- (WKWebView *)view;
+
+ at end
+
+
+/*
+ WKWebViewDelegates implement protocols that modify the behavior of
+ WKWebViews. A WKWebView does not require a delegate.
+*/
+ at protocol WKWebViewDelegate <WKContextMenuHandler>
@end
+
+/*
+ WKWebDataSourceDelegate implement protocols that modify the behavior of
+ WKWebDataSources. A WKWebDataSources does not require a delegate.
+*/
+ at protocol WKWebDataSourceDelegate <?>
+ at end
+
+
+// Is WKConcreteWebController the right name? The name fits with the
+// scheme used by Foundation, although Foundation's concrete classes
+// typically aren't public.
+ at interface WKConcreteWebController : NSObject <WKWebController>
+- initWithView: (WKWebView *) dataSource: (WKWebDataSource *)dataSource;
+ at end
+
+
// See the comments in WKWebPageView above for more description about this protocol.
@protocol WKLocationChangeHandler
-- (BOOL)locationWillChange;
+
+- (void)loadingStarted;
- (void)loadingCancelled;
- (void)loadingStopped;
- (void)loadingFinished;
-- (void)loadingStarted;
+
+- (void)loadedPageTitle: (NSString *)title;
+
@end
@protocol WKContextMenuHandler
-/*
- We decided to implement this in terms of a fixed set of types rather
- than per node.
-
- What items should be supported in the default context menus?
-*/
+// Returns the array of menu items for this node that will be displayed in the context menu.
+// Typically this would be implemented by returning the results of WKWebView defaultContextMenuItemsForNode:
+// after making any desired changes or additions.
+- (NSArray *)contextMenuItemsForNode: (WKDOMNode *);
@end
/*
@@ -56,7 +137,9 @@
typically for non-base URLs this should be done after a URL (i.e. image)
has been completely downloaded.
*/
-- (void)receivedDataForLocation: (WKLoadProgress *)progress;
+- (void)receivedProgress: (WKLoadProgress *)progress forLocation: (NSString *)lcoation;
+
+- (void)timeoutForLocation: (NSString *)location partialProgress: (WKLoadProgress *)progress;
@end
@@ -69,13 +152,32 @@
@interface WKLoadProgress
{
int bytesSoFar; // 0 if this is the start of load
- int totalLoaded; // -1 if this is not known.
+ int totalToLoad; // -1 if this is not known.
// bytesSoFar == totalLoaded when complete
- NSString *location; // Needs to be a string, not URL.
- LOAD_TYPES type; // load types, either image, css, jscript, or html
+ WK_LOAD_TYPES type; // load types, either image, css, jscript, or html
+}
+ at end
+
+/*
+ Error handling:
+ error conditions:
+ timeout
+ unrecognized/handled mime-type
+ javascript errors
+ invalid url
+ parsing errors
+
+*/
+ at interface WKError
+{
+ NSString *description;
+ int code;
}
@end
+ at protocol WKWebDataSourceErrorHandler
+- error: (WKError *)error;
+ at end
/*
@@ -85,6 +187,7 @@
*/
@protocol WKScriptContextHandler
+// setStatusText and statusText are used by Javascript's status bar text methods.
- (void)setStatusText: (NSString *)text;
- (NSString *)statusText;
@@ -99,11 +202,10 @@
*/
@protocol WKFrameSetHandler
- (NSArray *)frameNames;
-- (WKFrame *)findFrameNamed: (NSString *)name;
+- (id <WKFrame>) findFrameNamed: (NSString *)name;
- (BOOL)frameExists: (NSString *)name;
-- (BOOL)openURLInFrame: (WKFrame *)aFrame url: (NSURL *)url;
+- (void)openURL: (NSURL *)url inFrame: (id <WKFrame>) frame;
@end
- at protocol WKFrame
-//
- at end
+#endif
+
--
WebKit Debian packaging
More information about the Pkg-webkit-commits
mailing list