196779 - Scroll position element properties not documented

Status: RESOLVED WORKSFORME

(Documentation Graveyard :: Web Developer, defect)

Description

[Ernest Cline]

User-Agent:       Mozilla/5.0 (Windows; U; Win98; en-US; rv:1.2.1) Gecko/20021130
Build Identifier: Mozilla/5.0 (Windows; U; Win98; en-US; rv:1.2.1) Gecko/20021130

The following DOM Level 0 Element properties are not documented, altho they are
in Mozilla.
element.clientHeight
element.clientWidth
element.scrollHeight
element.scrollLeft
element.scrollTop
element.scrollWidth

Reproducible: Always

Steps to Reproduce:
1. Go to the documentation.
2. Look for these properties.


Actual Results:  
No such properties to be found.

Expected Results:  
These properties, which Mozilla does implement should be documented.

Comment 1

[rudman]

-->oeschger.

Comment 2

[Ian Oeschger (gone)]

moving stuff over to an outside-the-firewall email for the time being, looking
for people to pick these Help and doc bugs up for me.

Comment 3

[Daniel Wang]

-> Doron

Comment 4

[Gérard Talbot]

Assigning to me 

Comment 5

[Gérard Talbot]

Here are the references I intend to use for this bug:

http://bugzilla.mozilla.org/show_bug.cgi?id=62536#c109

http://www10.brinkster.com/doctorunclear/HTMLJavascriptCSS/DUWindowsNS6.html

http://www.quirksmode.org/viewport/compatibility.html

http://msdn.microsoft.com/workshop/author/om/measuring.asp

http://www10.brinkster.com/doctorunclear/BrowserBugsSection/MozillaBugs/Bug189308_ScrollEvent.html

                               / Top
                   / client   /  Left
elementReference. /  offset  /   Width
                  \  scroll  \   Height

are often and more widely referred as the DHTML object model properties in books
and references: they originally come from MSDN. window.pageXOffset and
window.pageYOffset came from NS. offsetParent will need to be defined as well.

Interactive examples and instructional image showing the measurements,
illustrating the concepts will be needed to make these pages as useful and
recommendable as they can be.

Another idea is to create a cross-browser interactive demo page like
http://msdn.microsoft.com/workshop/samples/author/css/overview/interactivemeasurement.htm

Comment 6

[Gérard Talbot]

oops, I meant
https://bugzilla.mozilla.org/show_bug.cgi?id=62536#c101 not c109
and here, scrollWidth and scrollHeight definitions need to be more accurate.

Comment 7

[Gérard Talbot]

scrollWidth, scrollHeight: it is the width/height of the content of an element
according/related to/given for a certain height/width of such element's
viewport. What I mean by this is that if the element height/width is reduced or
increased (while its content remains the same), its scrollWidth/scrollHeight
will be reverse-proportionally increased. I will just add this as a note to the
definition though.

clientWidth, clientHeight. This the width/height of the element's viewport. E.g.
for clientWidth, this equates to offsetWidth - border-left-width -
border-right-width - width of vertical scroll bar (if present). clientWidth,
clientHeight include the padding of the element.

Comment 8

[Gérard Talbot]

Attachment: Basic CSS and DHTML page

I use this page to create the upcoming images

Comment 9

[Gérard Talbot]

Attachment: CSS width

Comment 10

[Gérard Talbot]

Attachment: DHTML clientWidth

Comment 11

[Gérard Talbot]

Attachment: DHTML offsetWidth

Comment 12

[Gérard Talbot]

Attachment: CSS height

Comment 13

[Gérard Talbot]

Attachment: DHTML clientHeight

Comment 14

[Gérard Talbot]

Attachment: DHTML offsetHeight

Comment 15

[Gérard Talbot]

Attachment: DHTML clientLeft

If the element has a vertical scrollbar and if the text direction is rtl, then
clientLeft property must include the width of the vertical scrollbar.

Comment 16

[Gérard Talbot]

Attachment: DHTML clientTop

Comment 17

[Gérard Talbot]

Attachment: DHTML clientHeight (with vertical scrollbar)

Comment 18

[Gérard Talbot]

Attachment: DHTML clientWidth (with vertical scrollbar)

Comment 19

[Gérard Talbot]

Attachment: DHTML offsetHeight (with vertical scrollbar)

Comment 20

[Gérard Talbot]

Attachment: DHTML offsetWidth (with vertical scrollbar)

Comment 21

[Gérard Talbot]

Attachment: DHTML scrollHeight

Comment 22

[Gérard Talbot]

Attachment: DHTML scrollTop

Comment 23

[Gérard Talbot]

Attachment: Birman cat image

Comment 24

[Gérard Talbot]

Attachment: Web page serving as demo

Comment 25

[Gérard Talbot]

Attachment: Web page serving to create images or serving as demo

Comment 26

[Gérard Talbot]

Attachment: DHTML scrollHeight (better)

Comment 27

[Gérard Talbot]

Attachment: DHTML scrollTop (better)

Comment 28

[Gérard Talbot]

Attachment: Interactive and instructional demo on DHTML scrollTop property

This is just one single example of how each of the 

			       / Top
		   / client   /  Left
elementReference. /  offset  /	 Width
		  \  scroll  \	 Height , window.pageXOffset,
window.pageYOffset

could be explained, demonstrated, defined and measured in an HTML document for
best instructional purposes.

The image on the right shows in a static manner the visual representation of
the property.
The div on the left shows an interactive demo of the property.
Not included is the strict textual definition of that scrollTop property with
details (type, value, compatibility support, etc.). 
Note that this demo works in MSIE 6 and also works (or should work) in Opera
7.60 PR3.

Comment 29

[Gérard Talbot]

Attachment: Interactive and instructional demo on DHTML scrollTop property

(Please ignore previous attachment)

This is just one single example of how each of the 

			       / Top
		   / client   /  Left
elementReference. /  offset  /	 Width
		  \  scroll  \	 Height , window.pageXOffset,
window.pageYOffset

could be explained, demonstrated, defined and measured in an HTML document for
best instructional purposes.

The image on the right shows in a static manner the visual representation of
the property.
The div on the left shows an interactive demo of the property.
Not included is the strict textual definition of that scrollTop property with
details (type, value, compatibility support, etc.). 
Note that this demo works in MSIE 6 and also works (or should work) in Opera
7.60 PR3.

Comment 30

[Gérard Talbot]

I've created a meta interactive demo page of what I've done so far. 

http://www.gtalbot.org/Bugzilla/DocumentAllDHTMLproperties.html

The pages for each property would be created with the individual images. There
are several other possible improvements to such meta page and then they can be
transferred, reused in the Gecko DOM Reference pages. 

I think I'll need to redo all the images that involve height since the *Height
images so far do not show any horizontal scrollbar. This is important since
offsetHeight include such scrollbar while clientHeight and scrollHeight exclude
it. I may need to redo all the images anyway for several reasons (consistent
look, way of presenting info, reproducible value and functioning with live
example) and that's the long part. Best is to start with a real existing div
with content so that the info in a static image can be achieved, reproduced with
a real, live, existing <div>.

I don't know when I'll be able to do all the pages involved into this bugfile:
right now, it maybe more than 20 pages since the root element implements some of
those DHTML object model properties differently in MSIE and Mozilla. Note that
there are also window.scrollX, window.scrollY to cover and also offsetLeft,
offsetTop, offsetParent. Right now, my wish would be to fix all this before
march 30th 2005 or so.

I think these new Gecko DOM reference pages (to be created individually) should
be able to convey without javascript useful, meaningful and trustworty
definitions, information about these properties *and* should offer a small
interactive javascript-driven demo, instructional example. If an image is worth
a thousand words, on the web, a good interactive demo is worth a thousand words
and images, I'd say.

I need to document also the bugs which affect the value of such properties and
how they affect these. For instance, rendering of padding-bottom in bug 47710.

Comment 31

[Gérard Talbot]

I uploaded a first document on my site and have requested a review, comments,
feedback:

http://www.gtalbot.org/Bugzilla/OffsetHeight.html

Comment 32

[Erik Arvidsson]

I've read through this bug and the linked/attached test cases and they all look
fine to me.

Comment 33

[Gérard Talbot]

I have made some corrections (tweaking, tuning, corrections) to
http://www.gtalbot.org/Bugzilla/OffsetHeight.html
and also uploaded
http://www.gtalbot.org/Bugzilla/OffsetWidth.html
http://www.gtalbot.org/Bugzilla/ClientHeight.html
http://www.gtalbot.org/Bugzilla/ClientWidth.html

Doron: are these files ok for GDR?

Comment 34

[Gérard Talbot]

http://www.gtalbot.org/Bugzilla/ScrollHeight.html
http://www.gtalbot.org/Bugzilla/ScrollTop.html
have been added.

I will remove all inline-style and edit css declarations in the <head> section
later.

Comment 35

[Erik Arvidsson]

"...relative to the layout or relative to its offsetParent."

The size (offsetWidth, offsetHeight) is not really relative to the offsetParent.
As a matter of fact there is really no connection between the offsetWidth/Height
and the offsetParent.

I also think that the paragraph with -moz-box-sizing is a bit confusing and I'm
not sure that this paragraph helps people understand and use offset*

clientWidth/Height is often referred to as inner width/height or viewport
width/height. The first sentence in both these are a bit cryptic. A better
alternative (IMHO):

DHTML property that represents the inner height of an element. This includes
possible padding but not scrollbar, border nor margin.

Comment 36

[Gérard Talbot]

> The size (offsetWidth, offsetHeight) is not really relative to the offsetParent.

Agreed! I removed reference to offsetParent. Strangely enough, MSDN mentions
that offsetWidth/Height is relative to offsetParent. <shrug>

> I also think that the paragraph with -moz-box-sizing is a bit confusing and I'm
> not sure that this paragraph helps people understand and use offset*

Agreed! Removals done.

> clientWidth/Height is often referred to as inner width/height or viewport
> width/height. The first sentence in both these are a bit cryptic. 

Regarding clientWidth/Height, there is actually a bug in MSIE which Opera and
Mozilla browsers are duplicating, reproducing and it makes the definition
painful to do.

clientWidth could be narrower than the css width and I've tried to render such
possibility in the definition. Anyway, I made some changes in the definitions.

Comment 37

[Gérard Talbot]

Attachment: Patch for offsetHeight; revision 1.34 (checked in)

The offsetHeight file is:

http://www.mozilla.org/docs/dom/domref/dom_el_ref18.html

- Converted to HTML 4.01 strict
- removed some 40 markup errors
- everything was upgraded and updated: definition, description, example,
illustration, notes, references, links, etc.

Many thanks to Fantasai for her assistance for the file uploads

Comment 38

[Gérard Talbot]

Attachment: Patch for offsetWidth; revision 1.34 (checked in)

The file is:

http://www.mozilla.org/docs/dom/domref/dom_el_ref22.html

- Converted to HTML 4.01 strict
- removed some 37 markup errors in HTML 3.2
- everything was upgraded and updated: definition, description, example,
illustration, notes, references, links, etc.

Comment 39

[Gérard Talbot]

Attachment: Patch for clientHeight; revision 1.2 (checked in)

http://www.mozilla.org/docs/dom/domref/clientHeight.html

Many thanks to Fantasai for uploading the file. I re-edited the path of links
and path of images in this patch.

To do: reposition the offsetContainer

Comment 40

[Gérard Talbot]

Attachment: Patch for clientWidth; revision 1.2 (checked in)

Many thanks to Fantasai :) for uploading the first patch.

http://www.mozilla.org/docs/dom/domref/clientWidth.html

Re-edited path of links and path of images in the patch.

To do: reposition the offsetContainer accordingly

Comment 41

[Gérard Talbot]

Attachment: Patch for scrollHeight; revision 1.2 (checked in)

Many thanks to Fantasai :) for uploading the first patch.

http://www.mozilla.org/docs/dom/domref/scrollHeight.html

Re-edited path of the links and path of images in the patch.

To do: adjust the position of offsetContainer accordingly.

Comment 42

[Gérard Talbot]

Attachment: Patch for scrollHeight; revision 1.2 (checked in)

Many thanks to Fantasai for uploading the first patch.

http://www.mozilla.org/docs/dom/domref/scrollTop.html

Re-edited path of links and path of images in the patch.

To do: correct the position of offsetContainer, the form and to initialize the
event listeners accordingly once the page has loaded.

Comment 43

[Gérard Talbot]

Today, I got formal approval from Larry Chamberlain of www.best-cat-art.com/ to
include the Birman cat image and its related text description in the example
sections of all DHTML object model properties pages. Larry asked for a link back
to his page and I agreed. So, I updated accordingly each/all of the following pages:

http://www.mozilla.org/docs/dom/domref/clientHeight.html
http://www.mozilla.org/docs/dom/domref/clientWidth.html
http://www.mozilla.org/docs/dom/domref/dom_el_ref18.html
http://www.mozilla.org/docs/dom/domref/dom_el_ref22.html
http://www.mozilla.org/docs/dom/domref/scrollHeight.html
http://www.mozilla.org/docs/dom/domref/scrollTop.html

and

http://developer.mozilla.org/en/docs/DOM:element.clientHeight
http://developer.mozilla.org/en/docs/DOM:element.clientWidth
http://developer.mozilla.org/en/docs/DOM:element.offsetHeight
http://developer.mozilla.org/en/docs/DOM:element.offsetWidth
http://developer.mozilla.org/en/docs/DOM:element.scrollHeight
http://developer.mozilla.org/en/docs/DOM:element.scrollTop

and I will eventually update the scrollHeight.png and scrollTop.png images where
they are used. Eventually, I will use the Birman cat image and related text
description in other DHTML object properties pages 

(to do: clientLeft [lrt and rtl versions], clientTop, offsetLeft, offsetTop,
offsetParent, scrollLeft, scrollWidth and possibly window.pageXOffset,
window.pageYOffset, window.scrollX, window.scrollY,
document.documentElement.scrollLeft, document.documentElement.scrollTop, etc.).

Thank you, Larry :)

Comment 44

[Gérard Talbot]

> I will eventually update the scrollHeight.png and scrollTop.png images where
> they are used.

Done at: 

http://developer.mozilla.org/en/docs/DOM:element.scrollHeight
http://developer.mozilla.org/en/docs/DOM:element.scrollTop

Comment 45

[Gérard Talbot]

Ernest,

the Gecko DOM Reference is now/has migrated at Mozilla Developer Center. So, it makes no more sense to have a bugzilla file opened for documenting DHTML properties. Anyone, including yourself, can update the files, the properties not defined so far (scrollLeft, offsetTop, offsetLeft, offsetParent, window.pageXOffset and window.pageYOffset) at MDC.

So, I'm resolving this bug as WORKSFORME