Browse docs

OverviewInstallationCanvasAll ComponentsFilesPDFCADAnnotationMeasurementPlacementAPI Key ManagementSymbol ManagementCollaborationCompareBatch ExportNavigationAll CapabilitiesStyles
Message API/docs/components/measurement/selection

Select Measurement

Listen for active selection changes and control the selected measurement from the host application.

Overview

Selection in the viewer works in both directions. The viewer emits `annotationSelected` when a user clicks an existing measurement or annotation, and the host can request a specific selection with `selectAnnotation`.

This is the main entry point for actions such as opening a properties panel, enabling delete controls, or syncing a sidebar row with the active canvas item.

  • Viewer Event: `annotationSelected` is emitted after a measurement becomes active.
  • Host Command: `selectAnnotation` selects a known annotation by GUID.
  • Clear Command: `unselectAnnotation` clears the active selection.

Quick Start

Most integrations need three simple pieces: listen for selection changes, select an item by GUID when needed, and clear the selection when the workflow ends.

Listen for annotationSelected

window.addEventListener('message', (event) => {
  if (event.data?.type !== 'annotationSelected') return;

  const { guid, data } = event.data.payload;
  console.log('Selected annotation', guid, data);
});

Select by GUID

const iframe = document.querySelector('[data-viewer-iframe]');

iframe.contentWindow?.postMessage({
  type: 'selectAnnotation',
  payload: {
    guid: 'B6B884DD-2C53-4237-9AA2-D000F8256246'
  }
}, '*');

Clear active selection

const iframe = document.querySelector('[data-viewer-iframe]');

iframe.contentWindow?.postMessage({
  type: 'unselectAnnotation'
}, '*');

User Selection Flow

When the user clicks a measurement on the canvas, the viewer becomes the source of truth and returns the selected annotation payload to the host.

The click itself happens inside the viewer UI, so the code starts at the first emitted message rather than the physical canvas interaction.

Canvas Emits

1. Viewer emits annotationSelected

The viewer sends the active GUID and annotation data back to the host.

typescript
{
  type: 'annotationSelected',
  payload: {
    guid: 'D981187C-8192-46E3-B64C-F8F6B70B6073',
    data: {
      DimText: '137.96 mm',
      FileName: 'C:\\Rasterex\\RxView360Server\\bin\\cache\\rx_3c_54c226f0\\version 42.pdf',
      FillColor: 'rgba(255,0,0,1)',
      ID: 1,
      LineColor: 'rgba(165,42,42,1)',
      LineWidth: 0.07818840740727304,
      Locked: false,
      Rect: { x: 199.6, y: 177.1, w: 230.3, h: 152.8 },
      Status: 'none',
      Subtype: 0,
      TextColor: 'rgba(165,42,42,1)',
      TimeStamp: 1770125135915,
      Tool: 'Dimension Line',
      Transparency: 100,
      Type: 7,
      UniqueID: 'D981187C-8192-46E3-B64C-F8F6B70B6073',
      ViewName: 'Page 1'
    }
  }
}
Host Sends

2. Host syncs UI

The host uses the GUID and payload to highlight the matching row, open tools, or enable follow-up actions.

typescript
window.addEventListener('message', (event) => {
  if (event.data?.type !== 'annotationSelected') return;

  const { guid } = event.data.payload;
  setActiveSidebarItem(guid);
  setDeleteEnabled(true);
});

Programmatic Control

Use `selectAnnotation` when the host already knows the target GUID and needs the viewer to focus that item.

Use `unselectAnnotation` to clear the current selection before switching context or closing a selection-driven workflow.

Host Sends

1. Host sends selectAnnotation

The host asks the viewer to activate a specific annotation by GUID.

typescript
const iframe = document.querySelector('[data-viewer-iframe]') as HTMLIFrameElement;

iframe.contentWindow?.postMessage({
  type: 'selectAnnotation',
  payload: {
    guid: 'B6B884DD-2C53-4237-9AA2-D000F8256246'
  }
}, '*');
Canvas Emits

2. Viewer returns annotationSelected

After selection is applied, the viewer emits the same selection event used for manual clicks.

typescript
{
  type: 'annotationSelected',
  payload: {
    guid: 'B6B884DD-2C53-4237-9AA2-D000F8256246',
    data: {
      UniqueID: 'B6B884DD-2C53-4237-9AA2-D000F8256246',
      Tool: 'Dimension Line'
    }
  }
}
Host Sends

3. Host clears selection with unselectAnnotation

The host clears the active annotation when the selection is no longer needed.

typescript
iframe.contentWindow?.postMessage({
  type: 'unselectAnnotation'
}, '*');

Select and clear from the host

const iframe = document.querySelector('[data-viewer-iframe]');

function selectMeasurement(guid) {
  iframe.contentWindow?.postMessage({
    type: 'selectAnnotation',
    payload: { guid }
  }, '*');
}

function clearMeasurementSelection() {
  iframe.contentWindow?.postMessage({
    type: 'unselectAnnotation'
  }, '*');
}

Selection Payload

The `annotationSelected` payload contains the selected GUID plus the annotation metadata returned by the viewer.

{
  guid: 'D981187C-8192-46E3-B64C-F8F6B70B6073',
  data: {
    DimText: '137.96 mm',
    Tool: 'Dimension Line',
    ViewName: 'Page 1',
    FileName: 'C:\\Rasterex\\RxView360Server\\bin\\cache\\rx_3c_54c226f0\\version 42.pdf',
    FillColor: 'rgba(255,0,0,1)',
    LineColor: 'rgba(165,42,42,1)',
    TextColor: 'rgba(165,42,42,1)',
    LineWidth: 0.07818840740727304,
    Rect: { x: 199.6, y: 177.1, w: 230.3, h: 152.8 },
    TimeStamp: 1770125135915,
    UniqueID: 'D981187C-8192-46E3-B64C-F8F6B70B6073',
    ID: 1,
    Type: 7,
    Subtype: 0,
    Status: 'none',
    Locked: false,
    Transparency: 100
  }
}
Selection Payload

Implementation Pattern

A common integration pattern is to listen for `annotationSelected`, keep the active GUID in host state, and expose helper functions that can select or clear measurements on demand.

const iframe = document.querySelector('[data-viewer-iframe]');
let activeGuid = null;

window.addEventListener('message', (event) => {
  if (event.data?.type !== 'annotationSelected') return;

  const { guid, data } = event.data.payload;
  activeGuid = guid;

  document.getElementById(guid)?.scrollIntoView();
  showPropertyEditor(data);
});

function selectMeasurement(guid) {
  iframe.contentWindow?.postMessage({
    type: 'selectAnnotation',
    payload: { guid }
  }, '*');
}

function clearMeasurementSelection() {
  activeGuid = null;
  iframe.contentWindow?.postMessage({
    type: 'unselectAnnotation'
  }, '*');
}
Implementation Pattern

Additional Resources

Continue with related measurement workflows and API references.