# Class AnimationTrigger

GoJS® Diagramming Components
version 3.0.7
by Northwoods Software®

An AnimationTrigger describes how to automatically animate a property on a GraphObject when it changes value. The target property name is a string, and all name matching is case-sensitive.

Triggers will be shared by all copies of the template's GraphObjects. You can include AnimationTriggers in your templates just like Bindings are included:

    new go.Panel("Vertical",
        {
          // ... Panel properties
        })
      // This trigger uses the default value of AnimationTrigger.startCondition:
      // If a transaction is ongoing and Panel.position is changed, this trigger will animate
      // all changes to Panel.position at the end of the next transaction, in one bundled Animation.
      // If no transaction is ongoing, then it will animate this value immediately.
      .trigger("position")
      .add(
        new go.Shape({
            // ... Shape properties
          })
          // Animate all changes to Shape.opacity immediately
          .trigger("opacity", null, go.TriggerStart.Immediate),
        // ... other GraphObjects in the Panel
      )

When the startCondition is TriggerStart.Default, GoJS will attempt to TriggerStart.Bundled or TriggerStart.Immediate based on the state of the transaction. If no transaction is ongoing, this trigger will treat the default as using TriggerStart.Immediate. Otherwise it will work as TriggerStart.Bundled.

When the startCondition is TriggerStart.Bundled, the AnimationManager will use the default animation to prepare a single Animation that begins when the current transaction has ended. This animation may be canceled if a new transaction is started.

When the startCondition is TriggerStart.Immediate, a new animation will be created for every instance of the property changed, and started immediately, and run until completion. This may be useful for cosmetic changes, such as animating the opacity or color of an object on mouseEnter or mouseLeave.

You can only specify properties that exist on the GraphObject, and are also registered with AnimationManager.defineAnimationEffect. By default these properties are:

- `"position"`
- `"location"` (on Parts)
- `"scale"`
- `"opacity"`
- `"angle"`
- `"desiredSize"`
- `"background"`
- `"fill"` (on Shapes)
- `"strokeWidth"` (on Shapes)
- `"strokeDashOffset"` (on Shapes)
- `"stroke"` (on Shapes, TextBlocks)

Examples of defining additional animation properties are given in the Introduction Page on Animations.

`since`

2.1

#####
Index

### Constructors

constructor

### Accessors

animationSettings
propertyName
startCondition

### Methods

copy

### Properties

Bundled
Default
Immediate

## Constructors

### constructor

- new AnimationTrigger(propertyName: string, animationSettings?: {
  duration?: number;
  easing?: EasingFunction;
  finished?: ((animation: Animation) => void);
  }, startCondition?: TriggerStart): AnimationTrigger

- This constructor creates an AnimationTrigger. These are typically constructed within Part templates.

       // ...
       new go.Shape(
         {
           // ... Shape properties
         })
         // Animate all changes to Shape.opacity immediately
         .trigger("opacity", null, go.TriggerStart.Immediate)

  #### Parameters

  - ##### propertyName: string

    A string naming the target property to animate. This should not be the empty string.

  - ##### `Optional` animationSettings: {
    duration?: number;
    easing?: EasingFunction;
    finished?: ((animation: Animation) => void);
    }

    An optional Object describing properties to set on animations created by this AnimationTrigger. See the animationSettings property for detail. If specified, this also sets the startCondition to TriggerStart.Immediate.

    - ##### `Optional` duration?: number

    - ##### `Optional` easing?: EasingFunction

    - ##### `Optional` finished?: ((animation: Animation) => void)

      - - (animation: Animation): void

        - #### Parameters

          - ##### animation: Animation

          #### Returns void

  - ##### `Optional` startCondition: TriggerStart

    An optional TriggerStart to set the startCondition property.

  #### Returns AnimationTrigger

## Accessors

### animationSettings
: {
duration?: number;
easing?: EasingFunction;
finished?: ((animation: Animation) => void);
}

- These settings are only used if the startCondition is TriggerStart.Immediate. Creating a new AnimationTrigger with animationSettings in the constructor automatically sets startCondition to TriggerStart.Immediate

  This gets or sets the settings for any Animations this trigger creates. Immediate triggers create a new Animation with each triggering, and apply these settings to that Animation.

  This can be set to an object with a subset of possible Animation settings. The default value is `null`, which keeps default Animation settings.

  Since a startCondition of TriggerStart.Bundled uses the default animation, you must set the properties of AnimationManager.defaultAnimation, and not this property, to modify the animation settings.

  To set default settings for all created Animations, you can modify the settings on AnimationManager instead, such as AnimationManager.duration.

  Possible properties to set in this object are:

  - duration: a `number`, corresponding to Animation.duration.
  - finished: a `Function`, corresponding to Animation.finished.
  - easing: an `EasingFunction`, corresponding to Animation.easing.

### propertyName
: string

- Gets or sets the name of the property to animate on the target GraphObject. The default value is set during constructor initialization.

  You can only specify properties that exist on the GraphObject, and are also registered with AnimationManager.defineAnimationEffect. By default these properties are the same as the list of possible Animation effects:

  - `"position"`
  - `"location"` (on Parts)
  - `"scale"`
  - `"opacity"`
  - `"angle"`
  - `"desiredSize"`
  - `"background"`
  - `"fill"` (on Shapes)
  - `"strokeWidth"` (on Shapes)
  - `"strokeDashOffset"` (on Shapes)
  - `"stroke"` (on Shapes, TextBlocks)

  Examples of defining additional properties by adding animation effects are given in the Introduction Page on Animations.

### startCondition
: TriggerStart

- Gets or sets the starting condition for this trigger.

  AnimationTriggers can invoke an animation immediately, starting a new animation with each property of each GraphObject that has been modified, or they can (more efficiently) be bundled together into the default animation (AnimationManager.defaultAnimation) and begin only one animation, at the end of the next transaction.

  It is useful for the startCondition to be TriggerStart.Immediate when changing GraphObject properties on GraphObject.mouseEnter or GraphObject.mouseLeave. It is useful for the startCondition to be TriggerStart.Bundled when changing several GraphObject properties together, such as when highlighting multiple parts, on selection changes, and during transactions, or when performance is a consideration.

  These behaviors can be set with the values TriggerStart.Immediate and TriggerStart.Bundled, respectively. The default value, TriggerStart.Default, attempts to infer which is best: It will start immediately if there is no ongoing transaction or if Diagram.skipsUndoManager is true, and otherwise bundle them.

## Methods

### `Virtual` copy

- copy(): AnimationTrigger

- Create a copy of this AnimationTrigger, with the same property values.

  #### Returns AnimationTrigger

## Properties

### `Static` `Readonly` Bundled

`deprecated`

See TriggerStart.Bundled.

### `Static` `Readonly` Default

`deprecated`

See TriggerStart.Default.

### `Static` `Readonly` Immediate

`deprecated`

See TriggerStart.Immediate.

Copyright © 1998-2024 by Northwoods Software Corporation.