The documentation for the aFeatures param of openWindow() in nsIWindowWatcher.idl is unsatisfactory at best... We should document the various features.

I realize the interface is frozen... but these comments change nothing in the functionality and are _very_ useful for anyone actually using this function.

Danm should review this.

also need to add docs for: width, height, left, top, outerWidth, outerHeight, screenX ( == left), screenY ( == top), innerWidth ( == width), innerHeight ( == height)

'turn <foo> on or off' will need work because on/off have different meanings for different <foo> offhand, i think + "close" -- turn the close box ([x]) on or off should use this form: + "minimizable" -- allow or disallow minimizing the window i'd remove the parenthetical by "all" it's not usefully accurate win quirks dialog is more useful when used w/ chrome (you can have no icon, ala preferences) close=no requires dialog close=no trumps minimizable

Reassign to Boris

Comment on attachment 97473 [details] [diff] [review] Change how "close" is worded per how Windows implements it >+ "popup" -- special "popup" chrome should be shown window.openDialog("about:","something","chrome=all,popup=yes") in my phoenix and 10/8 builds relusts in a *very* bare window >+ "alwaysRaised" -- keep this window on the top of the window >+ stack in tests this didn't put it above other app's windows... >+ "centerscreen" -- create the new window centered on the screen this didn't work (2002091008-seamonkey-w2k)

> in my phoenix and 10/8 builds relusts in a *very* bare window Is that pheonix-specific or Mozilla too? > in tests this didn't put it above other app's windows... So maybe "on top of the windowwatcher's" window stack? > this didn't work (2002091008-seamonkey-w2k) Did you use the "chrome" flag with it too? And you may need "modal" and "titlebar".... It's also possible that it only works for openDialog()

This is the bugfile I've been looking for. I know that a reliable list of window features (and their definition) would be extremely helpful for book authors, web developers and the Gecko DOM reference. I am working on a meta-testcase for the open() method these days. The list provided by Boris is extremely useful (for book authors, web developers, sites with online documentation, etc). FYI, Gecko DOM Reference litteraly admits that the whole window.open() file needs updating. - hotkeys is not mentioned in attachment 97365 [details] [diff] [review] . My experimentations lead me to believe that hotkeys are always turn on and cannot be disabled. - copyhistory is not mentioned. My experimentations lead me to believe that history (list of visited urls) is always available and cannot be disabled. It would be most useful for interested people to indicate which window features must be used within signed scripts, otherwise such reference is not ideally useful. Some window features exclude or have precedence over other window features or implies other window features. (>> means "have precedence over") outerWidth/Height >> width/height >> innerWidth/innerHeight In the case of outerWidth/Height, this precedence is to a second degree. (I'll better explain this as soon as the meta-demo I'm working on will be online). left/top >> screenX/screenY Btw, left and top are not documented officially as supported by NS 6+ anywhere ... but they do work within Gecko-based browsers. Finally, it would be useful to explain and describe in a doc/reference the intricacies of the user preferences and the author setting the window features. I can assure you that in newsgroups, many people are mixed up, confused, overcome by the complexities involved here. Just 1 example: if the user has set his Preferences.../Category: Advanced/Scripts & plugins/Allow scripts to:/Move or resize existing windows checkbox to unchecked, then the author will not be able to use the very powerful sizeToContent() method but will nevertheless be able to set the popup window with "resizable=yes" in the list of features.

Argh ... forgot to add this. But if the user has set his Preferences.../Category: Advanced/Scripts & plugins/Allow scripts to:/Move or resize existing windows checkbox to CHECKED, then the author will be able to use the very powerful sizeToContent() method and can at the same time prevent the user from resizing the popup window with "resizable=no" in the list of features. Amazing!

Argh. This needs to actually land! > hotkeys is not mentioned That's because we do not implement it. > copyhistory is not mentioned Same reason. > indicate which window features must be used within signed scripts This is documentation for a function that can only be used from signed scripts anyway (note that it's _not_ window.open() but a function in nsIWindowWatcher; the fact that window.open() uses this internally is pure coincidence). I'd rather not document the "left/top/whatever" behavior if there's any chance it will change. This _is_ after all a frozen interface... (furthermore, users of this interface should never be using those options in the open-string anyway). Keep in mind that this is all documentation for people developing using the Mozilla toolkit, not for web developers.

I keep meaning to get to this. There are some corrections and additions I'd like to make. All this does want to be documented. However I think nsIWindowWatcher.idl is not the right place for that. It's an embedding component and this canonizes Mozilla's interpretation. At the level of the interface definition, it's just a string where hints can be sent to the implementing application.

Comment on attachment 97473 [details] [diff] [review] Change how "close" is worded per how Windows implements it sr=jst

Hmm... ok.. So what you're saying is that in an embedding environment nsIWindowWatcher is implemented by the host app and hence the feature string is determined by the host app? That makes sense. In that case these need to move to where? nsIDOMWindowInternal?

Practically speaking, I expect no one will ever re-implement WindowWatcher. And judging from this patch's collection of reviewers maybe I'm alone on this. But it does seem to me that the implementation of the features flags -- mostly an nsXULWindow thing -- is a feature of our browser window. I'd be inclined not to document this in the source at all, but in the developer documentation on mozilla.org. But maybe I'm thinking about this too much. This is probably a good enough place for basic documentation. I guess this is where I'd think to look for such docs if I were looking in the source. It just strikes me as a little inapplicable, is all. I would make some corrections, though. Sorry I haven't gotten around to reviewing this. For starters "centerscreen" is now a misnomer; now it works relative to the parent window. Your description of "dialog" could stand a bit more detail, even in a basic description. And there's a bunch of interaction between "dialog" and other features; "all" for instance does require "dialog". But "close" doesn't really require "dialog", does it? However it does require privileged script.

Comment on attachment 97473 [details] [diff] [review] Change how "close" is worded per how Windows implements it Yeah.. It would make sense to move this to nsIDOMWindowInternal... Thanks for the update on the inaccuracies! I mostly based this list on experimentation and reading the actual code that parses/sets these props... Hence the brevity of some descriptions -- I didn't want to specify to the point of incorrectness. I can't test close=no here, so someone testing for sure would be nice. ;) Dan, thank you very much for the feedback. I'd rather do this right, obviously. ;)

danm, would you prefer that the IDL just pointed to a mozilla.org webpage with documentation for how _our_ browser windows happen to interpret the feature string?

To default owner....

-> Danm to add corrections to patch

Regarding the patch: "scrollbars" -- controls whether scrollbars are shown" This is not perfectly accurate... A window.open with "scrollbars=yes" may not render scrollbar at all if content box does not overflow window dimensions. Often web authors assume that "scrollbars=yes" will render scrollbars all the time (and such assumption/perception is reinforceb because in MSIE 5+, the root element has the declaration overflow-y: scroll), even if not needed, like for the attribute "scrolling=yes" for frame. Previous documentation also underlined that point (link broken): Previous documentation links about windowFeature "scrollbars=yes": http://web.archive.org/web/20031204171013/http://devedge.netscape.com/library/ manuals/2000/javascript/1.3/reference/window.html#1202844 http://wp.netscape.com/eng/mozilla/3.0/handbook/javascript/ref_m-q.htm#177641

Not entirely sure what I'm supposed to do with this bug, so any guidance would be appreciated. If you're looking for a place to put related documentation at developer.mozilla.org, I believe the correct location (currently empty) would be here: http://developer.mozilla.org/en/docs/nsIWindowWatcher If I'm totally missing why this is assigned to me, let me know. If you need any help with the wiki, I'm always in IRC and happy to help out.

So it looks like Gérard Talbot documented stuff for window.open at <http://www.mozilla.org/docs/dom/domref/dom_window_ref76.html>, but unfortunately wasn't aware of this bug. In particular, some of the issues raised here (eg that "minimizable" requires "dialog") didn't make it to that documentation... I would still like to see this documented for our window watcher component somewhere, since the handling of options in window.open and the window watcher methods is not quite the same (eg window.open never has aDialog true).

> wasn't aware of this bug. I have added bug 195867 in the list of "depends on" some time ago. > (eg that "minimizable" requires "dialog") didn't make it to that > documentation... Well, I do and did mention "This setting can only apply to dialog windows." both at http://www.mozilla.org/docs/dom/domref/dom_window_ref76.html#grpWindowFunctionalitiesFeat and http://developer.mozilla.org/en/docs/DOM:window.open#Window_functionality_features To verify: http://www.gtalbot.org/BugzillaSection/MozPopupHelpTestcaseDebugger.html If you want me to make this more explicit (say: "minimizable" requires "dialog"), I'll do it. No problem, Boris.

I updated both http://www.mozilla.org/docs/dom/domref/dom_window_ref76.html#grpWindowFunctionalitiesFeat (see attachment 208904 [details] [diff] [review]) and http://developer.mozilla.org/en/docs/DOM:window.open#Window_functionality_features to explicitly indicate that minimizable requires dialog=yes. Since no link at mozilla.org goes to http://developer.mozilla.org/en/docs/Gecko_DOM_Reference anymore and because of bug 157610 , the whole mozilla documentation project (including Gecko DOM reference) is now exclusively at (and being worked/updated/developed at) http://developer.mozilla.org/ and at http://developer.mozilla.org/en/docs/Gecko_DOM_Reference At least, this is my understanding.

Gérard, thanks for clarifying that! And for writing the documentation to start with!

I guess these are now documented at https://developer.mozilla.org/en/DOM/window.open - fixed/wontfix?

That doesn't include docs for the "popup" feature (is that still supported?). Also, are you sure the features are the same for the two functions? I seem to recall that at least some of them are not passed through directly.

Oh, and at the very least the idl needs a pointer to the docs.

Marking a bunch of bugs in the "Embedding: APIs" component INCOMPLETE in preparation to archive that component. If I have done this incorrectly, please reopen the bugs and move them to a more correct component as we don't have "embedding" APIs any more.