Option Overloads

yFiles provides option overloads, also known as option objects, for conveniently passing complex sets of parameters to methods and constructors. Instead of passing a list of multiple parameters to many API methods, you can pass a parameter object as the sole parameter.

The object’s properties must have the names of the parameters. For some APIs, you can provide additional "extra" options that are described in the API documentation. Unlike parameter lists, you don’t need to provide all properties if there are optional parameters: default values will be used where available. Extra properties offer a way to pass further information and enable more concise object creation code that doesn’t require temporary variables.

Parameter objects can contain complex types, such as other yFiles types or convertible types.

Option overloads cannot always be used in the library. Methods and constructors that accept a parameter object are annotated as such in the API documentation. To see which options are available, toggle the checkbox named Option Overload. See the documentation of GraphEditorInputMode for a more complex example. Whenever extra properties are available, a small exclamation mark will be shown in the documentation for the parameters.

const node = graph.createNode({
  layout: new Rect(10, 10, 100, 60),
  style: new ShapeNodeStyle({
    shape: ShapeNodeShape.HEXAGON,
    fill: Fill.BLUE,
    stroke: new Stroke({
      fill: Fill.DARK_BLUE,
      thickness: 3
    })
  }),
  labels: ['label1'],
  ports: [
    {
      style: new ShapePortStyle({
        shape: ShapeNodeShape.ELLIPSE,
        renderSize: new Size(5, 5)
      }),
      locationParameter: FreeNodePortLocationModel.NODE_TOP_ANCHORED
    },
    {
      style: VoidPortStyle.INSTANCE,
      locationParameter: FreeNodePortLocationModel.NODE_BOTTOM_ANCHORED
    }
  ],
  tag: { data: 'data' }
})

Extra Properties in Option Overloads

There are two main types of extra properties:

For many frequently used properties, the constructor of a type has an extra property with the same name available via the options object parameter:

new GraphEditorInputMode({ movableSelectedItems: GraphItemTypes.NONE })

// equivalent to
const geim = new GraphEditorInputMode()
geim.movableSelectedItems = GraphItemTypes.NONE

For factory methods, there is a variant where more complex properties of the resulting element can be specified using options objects. Instead of calling methods on the resulting object directly, an array of method invocations can be specified using options object parameter syntax:

graph.createNode({
  labels: ['MyLabel', { text: "My Label", style: style }]
})

// is equivalent to
const node = graph.createNode()
graph.addLabel(node, 'My Label')
graph.addLabel({ owner: node, text: 'My Label', style: style })

If the method to be called accepts a list of parameters, the entries in the array also need to be arrays of values. For methods that accept a single parameter, it is sufficient to put the single parameter into the top-level array. Likewise, if the method accepts options objects, the options object may be put directly into the array. For each element in the array, the method will be called, and if required, the necessary relating "owner" item will be automatically injected into the invocation.