Option Overloads

The yFiles Class Framework provides option overloads, also known as option objects for comfortably passing complex sets of parameters to methods and constructors. With many API methods, instead of passing a list of multiple parameters, a plain parameter object can be passed as the sole parameter.

The object’s properties need to have the names of the parameters. For some APIs, additional "extra" options that are described in the API documentation can be provided. In contrast to parameter lists, not all properties need to be provided in case of optional parameters: Default values will be used instead 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. Toggle the checkbox named Option Overload, to see which options are available. 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 NodeStylePortStyleAdapter({
        nodeStyle: new ShapeNodeStyle({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

Basically there are two major types of extra properties:

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

new GraphEditorInputMode({movableItems: GraphItemTypes.NONE})

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

For factory methods there is a variant where more complex properties of the resulting element can be specified using option objects. Instead of calling methods on or for the resulting object, an array of invocations of that method may be specified in option 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 need to be arrays of values, too. For single parameter methods, it suffices to put the single parameter into the top-level array. Like-wise, if the method accepts option objects, the option 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.