W3C home > Mailing lists > Public > public-webapi@w3.org > February 2006

Window object, very rough cut of proposed content for first version of spec

From: Maciej Stachowiak <mjs@apple.com>
Date: Tue, 14 Feb 2006 02:29:49 -0800
Message-Id: <D2285453-83FC-4A5E-B4B1-646763FC9333@apple.com>
To: public-webapi@w3.org


Hello people interested in Web APIs,

Here's my proposal for what to put in the first version of the window  
object spec, as IDL with comments. This is a small subset of what the  
window interface provides in popular implementations. These features  
were selected as follows:

- Already widely interoparably implemented by mainstream HTML UAs
- Likely to be helpful for SVG or CDR requirements
- Simple (nothing that implies the existence of other interfaces with  
their own complex semantics; no events; but timers and location are  
included)
- Likely to be uncontroversial (nothing that would spawn debates over  
its moral values, like window.open)
- no networking or XML parsing, that will be in other specs

More complex features would likely be addressed in a follow-on  
version of the spec.

Please review this rough proposal to see if there's anything in here  
that you wildly object to, or anything you think desperately needs  
adding. Keep in mind that this is not the last word on specifying the  
window object, I would expect work on a follow-on to start  
immediately once this spec is done, covering a much broader range of  
features.


I propose one of the following for the title:

DOM Global Object (Level 3? or 1.0?)
DOM Window Object (Level 3? or 1.0?)
DOM Level 3 Views (especially if we incorporate AbstractView and  
DocumentView interfaces into this spec instead of just referencing  
views)

// or global or window or views?
module window
{
     // based on Mozilla and Safari interfaces, Internet Explorer  
docs, WHATWG draft
     interface Location {
         // the current URI
         readonly attribute DOMString href;

         // pieces of the URI, per the generic URI syntax
         readonly attribute DOMString hash; // (fragment)
         readonly attribute DOMString host; // hostname:port if port  
specified,
         readonly attribute DOMString hostname; // just the hostname,  
no port
         readonly attribute DOMString pathname;
         readonly attribute DOMString port;
         readonly attribute DOMString protocol; // scheme
         readonly attribute DOMString search;  // query

         void assign(in DOMString url); // go to the requested URL
         // does it make sense to spec reload and replace without  
specifying history behavior at all?
         void replace(in DOMString url);
         void reload();

         // same value as href; not all implementations have this  
explicitly but toString is always available
         // in ECMAScript, and probably this should be explicit for  
the sake of Java. Or we could skip it since
         // it matches href.
         DOMString toString();
     };

     // for ECMAScript there is a special case for this type, it can  
be either a string or a function.
     // In the string case, the string is eval'd in global scope when  
the timer fires.
     // in the function case JS allows extra arguments after the  
milliseconds argument; the function
     // is called with extra arguments if any when the timer fires
     interface TimerListener {
         // who knows - what interface would work for non-JS  
languages? this could just be an EventListener
         // but then we would have to define TimerEvent; it might  
also be handy to expose that to JS, in which
         // case this spec would incorporate one new feature for HTML  
UAs to implement. But I would expect it
         // to be a simple one.
     };

     // should this interface be called something else - Global,  
DOMWindow, DOMGlobal?
     // should specify that for ECMAScript execution this provides  
the global scope
     // based on Mozilla and Safari implementations, Win IE docs, Web  
Apps 1.0 draft (some also in SVG Tiny 1.2 draft)
     interface Window : views::AbstractView {
         // AbstractView has a document attribute of type  
DocumentView, should we drop the charade and admit it is a
         // Document?

         // self-reference
         readonly attribute Window window;

         // self-reference - why both? because both are used
         readonly attribute Window self;

         // name attribute of referencing frame/iframe/object, or  
name passed to window.open,
         // does it make sense to spec this without being html- 
specific or defining open?
         attribute DOMString name;

         // global object of containing document
         readonly attribute Window parent;

         // global object of outermost containing document
         readonly attribute Window top;

         // referencing <html:frame>, <html:iframe>, <html:object>,  
<svg:foreignObject>, <svg:animation> or other
	// embedding point, or null if none
         readonly attribute core::Element frameElement;

         // Location object representing the current location
         // assigning this has special behavior in ECMAScript, but it  
is otherwise read only
         // specifically, in ES a string URI can be assigned to  
location, having the same effect as location.assign(URI)
         readonly attribute Location location;

         // should timers allow more than long, maybe a floating  
point type? don't think anyone's timers have more precision
         // one-shot timer
         long setTimeout(in TimerListener listener, in long  
milliseconds);
         void clearTimeout(in long timerID);

         // repeating timer
         long setInterval(in TimerListener listener, in long  
milliseconds);
         void clearInterval(in long timerID);
     };
};


Other possible things to add (potentially more controversial):

- SVG uDOM style timers - way less convenient in JS but maybe better  
for Java
- Web Apps 1.0 proposed version of setTimeout / clearTimeout that  
take a language name as third parameter(*)
- SVG uDOM window.gotoLocation(in URI) - same effect as  
window.location.assign(URI)
- IE extension window.navigate(in URI) - same effect as  
window.location.assign(URI)
- an interface that adds contentWindow property to DOM elements that  
have contentDocument; perhaps an issue for individual language specs
- due to the dependence on AbstractViews, Document is required to  
have a defaultView attribute that points to the window, perhaps it is  
desirable to add aliases for it, e.g. "window" as in Web Apps 1.0  
draft or "global" as in SVG uDOM
- yet another alias for the window object's self-reference named  
"global"

(*) - I think this is unneeded, because there's no need to enable one  
language to set a timer that will eval code in another language. I  
think the string parameter versions of these should instead be  
defined as an ECMAScript binding feature and not in the IDL.
Received on Tuesday, 14 February 2006 10:29:58 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Tuesday, 8 January 2008 14:18:53 GMT