Text Components and Editors

You have a text component on the screen, and you want your program to react whenever the text in it changes. You write a listener, attach it, and nothing happens. The window looks fine, and the code looks reasonable, so where should you start looking? This article answers that question by showing that a text component is not the object that holds the text. Behind the component sits a separate object, and a listener attached in the wrong place will never hear about the changes you care about.

The lesson's trace keeps one question in mind as you follow the code: where does the text component keep the information it is responsible for? The screen shows a text component, but the trace is designed to make you look past the screen to the object behind it. Keep that question in mind as we go.

The two objects have distinct jobs. The component handles what appears on screen and how the user interacts with it. The Document holds the model, which is the object the component depends on for its text. This separation is the heart of the model-view-controller idea that this chapter builds on. The practical consequence is simple: if you want to observe the text itself, rather than the component that displays it, you need a way to reach the Document.

The diagram shows the containment in one direction: the component you see is paired with the Document it depends on. Read the arrow as reliance, not as a claim about every internal detail of the component. Your job when reasoning about a listener is to remember that the text lives in the Document, and the component is the view of it.

The source gives one line for attaching a listener. It is worth reading slowly, because the line is a chain of three steps, and each step operates on a different object.

The first part names the text component. The second part, getDocument(), is called on that component and hands back its Document. The third part, addDocumentListener(listener), is called on the returned Document, not on the component. The order of the chain is the key detail. The chain first moves from the component to its model, and only then registers the listener. A listener attached this way is attached to the model, which is why the source describes it as a way to be notified of changes in the model.

Now trace the registration as a sequence of messages between the objects involved. Your code starts the process, the component supplies its model, the model receives the registration, and later the model notifies the listener when a change happens. Notice that the component never receives the listener in this path.

Read the diagram from top to bottom. Messages 1 and 2 retrieve the model. Message 3 is the registration, and it lands on the Document. Message 4 is the notification path: once a change happens in the model, the Document notifies the listeners attached to it, and the listener's own code then runs. The source describes this path at the level of which object is notified, so treat the notification step as the link to verify when you debug, rather than assuming any particular callback names.

When a listener does not react, do not guess at the whole program. Split the chain into its three steps and check each one. The first step where your expectation and the actual object disagree is the place to investigate. A listener that seems silent usually comes down to one question: at which step did the program stop doing what you expected? That step might be fetching the right object, registering the listener, or the change itself.