Class: State

montage/core/state-chart~ State

new State()

Source:

Extends

Methods

addBeforeOwnPropertyChangeListener(name, handler) → {function}

Adds a listener that will be notified *before* a property changes. See `addOwnPropertyChangeListener` for details.
Parameters:
Name Type Description
name string
handler object | function
Inherited From:
Source:
See:
Returns:
cancel
Type
function

addBeforePathChangeListener(path, handlerMethodName)

Establishes an observer such that the handler will receive a notification when the value of an FRB expression is about to change. See `addPathChangeListener` for details.
Parameters:
Name Type Description
path string
object | function
handlerMethodName string
Inherited From:
Source:
See:

addOwnPropertyChangeListener(name, handler, beforeChange) → {function}

Adds a change listener for the named property of this instance. The handler may be a function or an object with a handler method. When the property changes on this object, the handler will be notified *on the stack*. The dispatcher will try to dispatch to *only* the most specific handler method available, from `handle` + PropertyName (bactrian camel case) + `Change`, to `handlePropertyChange`, or if the `beforeChange` flag is set, `handle` + PropertyName + `WillChange` then `handlePropertyWillChange`. The arguments to the handler are `value`, `name`, and this.
Parameters:
Name Type Description
name string The name of the property to observe.
handler object | function On which to dispatch change notifications.
beforeChange boolean Whether to observer changes before they occur. To avoid the boolean trap, try to use `addBeforeOwnPropertyChangeListener` instead, unless `beforeChange` is truly variable.
Inherited From:
Source:
See:
Returns:
`cancel`, useful for removing the change listener without having to retain and reconstruct all of the arguments.
Type
function

addPathChangeListener(path, handler, handlerMethodName, beforeChange)

Creates an observer for the value of an FRB expression. The observer will immediately dispatch a notification to the handler of the initial value of the expression, before returning. If the expression's value is an array, this will be the final notification and all subsequent changes will be reflected by the content of the array. Use `addRangeAtPathChangeListener` if you want discrete notifications for changes to the content of an expression that evaluates to an array. Use `removePathChangeListener` to cancel all involved change listeners.
Parameters:
Name Type Description
path string an FRB expression.
handler object | function an object with a handler method, or a function. The handler will be called with `value`, `path`, and this as arguments.
handlerMethodName string the method name on the handler on which to dispatch change notifications, if the handler is not a function.
beforeChange boolean instructs the path change listener to dispatch before the change has occurred. Avoid using this boolean trap by making use of the named method `addBeforePathChangeListener`. Using this flag remains desireable only if `beforeChange` is indeed variable.
Inherited From:
Source:

addRangeAtPathChangeListener(path, handler, methodNamenullable) → {function}

Observes changes to the content of the value for an FRB expression. The handler will receive “ranged content change” messages. When a change listener is added, the handler will be immediately invoked with the initial content added at index 0 for the expression.
Parameters:
Name Type Attributes Description
path string an FRB expression that produces content changes
handler a function that accepts `plus`, `minus`, and `index` arguments, or a handler object with a designated method by that signature. `plus` and `minus` are arrays of values that were added or removed. `index` is the offset at which the `minus` was removed, then the `plus` was added.
methodName string <nullable>
the name of the method on the handler object that should receive change messages.
Inherited From:
Source:
Returns:
cancel function for removing the range at path change listener. Until `removeRangeAtPathChangeListener` is implemented, this is the only way to disable this kind of observer.
Type
function

callDelegateMethod(name)

This method calls the method named with the identifier prefix if it exists. Example: If the name parameter is "shouldDoSomething" and the caller's identifier is "bob", then this method will try and call "bobShouldDoSomething"
Parameters:
Name Type Description
name string
Inherited From:
Source:

defineBinding(targetPath, descriptor)

Establishes a binding between two FRB expressions. See the [FRB](http://documentup.com/montagejs/frb/) documentation for information about FRB paths/expressions. There can only be one binding per target path on an object.
Parameters:
Name Type Description
targetPath string
descriptor object A descriptor has at least an arrow property, `"<-"`, `"<->"`. The corresponding string is the `sourcePath` for the binding and the type of arrow determines whether the binding is one way (from source to target) or if data flows both directions. The `descriptor` may contain a `converter` or `reverter` object, or directly provide `convert` and `revert` functions. Converters and reverters have `convert` and `revert` methods. The `convert` function or method transforms data from the source to the target. The `revert` function or method transforms data from the target to the source and is necessary if there is a converter on a two-way binding. A `reverter` is the same as a `converter`, but the polarity is reversed. This is useful for reusing converters that were designed for data flowing the “wrong” way. The `descriptor` may also provide a `trace` flag for console debugging.
Inherited From:
Source:

defineBindings(descriptors, commonDescriptornullable)

Establishes multiple bindings.
Parameters:
Name Type Attributes Description
descriptors object an object for which every property is a source path and every value is a binding descriptor as described by `defineBinding`.
commonDescriptor object <nullable>
a partial binding descriptor with properties intended to be shared by all of the established bindings.
Inherited From:
Source:
See:

dispatchBeforeOwnPropertyChange(name, value)

Manually dispatches a notification that a property is about to change. See `dispatchOwnPropertyChange`.
Parameters:
Name Type Description
name string
value
Inherited From:
Source:
See:

dispatchOwnPropertyChange(name, value, beforeChange)

Manually dispatches a property change notification on this object. This can be useful if the property is a getter or setter and its value changes as a side effect of some other operation, like cache invalidation. It is unnecessary to dispatch a change notification in the setter of a property if it modifies its own value, but if changing `celicius` has a side effect on `fahrenheit`, they can manually dispatch changes to the other. Be sure to dispatch both the change and before the change.
Parameters:
Name Type Description
name string
value
beforeChange boolean Avoid the boolean trap and use `dispatchBeforeOwnPropertyChange`. You are not likely to encounter a case where `beforeChange` is a named variable.
Inherited From:
Source:

equals(anObject) → {boolean}

Returns true if two objects are equal, otherwise returns false.
Parameters:
Name Type Description
anObject Object The object to compare for equality.
Inherited From:
Source:
Returns:
Returns `true` if the calling object and `anObject` are identical and their `uuid` properties are also equal. Otherwise, returns `false`.
Type
boolean

getBindings() → {object}

Gets the binding descriptors for all target paths.
Inherited From:
Source:
See:
Returns:
an object that maps traget paths to binding descriptors. See `defineBinding` for information on the descriptor type.
Type
object

getOwnPropertyChangeDescriptor(name)

Produces the descriptor for a property change listener. The descriptor is an object that will contain two arrays, `willChangeListeners` and `changeListeners`. Each listener will be the `handler` given to establish the change listener on `addOwnPropertyChangeListener` or `addBeforeOwnPropertyChangeListener`.
Parameters:
Name Type Description
name string
Inherited From:
Source:
See:
Returns:
the property change descriptor for this name, created if necessary.

getPath(path)

Evaluates an FRB expression from this object and returns the value. The evaluator does not establish any change listeners.
Parameters:
Name Type Description
path string an FRB expression
Inherited From:
Source:
Returns:
the current value of the expression

getPathChangeDescriptor(path, handler, beforeChange)

Gets the path change descriptor object for an observer established previously by `addPathChangeListener` or `addBeforePathChangeListener`.
Parameters:
Name Type Description
path string an FRB expression
handler a function that will receive a value change notification, or an object with a method that will receive the change notifications
beforeChange boolean
Inherited From:
Source:
Returns:
a path change descriptor. Such objects have `path`, `handler`, `beforeChange`, and `cancel` properties. The `cancel` method is for internal use only. It cancels the observer, but does not perform any book keeping on the index of path change descriptors.

getPathChangeDescriptors()

Returns an internal index of all of the path change descriptors associated with this instance.
Inherited From:
Source:
See:
Returns:
an object that maps property names to an object with two Maps, `changeListeners` and `willChangeListeners`. Each of these maps handler objects to path change descriptors. See `getPathChangeDescriptor` for a description of that type.

hasOwnPropertyChangeDescriptor(name)

Determines whether a property has ever been observed. Removing all property change listeners does not destroy this record.
Parameters:
Name Type Description
name string
Inherited From:
Source:

makePropertyObservable(name)

An overridable method for ensuring that changes to the named property dispatch notifications. The default behavior is to wrap the property with a getter and setter.
Parameters:
Name Type Description
name string
Inherited From:
Source:

observePath(path, emit) → {function}

Observes changes to the value of an FRB expression. The content of the emitted value may react to changes, particularly if it is an array.
Parameters:
Name Type Description
path string an FRB expression
emit function a function that receives new values in response to changes. The emitter may return a `cancel` function if it manages event listeners that must be collected when the value changes.
Inherited From:
Source:
Returns:
a canceler function that will remove all involved change listeners, prevent new values from being observed, and prevent previously emitted values from reacting to any further changes.
Type
function

removeBeforeOwnPropertyChangeListener(name, handler)

Removes a change listener established by `addBeforeOwnPropertyChangeListener` or `addOwnPropertyChangeListener` with the `beforeChange` flag. Call with the same arguments used to set up the observer.
Parameters:
Name Type Description
name string
handler object | function
Inherited From:
Source:
See:

removeBeforePathChangeListener(path, handlerMethodName, beforeChange)

Removes a path change listener previously established by a call to `addBeforePathChangeListener`. The given arguments must match the original. See `addPathChangeListener` for descriptions of their meaning.
Parameters:
Name Type Description
path string
object | function
handlerMethodName string
beforeChange boolean
Inherited From:
Source:
See:

removeOwnPropertyChangeListener(name, handler, beforeChange)

Cancels a change listener established with the same given parameters. For the meanings of the parameters, see `addOwnPropertyChangeListener`.
Parameters:
Name Type Description
name string
handler object | function
beforeChange boolean
Inherited From:
Source:
See:

removePathChangeListener(path, handler, beforeChange)

Removes a path change listener previously established by a call to `addPathChangeListener`. The given arguments must match the original. See `addPathChangeListener` for descriptions of their meaning.
Parameters:
Name Type Description
path string
handler object | function
beforeChange boolean
Inherited From:
Source:
See:

setPath(path, value)

Assigns a value to the FRB expression from this object. Not all expressions can be assigned to. Property chains will work, but will silently fail if the target object does not exist.
Parameters:
Name Type Description
path string an FRB expression designating the value to replace
value the new value
Inherited From:
Source: