« XUL Reference home [ Examples | Attributes | Properties | Methods | Related ]

A box that has additional functions that can be used to scroll the content. Note that a scrollbox doesn't cause scrollbars to be displayed. It is intended to be used when an application wants to be able to adjust the scroll position itself. If you just want scrollbars to appear, add style='overflow: auto;'. This may also be used with any other container element.

Examples

The following shows the XUL for a bunch of labels. They come out in a box. If their container doesn't give enough room to hold them (geometrically) what happens depends on the enclosing elements; often the content is just clipped off on the bottom or right (depending on what's too big to fit).

<vbox>
  <label value="01 Four score and seven years ago "/>
  <label value="02 our fathers brought forth on "/>
  <label value="03 this continent, a new nation, "/>
  <label value="04 conceived in Liberty, and "/>
  <label value="05 dedicated to the proposition "/>
  <label value="06 that all men are created equal."/>
</vbox>

The next bunch of labels is similar, but if the container doesn't give enough room for it, scroll bars will sprout out of nowhere and allow the user to scroll around the big content in the small view space. For the most part, the horizontal and vertical scrollbars will independently handle too-tall and too-wide cases, but each scroll bar takes up additional width and so the appearance of one scroll bar can trigger the other one if it's close to the edge anyway. Use overflow:scroll if you want the scroll bars on all the time.

<vbox flex="1" style="overflow:auto">
  <label value="01 Four score and seven years ago "/>
  <label value="02 our fathers brought forth on "/>
  <label value="03 this continent, a new nation, "/>
  <label value="04 conceived in Liberty, and "/>
  <label value="05 dedicated to the proposition "/>
  <label value="06 that all men are created equal."/>
</vbox>

The flex="1" above may or may not be needed, or even desired. In our case an enclosing element also was overflow:auto. If the user made the window smaller, the outer box would get smaller in response and sprout its scroll bars. We wanted our vbox to get smaller and sprout its scroll bars instead.

Note that this example doesn't use a scrollbox tag; you only need that tag if you want to programmatically scroll in addition to the automatic scroll bars.

Note: avoid nested scroll boxes; it's maddening for the experienced user and confusing for the less experienced user. Instead, figure out some other way to lay things out.

Scrolling a child element into view

See element.scrollIntoView.

Prior to Gecko 19, scrollIntoView() didn't exist in XUL. Do this instead:

   var xpcomInterface =scrollbox_element.boxObject.QueryInterface(
       Components.interfaces.nsIScrollBoxObject);
   xpcomInterface.ensureElementIsVisible(child_element_to_make_visible);

 

See the nsIScrollBoxObject API for other scroll-related methods.

Attributes

Inherited from XUL element
align, allowevents, allownegativeassertions, class, coalesceduplicatearcs, collapsed, container, containment, context, contextmenu, datasources, dir, empty, equalsize, flags, flex, height, hidden, id, insertafter, insertbefore, left, maxheight, maxwidth, menu, minheight, minwidth, mousethrough, observes, ordinal, orient, pack, persist, popup, position, preference-editable, querytype, ref, removeelement, sortDirection, sortResource, sortResource2, statustext, style, template, tooltip, tooltiptext, top, uri, wait-cursor, width

Properties

Inherited Properties
align, , allowEvents, , boxObject, builder, , , , className, , , , , collapsed, contextMenu, controllers, database, datasources, dir, , , flex, height, hidden, id, , , left, , maxHeight, maxWidth, menu, minHeight, minWidth, , , , , , , observes, ordinal, orient, , pack, , persist, , , , ref, resource, , , , , statusText, style, ,, tooltip, tooltipText, top, width

Methods

Inherited Methods
addEventListener(), appendChild(), blur, click, cloneNode(), compareDocumentPosition, dispatchEvent(), doCommand, focus, getAttribute(), getAttributeNode(), getAttributeNodeNS(), getAttributeNS(), getBoundingClientRect(), getClientRects(), getElementsByAttribute, getElementsByAttributeNS, getElementsByClassName(), getElementsByTagName(), getElementsByTagNameNS(), getFeature, getUserData, hasAttribute(), hasAttributeNS(), hasAttributes(), hasChildNodes(), insertBefore(), isDefaultNamespace(), isEqualNode, isSameNode, isSupported(), lookupNamespaceURI, lookupPrefix, normalize(), querySelector(), querySelectorAll(), removeAttribute(), removeAttributeNode(), removeAttributeNS(), removeChild(), removeEventListener(), replaceChild(), setAttribute(), setAttributeNode(), setAttributeNodeNS(), setAttributeNS(), setUserData