Spinner Model and Controller Classes

Table of Contents

Markup Tutorial

Interfacing with Java™

Web Services

Spinner

Month Spinner

Spinner Model and Controller Classes

This section shows how the spinner model and controller classes are implemented. It is intended for Java™ developers, and requires a good understanding of Java interfaces.

A spinner and its supporting objects are shown in the following illustration:

Action Listener

The spinner is controlled by an action listener that is loosely coupled to a model that maintains the spinner’s value. The controller has no direct association with any view. Loose coupling is achieved by making the controller refer to the model, not through the text model’s class, but through the com.enode.xalt.Sequence interface described next.

The com.enode.xalt.Sequence interface captures the essential properties of a spinner’s model, and the operations that may be performed on it. The interface also declares methods required to support event listeners for user-defined event notifications. You may use this interface as-is, or treat this as a model for defining your own interface.

package com.enode.xalt;

import com.enode.xalt.SequenceChangeListener;

public interface Sequence {
    public void increment();
    public void decrement();
    public void setValue(Object value);
    public Object getValue();
    public Object getPreviousValue();
    public Object getNextValue();

    // Event listener support for user-defined event
    public void addSequenceChangeListener(SequenceChangeListener listener);
    public void removeSequenceChangeListener(SequenceChangeListener listener);

    // Constants for "change type" used in sequenceChanged() notifications
    public final static int INCREMENT = 1;  // sequence changed via increment
    public final static int DECREMENT = -1; // sequence changed via decrement
    public final static int SET  = 0;       // sequence changed via setValue
}

Note that this interface works for sequences of any type, not just numbers.

The action listener is implemented as a JavaBean™ class called com.enode.xalt.Sequencer. The bean class defines a single property called sequence, as evidenced by the presence of conforming bean property methods setSequence() and getSequence(). As usual, you can use this class as an example for defining your own action listener, or you may choose to use it as-is.

package com.enode.xalt;

import java.awt.event.ActionEvent;
import com.enode.xalt.Sequence;

public class Sequencer implements java.awt.event.ActionListener {
    public Sequencer() {
        // Java beans must have a zero-argument constructor
    }

    // "sequence" property setter
    public void setSequence(Sequence seq) {
        sequence = seq;
    }

    // "sequence" property getter
    public Sequence getSequence() {
        return sequence;
    }

    public void increment(ActionEvent event) {
        sequence.increment();
    }

    public void decrement(ActionEvent event) {
        sequence.decrement();
    }

    public void actionPerformed(ActionEvent event) {
        System.out.println("No action performed by " + getClass());
    }

    private Sequence  sequence = null;
}

The increment() and decrement() methods have the same return type and argument list as the actionPerformed() method declared by the java.awt.event.ActionListener interface. If you associate either of these methods with a trampoline using the method attribute of an action element, eNode Object Realizer will invoke the named method in lieu of the generic actionPerformed() method. This allows us to use a single action listener object to handle action events from multiple sources, without having to decode the source of the action event inside the action listener.

That is all there is to the definition of the action listener class. Because of its design, this class can easily be reused in other unrelated situations, such as cycling through items in a combo box.

Spinner Text Model

As previously mentioned, the spinner and the text field share the same model — Rather than use a separate object for the spinner’s model, we adapt the text field’s model to implement the spinner’s model. That way, whenever the value maintained by the spinner’s model changes, the text field’s model also shows an identical change — after all, they are the same object!

The com.enode.xalt.Sequence interface declares methods that define one read-write property called value and two read-only properties called previousValue and nextValue. We want our spinner model to support a bounded sequence where the “step” size as well as the maximum and minimum for the sequence can be specified. So, we extend the existing interface by adding three new read-write properties, as follows:

package com.enode;

public interface BoundedSequence extends com.enode.xalt.Sequence {
    public void setMaximum(Object maximum); // maximum value of the sequence
    public Object getMaximum();             // maximum value of the sequence
    
    public void setMinimum(Object minimum); // minimum value of the sequence
    public Object getMinimum();             // minimum value of the sequence
    
    public void setStepSize(Object stepSize);// step size for the sequence
    public Object getStepSize();            // step size for the sequence
}

We define our text model class by extending javax.swing.text.PlainDocument (which is the default model class for a text field), and implementing the com.enode.BoundedSequence interface. We call this class com.enode.xalt.IntegerTextModel because we envision that it will be used to store integer values only.

The properties maximum and minimum define the range within which the spinner’s value is bounded. If either or both of these are not set, the corresponding end of the range is unbounded. The default value of the stepSize property is one, but it can be set to any integer value that indicates the amount by which the spinner’s value should change during a single increment or decrement. A negative value will cause increment() to decrease the value of the spinner by the absolute value of the stepSize property.

The listing for com.enode.xalt.IntegerTextModel is shown below. The code is straightforward and should be self-explanatory.

package com.enode.xalt;

import com.enode.xalt.SequenceChangeEvent;
import com.enode.xalt.SequenceChangeListener;

public class IntegerTextModel extends javax.swing.text.PlainDocument
                              implements com.enode.xalt.BoundedSequence {
    public IntegerTextModel() {
        setValue(value);
    }

    public void increment() {
        changeSequence(getNextValue(), INCREMENT);
    }

    public void decrement() {
        changeSequence(getPreviousValue(), DECREMENT);
    }

    public void setValue(Object val) {
        changeSequence(val, SET);
    }

    public Object getValue() {
        return value;
    }

    public Object getPreviousValue() {
        int newValue = value.intValue() - stepSize;
        if ((minimum != null) && (newValue < minimum.intValue())) {
            newValue = minimum.intValue();  // pin to minimum
        }
        return new Integer(newValue);
    }

    public Object getNextValue() {
        int newValue = value.intValue() + stepSize;
        if ((maximum != null) && (newValue > maximum.intValue())) {
            newValue = maximum.intValue();  // pin to maximum
        }
        return new Integer(newValue);
    }

    public void setMinimum(Object min) {
        try {
            if (min != null) {
                minimum = (Number) min;
                setValue(value);    // calibrate value to new minimum
            }
        }
        catch (Exception ex) {
            // Do nothing
        }
    }

    public Object getMinimum() {
        return minimum;
    }

    public void setMaximum(Object max) {
        try {
            if (max != null) {
                maximum = (Number) max;
                setValue(value);    // calibrate value to new maximum
            }
        }
        catch (Exception ex) {
            // Do nothing
        }
    }

    public Object getMaximum() {
        return maximum;
    }

    public void setStepSize(Object size) {
        try {
            if (size != null)
                stepSize = ((Number) size).intValue();
        }
        catch (Exception ex) {
            // Do nothing
        }
    }

    public Object getStepSize() {
        return new Integer(stepSize);
    }

    private void changeSequence(Object val, int changeType) {
        try {
            int newValue = ((Number) val).intValue();

            if ((minimum != null) && (newValue < minimum.intValue())) {
                newValue = minimum.intValue();  // pin to minimum
            }
            if ((maximum != null) && (newValue > maximum.intValue())) {
                newValue = maximum.intValue();  // pin to maximum
            }

            if (newValue != value.intValue()) {
                value = new Integer(newValue);
                updateTextModel();
                fireSequenceChanged(changeType);
            }
        }
        catch (ClassCastException ex) {
            // Do nothing
        }
    }

    private void updateTextModel() {
        try {
            remove(0, getLength());
            insertString(0, value.toString(), null);
        }
        catch (Exception ex) {
            // Do Nothing
        }
    }

    // Stereotypical code for event listener support.
    // See documentation for javax.swing.event.EventListenerList

    public void addSequenceChangeListener(SequenceChangeListener listener) {
        listenerList.add(SequenceChangeListener.class, listener);
    }

    public void removeSequenceChangeListener(SequenceChangeListener listener) {
        listenerList.remove(SequenceChangeListener.class, listener);
    }

    // Notify all listeners that have registered interest for
    // notification on this event type.  The event instance
    // is lazily created using the parameters passed into
    // the fire method.

    protected void fireSequenceChanged(int changeType) {
        // Guaranteed to return a non-null array
        Object[] listeners = listenerList.getListenerList();
        // Process the listeners last to first, notifying
        // those that are interested in this event
        for (int i = listeners.length-2; i>=0; i-=2) {
            if (listeners[i]==SequenceChangeListener.class) {
                if (event == null) {  // Lazily create the event:
                    event = new SequenceChangeEvent(this);
                }
                event.setChangeType(changeType);
                ((SequenceChangeListener)listeners[i+1]).sequenceChanged(event);
            }
        }
    }

    private SequenceChangeEvent event = null;
    private Number              minimum = null;
    private Number              maximum = null;
    private Number              value = new Integer(0);
    private int                 stepSize = 1;
}

Notice that our spinner model implements com.enode.BoundedSequence, but the action listener does not need to know about the additional properties. So, com.enode.xalt.Sequencer continues to refer to the model through the more general interface com.enode.xalt.Sequence.

User-Defined Events

Whenever the value of the spinner is changed, the spinner model fires a user-defined event called com.enode.xalt.SequenceChangeEvent. Event firing is a straightforward process that requires stereotypical code for setting up the necessary infrastructure. Refer to the documentation of javax.swing.event.EventListenerList for details.

Here, the events infrastructure depends on the com.enode.xalt.SequenceChangeListener interface, which declares a single method called sequenceChanged(), as shown below.

package com.enode.xalt;

public interface SequenceChangeListener extends java.util.EventListener {
    public void sequenceChanged(com.enode.xalt.SequenceChangeEvent event);
}

The listsing for com.enode.xalt.SequenceChangeEvent is shown below.

package com.enode.xalt;

import com.enode.xalt.Sequence;

public class SequenceChangeEvent extends javax.swing.event.ChangeEvent {
    // Not a Java bean, because it does not have a zero-argument constructor
    public SequenceChangeEvent(Object source) {
        super(source);
    }

    public void setChangeType(int type) {
        switch (type) {
            case Sequence.INCREMENT:
            case Sequence.DECREMENT:
            case Sequence.SET:
                changeType = type;
                break;
            default:
                throw new IllegalArgumentException("Invalid change type");
        }
    }

    public int getChangeType() {
        return changeType;
    }

    private int changeType = Sequence.SET;   // default change type
}

Whenever the spinner’s value changes, it fires a SequenceChangeEvent that can be intercepted by an object that implements the SequenceChangeListener interface. Upon notification, the listener can query the event to determine how the sequence changed. It can also query the event source, which, in this case, is the spinner model, to determine the current value of the sequence.

In this example, however, we do not use the sequenceChanged() notification, relying instead on the trampoline mechanism to invoke increment() or decrement(), as appropriate.