Last Comment Bug 160443 - Document the aFeatures param of nsIWindowWatcher.openWindow
: Document the aFeatures param of nsIWindowWatcher.openWindow
: helpwanted
Product: Core
Classification: Components
Component: Embedding: APIs (show other bugs)
: Trunk
: All All
: -- normal with 1 vote (vote)
: ---
Assigned To: Nobody; OK to take it and work on it
Depends on: 195867 277798
  Show dependency treegraph
Reported: 2002-07-31 21:23 PDT by Boris Zbarsky [:bz]
Modified: 2016-06-23 10:47 PDT (History)
10 users (show)
See Also:
Crash Signature:
QA Whiteboard:
Iteration: ---
Points: ---
Has Regression Range: ---
Has STR: ---

Proposed documentation (3.03 KB, patch)
2002-07-31 21:25 PDT, Boris Zbarsky [:bz]
no flags Details | Diff | Splinter Review
Updated to review comments. (2.85 KB, patch)
2002-08-30 21:39 PDT, Boris Zbarsky [:bz]
no flags Details | Diff | Splinter Review
Change how "close" is worded per how Windows implements it (2.85 KB, patch)
2002-09-01 15:07 PDT, Boris Zbarsky [:bz]
timeless: review+
jst: superreview+
Details | Diff | Splinter Review

Description Boris Zbarsky [:bz] 2002-07-31 21:23:59 PDT
The documentation for the aFeatures param of openWindow() in
nsIWindowWatcher.idl is unsatisfactory at best...  We should document the
various features.
Comment 1 Boris Zbarsky [:bz] 2002-07-31 21:25:13 PDT
Created attachment 93523 [details] [diff] [review]
Proposed documentation

I realize the interface is frozen... but these comments change nothing in the
functionality and are _very_ useful for anyone actually using this function.
Comment 2 Christopher Aillon (sabbatical, not receiving bugmail) 2002-07-31 21:26:34 PDT
Danm should review this.
Comment 3 Boris Zbarsky [:bz] 2002-07-31 21:43:14 PDT
also need to add docs for:

width, height, left, top, outerWidth, outerHeight, screenX ( == left), screenY (
== top), innerWidth ( == width), innerHeight ( == height)
Comment 4 timeless 2002-08-01 06:32:23 PDT
'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
Comment 5 Adam Lock 2002-08-19 13:13:03 PDT
Reassign to Boris
Comment 6 Boris Zbarsky [:bz] 2002-08-30 21:39:41 PDT
Created attachment 97365 [details] [diff] [review]
Updated to review comments.
Comment 7 Boris Zbarsky [:bz] 2002-09-01 15:07:14 PDT
Created attachment 97473 [details] [diff] [review]
Change how "close" is worded per how Windows implements it
Comment 8 timeless 2002-09-24 16:06:15 PDT
Comment on attachment 97473 [details] [diff] [review]
Change how "close" is worded per how Windows implements it

>+               "popup" -- special "popup" chrome should be shown
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)
Comment 9 Boris Zbarsky [:bz] 2002-09-24 16:39:57 PDT
> 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

It's also possible that it only works for openDialog()
Comment 10 Gérard Talbot 2002-10-22 05:05:32 PDT
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 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.
Comment 11 Gérard Talbot 2002-10-22 05:14:01 PDT
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!
Comment 12 Boris Zbarsky [:bz] 2002-10-22 08:48:24 PDT
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_ but a function in nsIWindowWatcher;
the fact that 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.
Comment 13 Dan M 2002-10-22 13:47:36 PDT
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 14 Johnny Stenback (:jst, 2002-10-22 13:48:05 PDT
Comment on attachment 97473 [details] [diff] [review]
Change how "close" is worded per how Windows implements it

Comment 15 Boris Zbarsky [:bz] 2002-10-22 14:01:01 PDT
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?
Comment 16 Dan M 2002-10-22 18:10:02 PDT
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 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 17 Boris Zbarsky [:bz] 2002-10-22 18:27:26 PDT
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.  ;)
Comment 18 Boris Zbarsky [:bz] 2003-02-11 16:28:31 PST
danm, would you prefer that the IDL just pointed to a webpage with
documentation for how _our_ browser windows happen to interpret the feature string?
Comment 19 Boris Zbarsky [:bz] 2003-04-01 23:01:44 PST
To default owner....
Comment 20 Adam Lock 2003-05-15 16:31:18 PDT
-> Danm to add corrections to patch
Comment 21 Gérard Talbot 2005-01-19 22:57:36 PST
Regarding the patch:
"scrollbars" -- controls whether scrollbars are shown"
This is not perfectly accurate... A 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":
Comment 22 Deb Richardson [:dria] (plz NEEDINFO) 2005-12-21 20:01:45 PST
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, I believe the correct location (currently empty) would be here:

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.
Comment 23 Boris Zbarsky [:bz] 2006-01-18 07:45:42 PST
So it looks like Gérard Talbot documented stuff for at <>, 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 and the window watcher methods is not quite the same (eg never has aDialog true).
Comment 24 Gérard Talbot 2006-01-18 13:56:43 PST
>  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

To verify:

If you want me to make this more explicit (say: "minimizable" requires "dialog"), I'll do it. No problem, Boris.
Comment 25 Gérard Talbot 2006-01-18 15:47:39 PST
I updated both
(see attachment 208904 [details] [diff] [review])


to explicitly indicate that minimizable requires dialog=yes.

Since no link at goes to 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) and at
At least, this is my understanding.
Comment 26 Boris Zbarsky [:bz] 2006-01-18 20:08:36 PST
Gérard, thanks for clarifying that!  And for writing the documentation to start with!
Comment 27 Magnus Melin 2009-08-13 04:03:06 PDT
I guess these are now documented at - fixed/wontfix?
Comment 28 Boris Zbarsky [:bz] 2009-08-13 05:47:27 PDT
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.
Comment 29 Boris Zbarsky [:bz] 2009-08-13 05:48:02 PDT
Oh, and at the very least the idl needs a pointer to the docs.
Comment 30 Benjamin Smedberg [:bsmedberg] 2016-06-23 10:47:46 PDT
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.

Note You need to log in before you can comment on or make changes to this bug.