A Subject notifies its Observer when something changes in the Subject. This can be a change in the value of a Parameter, or the occurrence of a GenericEvent. The Subject maintains a list of its Observers. An Observer is connected to the Subject via the addObserver method, which is typically called by the Observer's constructor or the entity that creates the Observer.

See Subject, Observer, Parameter for an overview. The Subject and Observer interfaces are an implementation of the Observer design pattern.

When a change occurs in the Subject, the broadcast method should be called to inform all Observers of the change. For a Parameter, the "setter" method of the Subject should call broadcastParameter at the end of the setter method.

Language-Independent Names

To enable scripting, we need Parameters and SubjectEvents to have language independent names. Therefore Parameter.getName() and SubjectEvent.getName() return a language independent name which is derived from the English localized name by converting the English name to uppercase and replacing spaces and dashes by underscore.

You can use the function Util.toName to convert an English name to the language-independent name. Or use SubjectEvent.nameEquals() which handles the conversion to language independent name.

See Internationalization for more about localized and language-independent strings.

Example Scenario

Here is an example usage of the Subject and Observer interfaces, along with Parameters and user interface controls.

Subject/Observer Relationships with Parameters

The diagram shows a ContactSim as the Subject. It has a list of Parameters, including a Parameter representing the distance tolerance which determines when objects are in contact. The Subject also has a list of Observers, including a NumericControl which is connected to the distance tolerance ParameterNumber. In its constructor, the NumericControl adds itself to the list of Observers by calling addObserver on the Subject of the ParameterNumber.

Whenever the distance tolerance is changed, the Subject should notify each Observer by calling broadcast. The Observer can then get the current value by calling ParameterNumber.getValue.

This design is very decoupled. The Subject knows nothing about the NumericControl except that it is an Observer. The Parameter is unaware of the NumericControl. The NumericControl only knows about the ParameterNumber and that it has a Subject which will provide notification of changes.

interface Subject {
    addObserver(observer): void;
    broadcast(evt): void;
    broadcastParameter(name): void;
    getName(): string;
    getObservers(): Observer[];
    getParameter(name): Parameter;
    getParameterBoolean(name): ParameterBoolean;
    getParameterNumber(name): ParameterNumber;
    getParameterString(name): ParameterString;
    getParameters(): Parameter[];
    removeObserver(observer): void;
    toStringShort(): string;
}

Hierarchy (view full)

Implemented by

Methods

  • Adds the given Observer to this Subject's list of Observers, so that the Observer will be notified of changes in this Subject. An Observer may call Subject.addObserver during its observe method.

    Parameters

    Returns void

  • Notifies all Observers that the Parameter with the given name has changed by calling observe on each Observer.

    Parameters

    • name: string

      the language-independent or English name of the Parameter that has changed

    Returns void

    Throws

    if there is no Parameter with the given name

  • Return the language-independent name of this Subject for scripting purposes.

    Returns string

    name the language-independent name of this Subject

  • Returns the Parameter with the given name.

    Parameters

    • name: string

      the language-independent or English name of the Parameter

    Returns Parameter

    the Parameter with the given name

    Throws

    if there is no Parameter with the given name

  • Returns the ParameterBoolean with the given name.

    Parameters

    • name: string

      the language-independent or English name of the ParameterBoolean

    Returns ParameterBoolean

    the ParameterBoolean with the given name

    Throws

    if there is no ParameterBoolean with the given name

  • Returns the ParameterNumber with the given name.

    Parameters

    • name: string

      the language-independent or English name of the ParameterNumber

    Returns ParameterNumber

    the ParameterNumber with the given name

    Throws

    if there is no ParameterNumber with the given name

  • Returns the ParameterString with the given name.

    Parameters

    • name: string

      the language-independent or English name of the ParameterString

    Returns ParameterString

    the ParameterString with the given name

    Throws

    if there is no ParameterString with the given name

  • Returns a copy of the list of this Subject's available Parameters.

    Returns Parameter[]

    a copy of the list of available Parameters for this Subject

  • Removes the Observer from this Subject's list of Observers. An Observer may call removeObserver during its observe method.

    Parameters

    • observer: Observer

      the Observer to detach from list of Observers

    Returns void

  • Returns a minimal string representation of this object, usually giving just identity information like the class name and name of the object.

    For an object whose main purpose is to represent another Printable object, it is recommended to include the result of calling toStringShort on that other object. For example, calling toStringShort() on a DisplayShape might return something like this:

    DisplayShape{polygon:Polygon{'chain3'}}
    

    Returns string

    a minimal string representation of this object.

Generated using TypeDoc