Table of Contents

theField.onScroller(scrolledField)
listener.onScroller(scrolledField)

Arguments

scrolledField

The TextField object that changed scroll position.

Description

The onScroller( ) event is triggered whenever any of the following text field properties changes: scroll, maxscroll, hscroll, or maxhscroll. It tells us that theField has been scrolled vertically or horizontally, or that theField has new content that changes its maximum vertical or horizontal scrolling range. Typically, onScroller( ) is used to synch a scrollbar interface with the content of theField. For example, if the user enters more text than will fit in a single-line text field, the text will scroll horizontally and onScroller( ) will fire, allowing code to update the width and position of a horizontal scrollbar.

The onScroller( ) event can be handled with a callback function attached to the text field. The following code registers a callback function that responds to onScroller( ). Run it in Test Movie mode and enter multiple lines of text into the field to see it work.

// Create a text field that accepts multiple lines of user input
this.createTextField("theField_txt", 1, 0, 0, 200, 20);
theField_txt.type = "input";
theField_txt.border = true;
theField_txt.multiline = true;
// Assign the onScroller() callback using a function literal
theField_txt.onScroller = function (scrolledField) {
  trace("scroll is "     + this.scroll);
  trace("maxscroll is "  + this.maxscroll);
  trace("hscroll is "    + this.hscroll);
  trace("maxhscroll is " + this.maxhscroll);
};

Notice that from the body of the callback we refer to theField_txt using the this keyword; we could also have used the scrolledField parameter.

The onScroller( ) event can also be handled by an event listener that has been added using addListener( ), as specified by listener. When using an event listener we must use the scrolledField parameter to determine which text field was scrolled. The following code registers an event listener that responds to onScroller( ):

scrollerListener = new Object();
scrollerListener.onScroller = function (scrolledField) {
  trace("scroll is "     + scrolledField.scroll);
  trace("maxscroll is "  + scrolledField.maxscroll);
  trace("hscroll is "    + scrolledField.hscroll);
  trace("maxhscroll is " + scrolledField.maxhscroll);
};
theField_txt.addListener(scrollerListener);

Using a callback function is simpler, but it allows only a single function to respond to the event. Any number of listener objects can respond to a single event. To stop a callback from handling the onScroller( ) event, use the delete operator, as in:

// Make sure to omit the () operator after the function name!
delete theField_txt.onScroller;

To stop a listener from handling the onScroller( ) event, use removeListener( ), as in:

theField_txt.removeListener(scrollerListener);

Usage

Note that simply clicking in a text field causes onScroller( ) to fire.

Bugs

In Flash 6, when a text field's scroll or hscroll properties are set on the same frame as the creation of the field, onScroller( ) is not triggered. Even when those properties are set on the frame after the creation of the field, onScroller( ) may not execute:

// Create a text field.
this.createTextField("theField_txt", 1, 0, 0, 200, 40);
theField_txt.text = "a\nb\nc\nd\ne\nf\ng\nh\ni\nj\nk\nl\nn\nm\no\np";
// Assign the onScroller() callback.
theField_txt.onScroller = function (scrolledField) {
  trace("scroll is " + this.scroll);
  trace("maxscroll is " + this.maxscroll);
};
// Scroll the field. onScroller() will not execute.
theField_txt.scroll = 4;

To force the onScroller( ) event handler to execute, invoke it manually, as in:

theField_txt.onScroller();

Unfortunately, there is no easy way to force all onScroller( ) listeners to execute manually. (You'd have to keep a list of all listeners and execute the onScroller( ) method of each individually.)

Example

The following code detects when theField_txt has been scrolled all the way to the bottom:

theField_txt.onScroller = function (scrolledField) {
  if (this.scroll =  = this.maxScroll) {
    trace("End of field reached.");
  }
}

See Also

TextField.addListener( ), TextField.hscroll, TextField.maxhscroll, TextField.maxscroll, TextField.removeListener( ), TextField.scroll; Chapter 10; the FScrollBar component in Appendix G

Table of Contents