useScreenSpaceEventHandler

Use Cesium's ScreenSpaceEventHandler in a Vue-friendly way for mouse/touch screen-space events: the handler is recreated automatically when the canvas changes; listeners are re-registered when the event type or modifier changes; it is destroyed on component unmount. Use it for clicks, movement, wheel, pinch gestures, etc., with the event type changeable at runtime.

Usage

<script setup lang="ts">
import * as Cesium from 'cesium';
import { useScreenSpaceEventHandler } from 'vesium';
import { ref } from 'vue';

const coord = ref<Record<any, any>>({});

Object.values(Cesium.ScreenSpaceEventType).forEach((type: any) => {
  useScreenSpaceEventHandler(type, (ctx: any) => coord.value[type] = JSON.stringify(ctx));
});
</script>

<template>
  <div class="p-10px bg-[var(--vp-c-bg)] flex flex-col gap-5px w-200px">
    <span v-for="(value, key) in Cesium.ScreenSpaceEventType" :key="key">
      {{ key }} : {{ coord[value] || '--' }}
    </span>
  </div>
</template>

import * as Cesium from 'cesium';
import { useScreenSpaceEventHandler } from 'vesium';

const stop = useScreenSpaceEventHandler(
  Cesium.ScreenSpaceEventType.LEFT_CLICK,
  (event) => {
    console.log(event.position); // positioned events carry the screen position
  },
  { modifier: Cesium.KeyboardEventModifier.SHIFT }, // fire only while Shift is held
);

stop(); // cleanup is automatic on unmount; you can also stop manually

Options

• type - The screen-space event type (Cesium.ScreenSpaceEventType); supports a ref/getter for dynamic changes. The callback argument type is derived from type (positioned events such as clicks receive a PositionedEvent, MOUSE_MOVE a MotionEvent, WHEEL a number, pinch gestures a TwoPointEvent / TwoPointMotionEvent). Nothing is registered when omitted.
• inputAction - The listener callback; nothing is registered when omitted.
• modifier - The keyboard modifier (Cesium.KeyboardEventModifier), forwarded to Cesium.
• isActive - Whether the listener is active, defaults to true; it only pauses/resumes listener registration without recreating the whole composable.

Return Value

• Returns a stop function (WatchStopHandle): calling it stops the current listener and destroys the handler immediately; it is also called automatically on component unmount.

Notes

• The handler is created on top of the canvas: when the canvas changes (e.g. the viewer is recreated), the old instance is destroyed and a new one is created automatically — no manual handling needed.

Type Definitions

import type { KeyboardEventModifier, ScreenSpaceEventType } from 'cesium';
import type { MaybeRefOrGetter, WatchStopHandle } from 'vue';
import { ScreenSpaceEventHandler } from 'cesium';
export type ScreenSpaceEvent<T extends ScreenSpaceEventType> = {
    [ScreenSpaceEventType.LEFT_DOWN]: ScreenSpaceEventHandler.PositionedEvent;
    [ScreenSpaceEventType.LEFT_UP]: ScreenSpaceEventHandler.PositionedEvent;
    [ScreenSpaceEventType.LEFT_CLICK]: ScreenSpaceEventHandler.PositionedEvent;
    [ScreenSpaceEventType.LEFT_DOUBLE_CLICK]: ScreenSpaceEventHandler.PositionedEvent;
    [ScreenSpaceEventType.RIGHT_DOWN]: ScreenSpaceEventHandler.PositionedEvent;
    [ScreenSpaceEventType.RIGHT_UP]: ScreenSpaceEventHandler.PositionedEvent;
    [ScreenSpaceEventType.RIGHT_CLICK]: ScreenSpaceEventHandler.PositionedEvent;
    [ScreenSpaceEventType.MIDDLE_DOWN]: ScreenSpaceEventHandler.PositionedEvent;
    [ScreenSpaceEventType.MIDDLE_UP]: ScreenSpaceEventHandler.PositionedEvent;
    [ScreenSpaceEventType.MIDDLE_CLICK]: ScreenSpaceEventHandler.PositionedEvent;
    [ScreenSpaceEventType.MOUSE_MOVE]: ScreenSpaceEventHandler.MotionEvent;
    [ScreenSpaceEventType.WHEEL]: number;
    [ScreenSpaceEventType.PINCH_START]: ScreenSpaceEventHandler.TwoPointEvent;
    [ScreenSpaceEventType.PINCH_END]: ScreenSpaceEventHandler.TwoPointEvent;
    [ScreenSpaceEventType.PINCH_MOVE]: ScreenSpaceEventHandler.TwoPointMotionEvent;
}[T];
export interface UseScreenSpaceEventHandlerOptions {
    /**
     * Modifier key forwarded to Cesium.
     */
    modifier?: MaybeRefOrGetter<KeyboardEventModifier | undefined>;
    /**
     * Whether to activate the event listener without tearing down the composable.
     * @default true
     */
    isActive?: MaybeRefOrGetter<boolean>;
}
/**
 * Easily use the `ScreenSpaceEventHandler`,
 * when the dependent data changes or the component is unmounted,
 * the listener function will automatically reload or destroy.
 *
 * @param type Types of mouse event
 * @param inputAction Callback function for listening
 */
export declare function useScreenSpaceEventHandler<T extends ScreenSpaceEventType>(type?: MaybeRefOrGetter<T | undefined>, inputAction?: (event: ScreenSpaceEvent<T>) => any, options?: UseScreenSpaceEventHandlerOptions): WatchStopHandle;