0
# Events and Interaction
1

2
Event system supporting mouse, touch, and pointer interactions with event bubbling, hit testing, and custom event handling. Provides comprehensive interaction capabilities for creating responsive user interfaces and interactive graphics.
3

4
## Capabilities
5

6
### Federated Event System
7

8
Modern event system with bubbling, capturing, and pointer abstraction.
9

10
```typescript { .api }
11
/**
12
 * Base federated event class
13
 */
14
class FederatedEvent {
15
  constructor(manager: EventBoundary);
16
  
17
  /** Event type */
18
  readonly type: string;
19
  
20
  /** Event target */
21
  readonly target: FederatedEventTarget;
22
  
23
  /** Current event target during bubbling */
24
  readonly currentTarget: FederatedEventTarget;
25
  
26
  /** Event timestamp */
27
  readonly timeStamp: number;
28
  
29
  /** Event bubbles flag */
30
  readonly bubbles: boolean;
31
  
32
  /** Event cancelable flag */
33
  readonly cancelable: boolean;
34
  
35
  /** Event canceled flag */
36
  readonly canceled: boolean;
37
  
38
  /** Default prevented flag */
39
  readonly defaultPrevented: boolean;
40
  
41
  /** Event phase */
42
  readonly eventPhase: number;
43
  
44
  /** Event manager */
45
  readonly manager: EventBoundary;
46
  
47
  /** Path of event propagation */
48
  readonly path: FederatedEventTarget[];
49
  
50
  /** Propagation stopped flag */
51
  readonly propagationStopped: boolean;
52
  
53
  /** Immediate propagation stopped flag */
54
  readonly propagationImmediatelyStopped: boolean;
55
  
56
  /**
57
   * Stop event propagation
58
   */
59
  stopPropagation(): void;
60
  
61
  /**
62
   * Stop immediate event propagation
63
   */
64
  stopImmediatePropagation(): void;
65
  
66
  /**
67
   * Prevent default behavior
68
   */
69
  preventDefault(): void;
70
  
71
  /**
72
   * Get composed path
73
   * @returns Array of event targets
74
   */
75
  composedPath(): FederatedEventTarget[];
76
}
77
```
78

79
### Pointer Events
80

81
Comprehensive pointer event system supporting mouse, touch, and pen input.
82

83
```typescript { .api }
84
/**
85
 * Federated pointer event for mouse, touch, and pen
86
 */
87
class FederatedPointerEvent extends FederatedEvent {
88
  /** Pointer ID */
89
  readonly pointerId: number;
90
  
91
  /** Pointer width */
92
  readonly width: number;
93
  
94
  /** Pointer height */
95
  readonly height: number;
96
  
97
  /** Is primary pointer */
98
  readonly isPrimary: boolean;
99
  
100
  /** Pointer type */
101
  readonly pointerType: 'mouse' | 'pen' | 'touch';
102
  
103
  /** Pressure (0-1) */
104
  readonly pressure: number;
105
  
106
  /** Tangential pressure */
107
  readonly tangentialPressure: number;
108
  
109
  /** Tilt X angle */
110
  readonly tiltX: number;
111
  
112
  /** Tilt Y angle */
113
  readonly tiltY: number;
114
  
115
  /** Twist angle */
116
  readonly twist: number;
117
  
118
  /** Alt key pressed */
119
  readonly altKey: boolean;
120
  
121
  /** Ctrl key pressed */
122
  readonly ctrlKey: boolean;
123
  
124
  /** Meta key pressed */
125
  readonly metaKey: boolean;
126
  
127
  /** Shift key pressed */
128
  readonly shiftKey: boolean;
129
  
130
  /** Mouse button pressed */
131
  readonly button: number;
132
  
133
  /** Mouse buttons bitmask */
134
  readonly buttons: number;
135
  
136
  /** Client X coordinate */
137
  readonly clientX: number;
138
  
139
  /** Client Y coordinate */
140
  readonly clientY: number;
141
  
142
  /** Movement X delta */
143
  readonly movementX: number;
144
  
145
  /** Movement Y delta */
146
  readonly movementY: number;
147
  
148
  /** Offset X coordinate */
149
  readonly offsetX: number;
150
  
151
  /** Offset Y coordinate */
152
  readonly offsetY: number;
153
  
154
  /** Global X coordinate */
155
  readonly globalX: number;
156
  
157
  /** Global Y coordinate */
158
  readonly globalY: number;
159
  
160
  /** Screen X coordinate */
161
  readonly screenX: number;
162
  
163
  /** Screen Y coordinate */
164
  readonly screenY: number;
165
  
166
  /**
167
   * Get local position relative to display object
168
   * @param displayObject - Target display object
169
   * @param point - Point to store result
170
   * @param globalPos - Global position to convert
171
   * @returns Local position
172
   */
173
  getLocalPosition(displayObject: Container, point?: Point, globalPos?: PointData): Point;
174
  
175
  /**
176
   * Get global position
177
   * @param point - Point to store result
178
   * @returns Global position
179
   */
180
  getGlobalPosition(point?: Point): Point;
181
  
182
  /**
183
   * Clone event
184
   * @returns Cloned pointer event
185
   */
186
  clone(): FederatedPointerEvent;
187
}
188
```
189

190
### Mouse Events
191

192
Mouse-specific event extensions.
193

194
```typescript { .api }
195
/**
196
 * Federated mouse event
197
 */
198
class FederatedMouseEvent extends FederatedPointerEvent {
199
  /** Related target (for enter/leave events) */
200
  readonly relatedTarget: FederatedEventTarget;
201
  
202
  /**
203
   * Get mouse position relative to display object
204
   * @param displayObject - Target display object
205
   * @param point - Point to store result
206
   * @returns Mouse position
207
   */
208
  getMousePosition(displayObject: Container, point?: Point): Point;
209
}
210
```
211

212
### Wheel Events
213

214
Mouse wheel event support.
215

216
```typescript { .api }
217
/**
218
 * Federated wheel event
219
 */
220
class FederatedWheelEvent extends FederatedMouseEvent {
221
  /** Wheel delta X */
222
  readonly deltaX: number;
223
  
224
  /** Wheel delta Y */
225
  readonly deltaY: number;
226
  
227
  /** Wheel delta Z */
228
  readonly deltaZ: number;
229
  
230
  /** Delta mode */
231
  readonly deltaMode: number;
232
}
233
```
234

235
### Event Target Interface
236

237
Interface for objects that can receive events.
238

239
```typescript { .api }
240
/**
241
 * Event target interface
242
 */
243
interface FederatedEventTarget extends EventEmitter {
244
  /** Interactive flag */
245
  interactive: boolean;
246
  
247
  /** Interactive children flag */
248
  interactiveChildren: boolean;
249
  
250
  /** Hit area for interaction */
251
  hitArea: Rectangle | Circle | Ellipse | Polygon | null;
252
  
253
  /** Cursor style */
254
  cursor: CSSStyleDeclaration['cursor'] | string;
255
  
256
  /**
257
   * Add event listener
258
   * @param type - Event type
259
   * @param listener - Event listener function
260
   * @param options - Listener options
261
   */
262
  addEventListener(type: string, listener: (event: FederatedEvent) => void, options?: AddEventListenerOptions): void;
263
  
264
  /**
265
   * Remove event listener
266
   * @param type - Event type
267
   * @param listener - Event listener function
268
   * @param options - Listener options
269
   */
270
  removeEventListener(type: string, listener: (event: FederatedEvent) => void, options?: EventListenerOptions): void;
271
  
272
  /**
273
   * Dispatch event
274
   * @param event - Event to dispatch
275
   * @returns True if not prevented
276
   */
277
  dispatchEvent(event: FederatedEvent): boolean;
278
}
279
```
280

281
### Event Boundary
282

283
Event management and hit testing system.
284

285
```typescript { .api }
286
/**
287
 * Event boundary for managing interaction events
288
 */
289
class EventBoundary {
290
  constructor(rootTarget?: Container);
291
  
292
  /** Root target container */
293
  rootTarget: Container;
294
  
295
  /** Renderer instance */
296
  renderer: Renderer;
297
  
298
  /** Current cursor */
299
  cursor: string;
300
  
301
  /**
302
   * Map pointer event to federated event
303
   * @param nativeEvent - Native DOM event
304
   * @returns Federated event
305
   */
306
  mapPointerDown(nativeEvent: PointerEvent): FederatedPointerEvent;
307
  
308
  /**
309
   * Map pointer move event
310
   * @param nativeEvent - Native DOM event
311
   * @returns Federated event
312
   */
313
  mapPointerMove(nativeEvent: PointerEvent): FederatedPointerEvent;
314
  
315
  /**
316
   * Map pointer up event
317
   * @param nativeEvent - Native DOM event
318
   * @returns Federated event
319
   */
320
  mapPointerUp(nativeEvent: PointerEvent): FederatedPointerEvent;
321
  
322
  /**
323
   * Map wheel event
324
   * @param nativeEvent - Native DOM event
325
   * @returns Federated wheel event
326
   */
327
  mapWheel(nativeEvent: WheelEvent): FederatedWheelEvent;
328
  
329
  /**
330
   * Hit test at coordinates
331
   * @param globalX - Global X coordinate
332
   * @param globalY - Global Y coordinate
333
   * @returns Hit target or null
334
   */
335
  hitTest(globalX: number, globalY: number): FederatedEventTarget;
336
  
337
  /**
338
   * Set cursor style
339
   * @param cursor - Cursor style
340
   */
341
  setCursor(cursor: string): void;
342
}
343
```
344

345
### Event System
346

347
Main event system integration.
348

349
```typescript { .api }
350
/**
351
 * Event system for handling DOM events
352
 */
353
class EventSystem {
354
  constructor(renderer: Renderer);
355
  
356
  /** Associated renderer */
357
  renderer: Renderer;
358
  
359
  /** Event boundary */
360
  boundary: EventBoundary;
361
  
362
  /** DOM element for events */
363
  domElement: HTMLElement;
364
  
365
  /** Resolution for coordinate conversion */
366
  resolution: number;
367
  
368
  /**
369
   * Set target element for events
370
   * @param element - DOM element
371
   */
372
  setTargetElement(element: HTMLElement): void;
373
  
374
  /**
375
   * Destroy event system
376
   */
377
  destroy(): void;
378
}
379
```
380

381
### Common Event Types
382

383
Standard event types supported by the system.
384

385
```typescript { .api }
386
/**
387
 * Pointer event types
388
 */
389
type PointerEventTypes = 
390
  | 'pointerdown'
391
  | 'pointerup' 
392
  | 'pointermove'
393
  | 'pointerover'
394
  | 'pointerout'
395
  | 'pointerenter'
396
  | 'pointerleave'
397
  | 'pointercancel'
398
  | 'pointertap';
399

400
/**
401
 * Mouse event types
402
 */
403
type MouseEventTypes = 
404
  | 'mousedown'
405
  | 'mouseup'
406
  | 'mousemove'
407
  | 'mouseover'
408
  | 'mouseout'
409
  | 'mouseenter'
410
  | 'mouseleave'
411
  | 'click'
412
  | 'rightclick'
413
  | 'rightdown'
414
  | 'rightup';
415

416
/**
417
 * Touch event types
418
 */
419
type TouchEventTypes = 
420
  | 'touchstart'
421
  | 'touchend'
422
  | 'touchmove'
423
  | 'touchcancel'
424
  | 'tap';
425

426
/**
427
 * Wheel event types
428
 */
429
type WheelEventTypes = 'wheel';
430
```
431

432
**Usage Examples:**
433

434
```typescript
435
import { Container, Sprite, Graphics, FederatedPointerEvent } from 'pixi.js';
436

437
// Basic interactivity
438
const sprite = new Sprite(texture);
439
sprite.interactive = true;
440
sprite.buttonMode = true;
441

442
// Pointer events
443
sprite.on('pointerdown', (event: FederatedPointerEvent) => {
444
  console.log('Pointer down at', event.globalX, event.globalY);
445
  console.log('Local position:', event.getLocalPosition(sprite));
446
  console.log('Pointer type:', event.pointerType);
447
});
448

449
sprite.on('pointerup', (event: FederatedPointerEvent) => {
450
  console.log('Pointer up');
451
});
452

453
sprite.on('pointermove', (event: FederatedPointerEvent) => {
454
  // Drag functionality
455
  if (event.buttons > 0) {
456
    const localPos = event.getLocalPosition(sprite.parent);
457
    sprite.x = localPos.x;
458
    sprite.y = localPos.y;
459
  }
460
});
461

462
// Mouse-specific events
463
sprite.on('mouseenter', () => {
464
  sprite.tint = 0xff0000;
465
});
466

467
sprite.on('mouseleave', () => {
468
  sprite.tint = 0xffffff;
469
});
470

471
// Touch events
472
sprite.on('touchstart', (event: FederatedPointerEvent) => {
473
  console.log('Touch started with pressure:', event.pressure);
474
});
475

476
// Wheel events
477
sprite.on('wheel', (event: FederatedWheelEvent) => {
478
  // Zoom functionality
479
  const scaleFactor = event.deltaY > 0 ? 0.9 : 1.1;
480
  sprite.scale.x *= scaleFactor;
481
  sprite.scale.y *= scaleFactor;
482
  
483
  event.preventDefault(); // Prevent page scroll
484
});
485

486
// Event propagation
487
const container = new Container();
488
const childSprite = new Sprite(texture);
489

490
container.interactive = true;
491
childSprite.interactive = true;
492

493
container.addChild(childSprite);
494

495
container.on('pointerdown', () => {
496
  console.log('Container clicked');
497
});
498

499
childSprite.on('pointerdown', (event: FederatedPointerEvent) => {
500
  console.log('Child clicked');
501
  event.stopPropagation(); // Prevent container event
502
});
503

504
// Custom hit areas
505
const graphics = new Graphics();
506
graphics.rect(0, 0, 100, 100).fill(0xff0000);
507
graphics.interactive = true;
508

509
// Triangle hit area
510
const triangleHitArea = new Polygon([
511
  0, 0,
512
  50, 0,
513
  25, 50
514
]);
515
graphics.hitArea = triangleHitArea;
516

517
// Interactive children management
518
const gameContainer = new Container();
519
gameContainer.interactive = true;
520
gameContainer.interactiveChildren = true; // Enable child interactions
521

522
// Add multiple interactive sprites
523
for (let i = 0; i < 10; i++) {
524
  const gameSprite = new Sprite(texture);
525
  gameSprite.interactive = true;
526
  gameSprite.x = i * 60;
527
  gameSprite.on('pointerdown', (event) => {
528
    console.log(`Sprite ${i} clicked`);
529
  });
530
  gameContainer.addChild(gameSprite);
531
}
532

533
// Global event handling
534
app.stage.interactive = true;
535
app.stage.hitArea = app.screen;
536

537
app.stage.on('pointerdown', (event: FederatedPointerEvent) => {
538
  console.log('Stage clicked at global:', event.global);
539
  
540
  // Check which child was actually hit
541
  const hitTarget = app.renderer.events.boundary.hitTest(event.globalX, event.globalY);
542
  if (hitTarget) {
543
    console.log('Hit target:', hitTarget);
544
  }
545
});
546

547
// Cursor management
548
sprite.cursor = 'pointer';
549
sprite.on('pointerover', () => {
550
  document.body.style.cursor = 'pointer';
551
});
552

553
sprite.on('pointerout', () => {
554
  document.body.style.cursor = 'default';
555
});
556

557
// Multi-touch handling
558
const multiTouchContainer = new Container();
559
multiTouchContainer.interactive = true;
560

561
const activePointers = new Map();
562

563
multiTouchContainer.on('pointerdown', (event: FederatedPointerEvent) => {
564
  activePointers.set(event.pointerId, {
565
    startX: event.globalX,
566
    startY: event.globalY
567
  });
568
});
569

570
multiTouchContainer.on('pointermove', (event: FederatedPointerEvent) => {
571
  if (activePointers.has(event.pointerId)) {
572
    const pointer = activePointers.get(event.pointerId);
573
    const deltaX = event.globalX - pointer.startX;
574
    const deltaY = event.globalY - pointer.startY;
575
    
576
    // Handle multi-touch gestures
577
    if (activePointers.size === 2) {
578
      // Two-finger gesture (zoom, rotate, etc.)
579
    }
580
  }
581
});
582

583
multiTouchContainer.on('pointerup', (event: FederatedPointerEvent) => {
584
  activePointers.delete(event.pointerId);
585
});
586
```