Skip to main content

Getting the Controller

The Display Controller is the advanced API for the Display element. While the standard Display element API (sendCapture, sendUnit, etc.) works at the capture/unit level, the controller works at the image and element level — giving you direct control over what is rendered, how it looks, and how the user can interact with it.

getController()​

Call getController() on any Display element to obtain its controller instance.

getController(): DisplayControllerWrapper;
tip

Call getController() once in your INIT script and store the result in a global variable. The controller instance is stable — you always get the same object back, but retrieving it in every cyclic cycle is unnecessary overhead.

// INIT script
global var ctrl = Visu.page0.display1.getController();

When to use the controller vs the Display element​

Use the standard Display API (Visu.page0.display1) when:

  • You have a Capture or Unit produced by the MES workflow
  • You want the display to manage the capture history automatically
  • You just need to show results and optionally save the view

Use the controller when:

  • You want to push a raw Ve.Image directly without building a Capture
  • You need to add, remove, or refresh individual elements after initial display
  • You need to control zoom programmatically
  • You want to enable interactive tools so the user can draw or edit shapes
  • You need to read user interactions (clicks, drawn shapes, edited entities, selection changes)
  • You need to configure display options (normalize mode, opacity, cursor cross)

Controller state is volatile​

The controller state — the current image, all elements, the zoom level, the active tool, the config — represents the live view of the display. It exists only for as long as the user is looking at the current frame.

When the user opens the capture history and navigates to an older capture (set by a previous sendCapture() call from the standard Display API), the live view is replaced by that historical snapshot. Any image, elements, or tool state set through the controller will not be visible while browsing history, and will not be restored automatically when the user returns to the live view.

danger

Do not mix the controller API with the capture history workflow. If you use Visu.page0.display1.sendCapture() to populate the history and also use the controller to add elements on top, those elements will disappear every time the user navigates away from the live capture and comes back.