162611 - Add convenience methods to nsIDocShell

Status: NEW

(Core :: DOM: Navigation, defect)

Description

[Aaron Leventhal]

Right now we have 5+ degrees of separation between some interfaces that there is
always a 1-1 relationship between. All the getters and QI's in Mozilla code make
it big and hard to read.

For example, to get from a dom window to a tree item, you have to go:
domwin-> domdoc-> doc-> presshell-> prescontext-> container-> docshell->treeitem

Or, to get from a docshell to a window, you have to:
docshell -> presshell -> doc -> script global object -> window

None of this stuff is documented anywhere either, and new coders are forced to
use lxr to try to get a handle on the mess. Is this a problem or not?

Why don't we add at least some of these methods:
nsIDocShell::GetDocument()
nsIDocShell::GetDOMDocument()
nsIDocShell::GetDOMWindow()
nsIDocShell::GetDOMWindowInternal()
etc.
and then a way to get an nsIDocShell from all these other objects.
In this way we could make docshell the information center and reduce everything
to 2 degrees of separation.

Something akin to, but not exactly like:
[from]
presshell  prescontext   doc  scriptglobalobject  windowinternal    esm
        \       \         |             /             /            /
                     d o c s h e l l !  
[to]    /       /         |       |            \         \       \     \     
presshell  prescontext   doc  scriptglobal  windowinternal  esm  domdoc  domwin

I realize there's not exactly a 1-1 correspondence between presshells and docs
(hence doc->GetShellAt(index, ...), but we can map this out and get it to work.

Also, there's a lot of interfaces I don't know. What else should be added to the
list? nsIDocumentViewer? nsIContentViewer? ...

Comment 1

[Aaron Leventhal]

Hmm, I would love to be able to hang on to one doc-related interface in a class
or method, and get to just about anything I need from it.

Comment 2

[Aaron Leventhal]

Would people want all these doc-related interfaces on nsIDocShell, or
nsIDocShellTreeItem?

Comment 3

[John Keiser (jkeiser)]

At the *very least* I suggest making nsIDocShellTreeNode extend
nsIDocShellTreeItem.  Better still, make nsIDocShell extend nsIDocShellTreeNode.
 I am certain the other doc-level interfaces could be organized better, but this
would be a modest step that could reduce QIs and improve readability.

Comment 4

[John Keiser (jkeiser)]

Further, "parent" items obviously have children, so those should be of type
nsIDocShellNode or even (possibly) nsIDocShell.

Comment 5

[Aaron Leventhal]

I forgot nsIViewManager.

Comment 6

[Aaron Leventhal]

jkeiser, how should we split this up.

One person could do the merging of classes and interfaces (nswebshell,
nsdocshell, nsidocshelltreenode, nsidocshelltreeitem, as you wish to do it).

Another person could add all of the new convenience getters.

Comment 7

[Johnny Stenback (:jst)]

The docshell owners should be aware of this, and they should also approve this
change before all the work is started.

Comment 8

[John Keiser (jkeiser)]

Agreed.  Not only that but we need to determine precisely which getters to put
on which class.

DocShell methods to get document, window and prescontext are reasonable. 
ScriptGlobal can be got from window PresContext methods to get 

Work I can see right now:
- review bryner's nsIPresContext patch (I'm working on this)
- deal with merging the silly TreeItem and TreeNode interfaces
- design the getters, document class relationships, add some getters

Comment 9

[Simon Fraser [no longer active]]

Doesn't GetInterface on nsIDocShell work for many of these?

Comment 10

[Aaron Leventhal]

Actually yes, but you have to QI to nsIInterfaceRequestor first.
That takes care of going from a docshell interface to lots of other things.
Perhaps we should just support GetInterface directly on nsIDocShell or
nsIDocShellTreeItem, and add a few more things that we can get.
Then we can make it really easy to get a docshell from just about anywhere, and
then we'd have our 2 degrees of separation. 

Comment 11

[John Keiser (jkeiser)]

GetInterface is rather horrid.

GetCurrentDocument(nsIDocument*) is much more descriptive--it tells you exactly
what you are getting and it gets you the result in the right form without QI'ing
either nsIDocShell or the resulting object from GetInterface (2 QI's).  It is
also more discoverable, which GetInterface() is emphatically *not*.

Perhaps there are situations in which GetInterface is good, but having real
getters as well is a must.

Comment 12

[David Bolter [:davidb] (NeedInfo me for attention)]

Mass un-assigning bugs assigned to Aaron.

Comment 13

[:Ms2ger (he/him; ⌚ UTC+1/+2)]

nsIDocument pretty much is this information center now, but without the restrictions of XPIDL.