0
# Event System
1

2
Comprehensive event handling with binding, delegation, triggering, and mobile-optimized features. The event system provides jQuery-compatible methods with optimizations for modern browsers.
3

4
## Capabilities
5

6
### Event Utilities
7

8
Static methods for event handling and context management.
9

10
```javascript { .api }
11
/**
12
 * Create function with bound context and optional pre-filled arguments
13
 * @param fn - Function to bind
14
 * @param context - Context (this) for function execution  
15
 * @param args - Optional arguments to pre-fill
16
 * @returns Bound function
17
 */
18
$.proxy(fn, context, ...args);
19

20
/**
21
 * Create Event object with specified type and properties
22
 * @param type - Event type string
23
 * @param props - Optional properties to set on event
24
 * @returns Event object
25
 */
26
$.Event(type, props);
27
```
28

29
**Usage Examples:**
30

31
```javascript
32
// Context binding
33
const obj = {
34
  name: 'MyObject',
35
  greet: function() {
36
    console.log('Hello from ' + this.name);
37
  }
38
};
39

40
const boundGreet = $.proxy(obj.greet, obj);
41
boundGreet(); // "Hello from MyObject"
42

43
// Pre-filled arguments
44
function logMessage(type, message) {
45
  console.log(`[${type}] ${message}`);
46
}
47

48
const logError = $.proxy(logMessage, null, 'ERROR');
49
logError('Something went wrong'); // "[ERROR] Something went wrong"
50

51
// Custom event creation
52
const customEvent = $.Event('customEvent', {
53
  customProperty: 'customValue'
54
});
55

56
$('#element').trigger(customEvent);
57
```
58

59
### Event Binding
60

61
Core event binding methods for attaching event handlers to elements.
62

63
```javascript { .api }
64
/**
65
 * Attach event handlers to elements
66
 * @param event - Event type or space-separated types
67
 * @param selector - Optional selector for event delegation
68
 * @param data - Optional data to pass to handler
69
 * @param callback - Event handler function
70
 * @param one - Internal flag for one-time binding
71
 * @returns Original collection
72
 */
73
$.fn.on(event, selector, data, callback, one);
74

75
/**
76
 * Remove event handlers from elements
77
 * @param event - Event type or space-separated types (optional)
78
 * @param selector - Optional selector used in delegation
79
 * @param callback - Optional specific handler to remove
80
 * @returns Original collection
81
 */
82
$.fn.off(event, selector, callback);
83

84
/**
85
 * Attach event handler that executes only once
86
 * @param event - Event type
87
 * @param selector - Optional selector for delegation
88
 * @param data - Optional data to pass to handler
89
 * @param callback - Event handler function
90
 * @returns Original collection
91
 */
92
$.fn.one(event, selector, data, callback);
93

94
/**
95
 * Bind event handlers (legacy method, use 'on' instead)
96
 * @param event - Event type
97
 * @param data - Optional data to pass to handler
98
 * @param callback - Event handler function
99
 * @returns Original collection
100
 */
101
$.fn.bind(event, data, callback);
102

103
/**
104
 * Remove event handlers (legacy method, use 'off' instead)
105
 * @param event - Event type (optional)
106
 * @param callback - Optional specific handler to remove
107
 * @returns Original collection
108
 */
109
$.fn.unbind(event, callback);
110
```
111

112
**Usage Examples:**
113

114
```javascript
115
// Basic event binding
116
$('.button').on('click', function(e) {
117
  console.log('Button clicked:', this);
118
});
119

120
// Event delegation
121
$('#container').on('click', '.dynamic-button', function(e) {
122
  console.log('Delegated click:', this);
123
});
124

125
// Multiple events
126
$('.element').on('mouseenter mouseleave', function(e) {
127
  $(this).toggleClass('hover');
128
});
129

130
// One-time handler
131
$('.trigger').one('click', function() {
132
  console.log('This will only run once');
133
});
134

135
// With data
136
$('.item').on('click', {id: 123}, function(e) {
137
  console.log('Item ID:', e.data.id);
138
});
139
```
140

141
### Event Delegation
142

143
Methods for delegated event handling, allowing events on dynamic content.
144

145
```javascript { .api }
146
/**
147
 * Delegate events to descendant elements
148
 * @param selector - Selector for elements to delegate to
149
 * @param event - Event type
150
 * @param callback - Event handler function
151
 * @returns Original collection
152
 */
153
$.fn.delegate(selector, event, callback);
154

155
/**
156
 * Remove delegated event handlers
157
 * @param selector - Selector used in delegation
158
 * @param event - Event type
159
 * @param callback - Optional specific handler to remove
160
 * @returns Original collection
161
 */
162
$.fn.undelegate(selector, event, callback);
163

164
/**
165
 * Live event binding (deprecated, use 'on' with delegation)
166
 * @param event - Event type
167
 * @param callback - Event handler function
168
 * @returns Original collection
169
 */
170
$.fn.live(event, callback);
171

172
/**
173
 * Remove live event handlers (deprecated)
174
 * @param event - Event type
175
 * @param callback - Optional specific handler to remove
176
 * @returns Original collection
177
 */
178
$.fn.die(event, callback);
179
```
180

181
### Event Triggering
182

183
Methods for programmatically triggering events.
184

185
```javascript { .api }
186
/**
187
 * Trigger events on elements
188
 * @param event - Event type or Event object
189
 * @param args - Optional arguments to pass to handlers
190
 * @returns Original collection
191
 */
192
$.fn.trigger(event, args);
193

194
/**
195
 * Trigger event handlers without bubbling or default actions
196
 * @param event - Event type or Event object
197
 * @param args - Optional arguments to pass to handlers
198
 * @returns Result from last handler or undefined
199
 */
200
$.fn.triggerHandler(event, args);
201
```
202

203
**Usage Examples:**
204

205
```javascript
206
// Trigger custom event
207
$('.element').trigger('customEvent', ['arg1', 'arg2']);
208

209
// Trigger with event object
210
const event = $.Event('click', {bubbles: true});
211
$('.button').trigger(event);
212

213
// Trigger handler only (no bubbling)
214
const result = $('.input').triggerHandler('focus');
215
```
216

217
### Event Shortcuts
218

219
Convenient shorthand methods for common events.
220

221
```javascript { .api }
222
/**
223
 * Bind or trigger click events
224
 * @param callback - Optional event handler
225
 * @returns Original collection
226
 */
227
$.fn.click(callback);
228

229
/**
230
 * Bind or trigger double-click events
231
 * @param callback - Optional event handler
232
 * @returns Original collection
233
 */
234
$.fn.dblclick(callback);
235

236
/**
237
 * Bind or trigger focus events
238
 * @param callback - Optional event handler
239
 * @returns Original collection
240
 */
241
$.fn.focus(callback);
242

243
/**
244
 * Bind or trigger blur events
245
 * @param callback - Optional event handler
246
 * @returns Original collection
247
 */
248
$.fn.blur(callback);
249

250
/**
251
 * Bind or trigger change events
252
 * @param callback - Optional event handler
253
 * @returns Original collection
254
 */
255
$.fn.change(callback);
256

257
/**
258
 * Bind or trigger select events
259
 * @param callback - Optional event handler
260
 * @returns Original collection
261
 */
262
$.fn.select(callback);
263

264
/**
265
 * Bind or trigger keydown events
266
 * @param callback - Optional event handler
267
 * @returns Original collection
268
 */
269
$.fn.keydown(callback);
270

271
/**
272
 * Bind or trigger keypress events
273
 * @param callback - Optional event handler
274
 * @returns Original collection
275
 */
276
$.fn.keypress(callback);
277

278
/**
279
 * Bind or trigger keyup events
280
 * @param callback - Optional event handler
281
 * @returns Original collection
282
 */
283
$.fn.keyup(callback);
284

285
/**
286
 * Bind or trigger mousedown events
287
 * @param callback - Optional event handler
288
 * @returns Original collection
289
 */
290
$.fn.mousedown(callback);
291

292
/**
293
 * Bind or trigger mouseup events
294
 * @param callback - Optional event handler
295
 * @returns Original collection
296
 */
297
$.fn.mouseup(callback);
298

299
/**
300
 * Bind or trigger mousemove events
301
 * @param callback - Optional event handler
302
 * @returns Original collection
303
 */
304
$.fn.mousemove(callback);
305

306
/**
307
 * Bind or trigger mouseover events
308
 * @param callback - Optional event handler
309
 * @returns Original collection
310
 */
311
$.fn.mouseover(callback);
312

313
/**
314
 * Bind or trigger mouseout events
315
 * @param callback - Optional event handler
316
 * @returns Original collection
317
 */
318
$.fn.mouseout(callback);
319

320
/**
321
 * Bind or trigger mouseenter events
322
 * @param callback - Optional event handler
323
 * @returns Original collection
324
 */
325
$.fn.mouseenter(callback);
326

327
/**
328
 * Bind or trigger mouseleave events
329
 * @param callback - Optional event handler
330
 * @returns Original collection
331
 */
332
$.fn.mouseleave(callback);
333

334
/**
335
 * Bind or trigger scroll events
336
 * @param callback - Optional event handler
337
 * @returns Original collection
338
 */
339
$.fn.scroll(callback);
340

341
/**
342
 * Bind or trigger resize events
343
 * @param callback - Optional event handler
344
 * @returns Original collection
345
 */
346
$.fn.resize(callback);
347

348
/**
349
 * Bind or trigger load events
350
 * @param callback - Optional event handler
351
 * @returns Original collection
352
 */
353
$.fn.load(callback);
354

355
/**
356
 * Bind or trigger unload events
357
 * @param callback - Optional event handler
358
 * @returns Original collection
359
 */
360
$.fn.unload(callback);
361

362
/**
363
 * Bind or trigger error events
364
 * @param callback - Optional event handler
365
 * @returns Original collection
366
 */
367
$.fn.error(callback);
368
```
369

370
**Usage Examples:**
371

372
```javascript
373
// Event binding
374
$('.button').click(function() {
375
  console.log('Button clicked');
376
});
377

378
// Event triggering
379
$('.button').click(); // Trigger click event
380

381
// Form events
382
$('input').focus(function() {
383
  $(this).addClass('focused');
384
}).blur(function() {
385
  $(this).removeClass('focused');
386
});
387

388
// Keyboard events
389
$('input').keydown(function(e) {
390
  if (e.which === 13) { // Enter key
391
    $(this).closest('form').submit();
392
  }
393
});
394
```
395

396
### Event Utilities
397

398
Utility functions and objects for event handling.
399

400
```javascript { .api }
401
/**
402
 * Create custom event objects
403
 * @param type - Event type
404
 * @param props - Optional event properties
405
 * @returns Event object
406
 */
407
$.Event(type, props);
408

409
/**
410
 * Bind function to specific context
411
 * @param fn - Function to bind
412
 * @param context - Context to bind to (this value)
413
 * @returns Bound function
414
 */
415
$.proxy(fn, context);
416

417
/**
418
 * Event utilities object
419
 */
420
$.event; // Contains add, remove methods for internal use
421
```
422

423
**Usage Examples:**
424

425
```javascript
426
// Custom event creation
427
const customEvent = $.Event('customType', {
428
  bubbles: true,
429
  cancelable: true,
430
  detail: {info: 'custom data'}
431
});
432
$('.element').trigger(customEvent);
433

434
// Function binding
435
const obj = {
436
  name: 'Example',
437
  greet: function() {
438
    console.log('Hello from ' + this.name);
439
  }
440
};
441

442
$('.button').on('click', $.proxy(obj.greet, obj));
443
// or
444
$('.button').on('click', $.proxy('greet', obj));
445
```
446

447
### Event Handler Context
448

449
Understanding the context and event object in handlers.
450

451
```javascript { .api }
452
// Event handler signature
453
function eventHandler(event) {
454
  // 'this' refers to the DOM element
455
  // 'event' is the event object with properties:
456
  //   - type: event type
457
  //   - target: element that triggered event
458
  //   - currentTarget: element handler is attached to
459
  //   - which: key/button code
460
  //   - pageX, pageY: mouse coordinates
461
  //   - preventDefault(): prevent default action
462
  //   - stopPropagation(): stop event bubbling
463
  //   - data: data passed during binding
464
}
465
```
466

467
**Usage Examples:**
468

469
```javascript
470
$('.link').on('click', function(e) {
471
  e.preventDefault(); // Prevent link navigation
472
  console.log('Clicked element:', this);
473
  console.log('Event type:', e.type);
474
  console.log('Mouse position:', e.pageX, e.pageY);
475
});
476

477
$('.item').on('keydown', function(e) {
478
  if (e.which === 27) { // Escape key
479
    $(this).hide();
480
  }
481
});
482
```
483

484
### Performance Considerations
485

486
Best practices for event handling performance:
487

488
```javascript
489
// Use event delegation for dynamic content
490
$('#container').on('click', '.dynamic-item', handler);
491

492
// Remove event handlers when no longer needed
493
$('.temporary').off('click.namespace');
494

495
// Use namespaced events for easier management
496
$('.element').on('click.myNamespace', handler);
497
$('.element').off('.myNamespace'); // Remove all namespaced events
498

499
// Throttle high-frequency events
500
let scrollTimeout;
501
$(window).on('scroll', function() {
502
  clearTimeout(scrollTimeout);
503
  scrollTimeout = setTimeout(function() {
504
    // Handle scroll
505
  }, 100);
506
});
507
```