Document the aFeatures param of nsIWindowWatcher.openWindow




17 years ago
3 years ago


(Reporter: bzbarsky, Unassigned)



Dependency tree / graph

Firefox Tracking Flags

(Not tracked)



(2 attachments, 1 obsolete attachment)

The documentation for the aFeatures param of openWindow() in
nsIWindowWatcher.idl is unsatisfactory at best...  We should document the
various features.
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.
Danm should review this.
also need to add docs for:

width, height, left, top, outerWidth, outerHeight, screenX ( == left), screenY (
== top), innerWidth ( == width), innerHeight ( == height)

Comment 4

17 years ago
'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

17 years ago
Reassign to Boris
Assignee: adamlock → bzbarsky
Created attachment 97365 [details] [diff] [review]
Updated to review comments.
Attachment #93523 - Attachment is obsolete: true
Created attachment 97473 [details] [diff] [review]
Change how "close" is worded per how Windows implements it

Comment 8

17 years ago
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)
Attachment #97473 - Flags: review+
> 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

17 years ago
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

17 years ago
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_ 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.
Priority: -- → P1
Summary: Document the aFeatures param of nsIWindowWatcher.openWindow → [FIX]Document the aFeatures param of nsIWindowWatcher.openWindow
Target Milestone: --- → mozilla1.2final

Comment 13

17 years ago
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

Attachment #97473 - Flags: superreview+
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

17 years ago
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 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.  ;)
Attachment #97473 - Flags: needs-work+


17 years ago
Target Milestone: mozilla1.2final → mozilla1.3beta
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?
Target Milestone: mozilla1.3beta → mozilla1.4beta
To default owner....
Assignee: bzbarsky → adamlock
OS: Linux → All
Priority: P1 → --
QA Contact: mdunn → carosendahl
Hardware: PC → All
Target Milestone: mozilla1.4beta → ---

Comment 20

16 years ago
-> Danm to add corrections to patch
Assignee: adamlock → danm


14 years ago
Depends on: 277798


14 years ago
Depends on: 195867

Comment 21

14 years ago
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":


14 years ago
Assignee: danm.moz → nobody


14 years ago
Keywords: helpwanted
Summary: [FIX]Document the aFeatures param of nsIWindowWatcher.openWindow → Document the aFeatures param of nsIWindowWatcher.openWindow


13 years ago
Assignee: nobody → deb
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.
Assignee: deb → adamlock
QA Contact: carosendahl
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

13 years ago
>  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

13 years ago
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.
Gérard, thanks for clarifying that!  And for writing the documentation to start with!
I guess these are now documented at - fixed/wontfix?
Assignee: adamlock → nobody
QA Contact: apis
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.
Last Resolved: 3 years ago
Resolution: --- → INCOMPLETE
You need to log in before you can comment on or make changes to this bug.