160443 - Document the aFeatures param of nsIWindowWatcher.openWindow

Status: RESOLVED INCOMPLETE

(Core Graveyard :: Embedding: APIs, defect)

Description

[Boris Zbarsky [:bzbarsky]]

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 [:bzbarsky]]

Attachment: 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)]

Danm should review this.

Comment 3

[Boris Zbarsky [:bzbarsky]]

also need to add docs for:

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

Comment 4

[timeless]

'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]

Reassign to Boris

Comment 6

[Boris Zbarsky [:bzbarsky]]

Attachment: Updated to review comments.

Comment 7

[Boris Zbarsky [:bzbarsky]]

Attachment: Change how "close" is worded per how Windows implements it

Comment 8

[timeless]

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)

Comment 9

[Boris Zbarsky [:bzbarsky]]

> 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()

Comment 10

[Gérard Talbot]

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.

Comment 11

[Gérard Talbot]

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 [:bzbarsky]]

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.

Comment 13

[Dan M]

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)]

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

sr=jst

Comment 15

[Boris Zbarsky [:bzbarsky]]

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]

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 17

[Boris Zbarsky [:bzbarsky]]

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 [:bzbarsky]]

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?

Comment 19

[Boris Zbarsky [:bzbarsky]]

To default owner....

Comment 20

[Adam Lock]

-> Danm to add corrections to patch

Comment 21

[Gérard Talbot]

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

Comment 22

[Deb Richardson [:dria] (plz NEEDINFO)]

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.

Comment 23

[Boris Zbarsky [:bzbarsky]]

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).

Comment 24

[Gérard Talbot]

>  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.

Comment 25

[Gérard Talbot]

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.

Comment 26

[Boris Zbarsky [:bzbarsky]]

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

Comment 27

[Magnus Melin [:mkmelin]]

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

Comment 28

[Boris Zbarsky [:bzbarsky]]

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 [:bzbarsky]]

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

Comment 30

[Benjamin Smedberg]

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.