XUL:Specs:Scrolling

Current State

• Scroll events are fired, but only if attached using addEventListener.
• nsIScrollbarListener sends callbacks but there is no consumer listening to them
• scrollbox is the only element that has a API to retrieve and adjust the scroll position, yet all elements may be scrollable.

Changes

• Add onscroll event for XUL elements. May be just a matter of adding to the list in nsXULElement::IsEventHandler
• Remove nsIScrollbarListener

Element API

  /**
   * The left scroll position of the element, or 0 if the element is not
   * scrollable.
   */
  attribute long             scrollTop;

  /**
   * The top scroll position of the element, or 0 if the element is not
   * scrollable.
   */
  attribute long             scrollLeft;

  /**
   * The total scrollable height, or the content height if the element is not
   * scrollable.
   */
  readonly attribute long             scrollHeight;

  /**
   * The total scrollable width, or the content width if the element is not
   * scrollable.
   */
  readonly attribute long             scrollWidth;

  /**
   * Scrolls the element's container such that this element is visible. If top
   * is true, the view will be scrolled such that the element is placed at the
   * top of the visible area. If top is false, the view is simply scrolled
   * such that the element will be visible. In this case, if the element is
   * already visible, then the view is not scrolled at all.
   *
   *  The top argument is optional in JavaScript.
   */
  // scriptability of this method is done in nsElementSH
  void scrollIntoView(in boolean top);

  /**
   * Scroll to the given coordinates, in css pixels. The left scroll position
   * will be set to x and the top scroll position will be set to y. If either
   * value is out of range, the scroll position in that direction will be set
   * to the minimum or maximum value as necessary
   *
   * A value of 0 for both x and y will put the top left corner of the
   * scrolled element's padding-box at the top left corner of the scrollport.
   *
   * @param x the new horizontal scroll position
   * @param y the new vertical scroll position
   *
   */
  void scrollTo(in long x, in long y);

  /**
   * Scroll by the given amount of pixels. The current left position will be
   * changed by the value specified by dx, causing the view to scroll to the
   * right if dx is positive and to the left if dx is negative. The current
   * top position will be changed by the value specified by dy, causing the
   * view to scroll to downwards if dy is positive and upwards if dy is
   * negative. If either adjustment would cause the scroll position past
   * the minimum or maximum position, the view is scrolled to the minimum or
   * maximum position as necessary. 
   *
   * @param dx the horizontal scroll adjustment
   * @param dy the vertical scroll adjustment
   */
  void scrollBy(in long dx, in long dy);

  /**
   * Scroll to a given line. For most elements, this size will be the height
   * of the element's computed font. That means that if the font size changes,
   * the distance scrolled by this method will differ. Some elements, such as
   * lists and trees may have their own concept of what a line is, so this
   * method will scroll according to that definition. For example, in a tree,
   * a line is a row within the tree, so this method will scroll to a row
   * within the tree.
   *
   * If edge is true, the view is scrolled such that the line is at the edge of
   * the visible area. The actual edge used depends on the orientation and
   * direction of the element. If edge is false, the view is only scrolled if
   * the line is not already visible.
   *
   * Lines are numbered started from 0.
   *
   * @param line the line to scroll to
   * @param edge true to move line to edge of view
   */
  void scrollToLine(in unsigned long line, in boolean edge);

  /**
   * Scroll to a particular displayed child.
   *
   * @param index the index of the child to scroll to
   * @param edge true to move to edge of the displayed child
   */
  void scrollToIndex(in unsigned long index, in boolean edge);

  /**
   * Scroll by a given number of lines. See the scrollToLine method for
   * details about lines.
   *
   * @param dlines the lines adjustment
   */
  void scrollByLine(in long dlines);

  /**
   * Scroll by a given number of pages. One page is equal to the vertical size
   * of the visible area. Use a positive value to scroll down a number of pages
   * and a negative value to scroll up.
   *
   * @param dpages the number of pages to scroll
   */
  void scrollByPage(in long dpages);

  /**
   * Scroll by a given number of displayed child elements. For example, when
   * passed a value of 1, this method will scroll the view so that the next
   * displayed child after the currently displayed child is shown. When
   * determining positioning, the currently displayed child is the one with an
   * upper edge along the upper edge (or lower edge for reverse direction
   * boxes) of the scrollable container.
   *
   * Note that this scrolls using the order in which the children are
   * displayed, not the order in which the children appear in the DOM.
   * That means that hidden elements and elements not in flow do not affect
   * the indexing, and the order may be varied by the box properties.
   *
   * @param dindexes the index of the child to scroll to
   */
  void scrollByIndex(in long dindexes);