1 /****************************************************************************
3 * SciTech OS Portability Manager Library
5 * ========================================================================
7 * The contents of this file are subject to the SciTech MGL Public
8 * License Version 1.0 (the "License"); you may not use this file
9 * except in compliance with the License. You may obtain a copy of
10 * the License at http://www.scitechsoft.com/mgl-license.txt
12 * Software distributed under the License is distributed on an
13 * "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
14 * implied. See the License for the specific language governing
15 * rights and limitations under the License.
17 * The Original Code is Copyright (C) 1991-1998 SciTech Software, Inc.
19 * The Initial Developer of the Original Code is SciTech Software, Inc.
20 * All Rights Reserved.
22 * ========================================================================
27 * Description: Header file for the SciTech cross platform event library
29 ****************************************************************************/
36 /*---------------------- Macros and type definitions ----------------------*/
40 /* 'C' calling conventions always */
42 #define EVTAPI _ASMAPI
43 #define EVTAPIP _ASMAPIP
45 /* Event message masks for keyDown events */
47 #define EVT_ASCIIMASK 0x00FF /* ASCII code of key pressed */
48 #define EVT_SCANMASK 0xFF00 /* Scan code of key pressed */
49 #define EVT_COUNTMASK 0x7FFF0000L /* Count for KEYREPEAT's */
51 /* Macros to extract values from the message fields */
53 #define EVT_asciiCode(m) ( (uchar) (m & EVT_ASCIIMASK) )
54 #define EVT_scanCode(m) ( (uchar) ( (m & EVT_SCANMASK) >> 8 ) )
55 #define EVT_repeatCount(m) ( (short) ( (m & EVT_COUNTMASK) >> 16 ) )
57 /****************************************************************************
59 Defines the set of ASCII codes reported by the event library functions
60 in the message field. Use the EVT_asciiCode macro to extract the code
61 from the event structure.
65 ****************************************************************************/
74 ASCII_backspace = 0x08,
98 ASCII_exclamation = 0x21, /* ! */
99 ASCII_quote = 0x22, /* " */
100 ASCII_pound = 0x23, /* # */
101 ASCII_dollar = 0x24, /* $ */
102 ASCII_percent = 0x25, /* % */
103 ASCII_ampersand = 0x26, /* & */
104 ASCII_apostrophe = 0x27, /* ' */
105 ASCII_leftBrace = 0x28, /* ( */
106 ASCII_rightBrace = 0x29, /* ) */
107 ASCII_times = 0x2A, /* * */
108 ASCII_plus = 0x2B, /* + */
109 ASCII_comma = 0x2C, /* , */
110 ASCII_minus = 0x2D, /* - */
111 ASCII_period = 0x2E, /* . */
112 ASCII_divide = 0x2F, /* / */
123 ASCII_colon = 0x3A, /* : */
124 ASCII_semicolon = 0x3B, /* ; */
125 ASCII_lessThan = 0x3C, /* < */
126 ASCII_equals = 0x3D, /* = */
127 ASCII_greaterThan = 0x3E, /* > */
128 ASCII_question = 0x3F, /* ? */
129 ASCII_at = 0x40, /* @ */
156 ASCII_leftSquareBrace = 0x5B, /* [ */
157 ASCII_backSlash = 0x5C, /* \ */
158 ASCII_rightSquareBrace = 0x5D, /* ] */
159 ASCII_caret = 0x5E, /* ^ */
160 ASCII_underscore = 0x5F, /* _ */
161 ASCII_leftApostrophe = 0x60, /* ` */
188 ASCII_leftCurlyBrace = 0x7B, /* { */
189 ASCII_verticalBar = 0x7C, /* | */
190 ASCII_rightCurlyBrace = 0x7D, /* } */
191 ASCII_tilde = 0x7E /* ~ */
192 } EVT_asciiCodesType;
194 /****************************************************************************
196 Defines the set of scan codes reported by the event library functions
197 in the message field. Use the EVT_scanCode macro to extract the code
198 from the event structure. Note that the scan codes reported will be the
199 same across all keyboards (assuming the placement of keys on a 101 key US
200 keyboard), but the translated ASCII values may be different depending on
201 the country code pages in use.
203 NOTE: Scan codes in the event library are not really hardware scan codes,
204 but rather virtual scan codes as generated by a low level keyboard
205 interface driver. All virtual codes begin with scan code 0x60 and
210 ****************************************************************************/
212 KB_padEnter = 0x60, /* Keypad keys */
226 KB_padPageDown = 0x6B,
228 KB_F1 = 0x3B, /* Function keys */
240 KB_left = 0x4B, /* Cursor control keys */
252 KB_scrollLock = 0x46,
254 KB_rightShift = 0x36,
259 KB_leftWindows = 0x5B,
260 KB_rightWindows = 0x5C,
263 KB_esc = 0x01, /* Normal keyboard keys */
289 KB_leftSquareBrace = 0x1A,
290 KB_rightSquareBrace = 0x1B,
302 KB_apostrophe = 0x28,
317 /****************************************************************************
319 Defines the mask for the joystick axes that are present
325 EVT_JOY_AXIS_X1 - Joystick 1, X axis is present
326 EVT_JOY_AXIS_Y1 - Joystick 1, Y axis is present
327 EVT_JOY_AXIS_X2 - Joystick 2, X axis is present
328 EVT_JOY_AXIS_Y2 - Joystick 2, Y axis is present
329 EVT_JOY_AXIS_ALL - Mask for all axes
330 ****************************************************************************/
332 EVT_JOY_AXIS_X1 = 0x00000001,
333 EVT_JOY_AXIS_Y1 = 0x00000002,
334 EVT_JOY_AXIS_X2 = 0x00000004,
335 EVT_JOY_AXIS_Y2 = 0x00000008,
336 EVT_JOY_AXIS_ALL = 0x0000000F
337 } EVT_eventJoyAxisType;
339 /****************************************************************************
341 Defines the event message masks for joystick events
347 EVT_JOY1_BUTTONA - Joystick 1, button A is down
348 EVT_JOY1_BUTTONB - Joystick 1, button B is down
349 EVT_JOY2_BUTTONA - Joystick 2, button A is down
350 EVT_JOY2_BUTTONB - Joystick 2, button B is down
351 ****************************************************************************/
353 EVT_JOY1_BUTTONA = 0x00000001,
354 EVT_JOY1_BUTTONB = 0x00000002,
355 EVT_JOY2_BUTTONA = 0x00000004,
356 EVT_JOY2_BUTTONB = 0x00000008
357 } EVT_eventJoyMaskType;
359 /****************************************************************************
361 Defines the event message masks for mouse events
367 EVT_LEFTBMASK - Left button is held down
368 EVT_RIGHTBMASK - Right button is held down
369 EVT_MIDDLEBMASK - Middle button is held down
370 EVT_BOTHBMASK - Both left and right held down together
371 EVT_ALLBMASK - All buttons pressed
372 EVT_DBLCLICK - Set if mouse down event was a double click
373 ****************************************************************************/
375 EVT_LEFTBMASK = 0x00000001,
376 EVT_RIGHTBMASK = 0x00000002,
377 EVT_MIDDLEBMASK = 0x00000004,
378 EVT_BOTHBMASK = 0x00000007,
379 EVT_ALLBMASK = 0x00000007,
380 EVT_DBLCLICK = 0x00010000
381 } EVT_eventMouseMaskType;
383 /****************************************************************************
385 Defines the event modifier masks. These are the masks used to extract
386 the modifier information from the modifiers field of the event_t structure.
387 Note that the values in the modifiers field represent the values of these
388 modifier keys at the time the event occurred, not the time you decided
389 to process the event.
395 EVT_LEFTBUT - Set if left mouse button was down
396 EVT_RIGHTBUT - Set if right mouse button was down
397 EVT_MIDDLEBUT - Set if the middle button was down
398 EVT_RIGHTSHIFT - Set if right shift was down
399 EVT_LEFTSHIFT - Set if left shift was down
400 EVT_RIGHTCTRL - Set if right ctrl key was down
401 EVT_RIGHTALT - Set if right alt key was down
402 EVT_LEFTCTRL - Set if left ctrl key was down
403 EVT_LEFTALT - Set if left alt key was down
404 EVT_SHIFTKEY - Mask for any shift key down
405 EVT_CTRLSTATE - Set if ctrl key was down
406 EVT_ALTSTATE - Set if alt key was down
407 EVT_CAPSLOCK - Caps lock is active
408 EVT_NUMLOCK - Num lock is active
409 EVT_SCROLLLOCK - Scroll lock is active
410 ****************************************************************************/
412 EVT_LEFTBUT = 0x00000001,
413 EVT_RIGHTBUT = 0x00000002,
414 EVT_MIDDLEBUT = 0x00000004,
415 EVT_RIGHTSHIFT = 0x00000008,
416 EVT_LEFTSHIFT = 0x00000010,
417 EVT_RIGHTCTRL = 0x00000020,
418 EVT_RIGHTALT = 0x00000040,
419 EVT_LEFTCTRL = 0x00000080,
420 EVT_LEFTALT = 0x00000100,
421 EVT_SHIFTKEY = 0x00000018,
422 EVT_CTRLSTATE = 0x000000A0,
423 EVT_ALTSTATE = 0x00000140,
424 EVT_SCROLLLOCK = 0x00000200,
425 EVT_NUMLOCK = 0x00000400,
426 EVT_CAPSLOCK = 0x00000800
427 } EVT_eventModMaskType;
429 /****************************************************************************
431 Defines the event codes returned in the event_t structures what field. Note
432 that these are defined as a set of mutually exlusive bit fields, so you
433 can test for multiple event types using the combined event masks defined
434 in the EVT_eventMaskType enumeration.
440 EVT_NULLEVT - A null event
441 EVT_KEYDOWN - Key down event
442 EVT_KEYREPEAT - Key repeat event
443 EVT_KEYUP - Key up event
444 EVT_MOUSEDOWN - Mouse down event
445 EVT_MOUSEAUTO - Mouse down autorepeat event
446 EVT_MOUSEUP - Mouse up event
447 EVT_MOUSEMOVE - Mouse movement event
448 EVT_JOYCLICK - Joystick button state change event
449 EVT_JOYMOVE - Joystick movement event
450 EVT_USEREVT - First user event
451 ****************************************************************************/
453 EVT_NULLEVT = 0x00000000,
454 EVT_KEYDOWN = 0x00000001,
455 EVT_KEYREPEAT = 0x00000002,
456 EVT_KEYUP = 0x00000004,
457 EVT_MOUSEDOWN = 0x00000008,
458 EVT_MOUSEAUTO = 0x00000010,
459 EVT_MOUSEUP = 0x00000020,
460 EVT_MOUSEMOVE = 0x00000040,
461 EVT_JOYCLICK = 0x00000080,
462 EVT_JOYMOVE = 0x00000100,
463 EVT_USEREVT = 0x00000200
466 /****************************************************************************
468 Defines the event code masks you can use to test for multiple types of
469 events, since the event codes are mutually exlusive bit fields.
475 EVT_KEYEVT - Mask for any key event
476 EVT_MOUSEEVT - Mask for any mouse event
477 EVT_MOUSECLICK - Mask for any mouse click event
478 EVT_JOYEVT - Mask for any joystick event
479 EVT_EVERYEVT - Mask for any event
480 ****************************************************************************/
482 EVT_KEYEVT = (EVT_KEYDOWN | EVT_KEYREPEAT | EVT_KEYUP),
483 EVT_MOUSEEVT = (EVT_MOUSEDOWN | EVT_MOUSEAUTO | EVT_MOUSEUP | EVT_MOUSEMOVE),
484 EVT_MOUSECLICK = (EVT_MOUSEDOWN | EVT_MOUSEUP),
485 EVT_JOYEVT = (EVT_JOYCLICK | EVT_JOYMOVE),
486 EVT_EVERYEVT = 0x7FFFFFFF
489 /****************************************************************************
491 Structure describing the information contained in an event extracted from
498 which - Window identifier for message for use by high level window manager
499 code (i.e. MegaVision GUI or Windows API).
500 what - Type of event that occurred. Will be one of the values defined by
501 the EVT_eventType enumeration.
502 when - Time that the event occurred in milliseconds since startup
503 where_x - X coordinate of the mouse cursor location at the time of the event
504 (in screen coordinates). For joystick events this represents
505 the position of the first joystick X axis.
506 where_y - Y coordinate of the mouse cursor location at the time of the event
507 (in screen coordinates). For joystick events this represents
508 the position of the first joystick Y axis.
509 relative_x - Relative movement of the mouse cursor in the X direction (in
510 units of mickeys, or 1/200th of an inch). For joystick events
511 this represents the position of the second joystick X axis.
512 relative_y - Relative movement of the mouse cursor in the Y direction (in
513 units of mickeys, or 1/200th of an inch). For joystick events
514 this represents the position of the second joystick Y axis.
515 message - Event specific message for the event. For use events this can be
516 any user specific information. For keyboard events this contains
517 the ASCII code in bits 0-7, the keyboard scan code in bits 8-15 and
518 the character repeat count in bits 16-30. You can use the
519 EVT_asciiCode, EVT_scanCode and EVT_repeatCount macros to extract
520 this information from the message field. For mouse events this
521 contains information about which button was pressed, and will be a
522 combination of the flags defined by the EVT_eventMouseMaskType
523 enumeration. For joystick events, this conatins information
524 about which buttons were pressed, and will be a combination of
525 the flags defined by the EVT_eventJoyMaskType enumeration.
526 modifiers - Contains additional information about the state of the keyboard
527 shift modifiers (Ctrl, Alt and Shift keys) when the event
528 occurred. For mouse events it will also contain the state of
529 the mouse buttons. Will be a combination of the values defined
530 by the EVT_eventModMaskType enumeration.
531 next - Internal use; do not use.
532 prev - Internal use; do not use.
533 ****************************************************************************/
548 /****************************************************************************
550 Structure describing an entry in the code page table. A table of translation
551 codes for scan codes to ASCII codes is provided in this table to be used
552 by the keyboard event libraries. On some OS'es the keyboard translation is
553 handled by the OS, but for DOS and embedded systems you must register a
554 different code page translation table if you want to support keyboards
555 other than the US English keyboard (the default).
557 NOTE: Entries in code page tables *must* be in ascending order for the
558 scan codes as we do a binary search on the tables for the ASCII
565 scanCode - Scan code to translate (really the virtual scan code).
566 asciiCode - ASCII code for this scan code.
567 ****************************************************************************/
573 /****************************************************************************
575 Structure describing a complete code page translation table. The table
576 contains translation tables for normal keys, shifted keys and ctrl keys.
577 The Ctrl key always has precedence over the shift table, and the shift
578 table is used when the shift key is down or the CAPSLOCK key is down.
584 name - Name of the code page table (ie: "US English")
585 normal - Code page for translating normal keys
586 normalLen - Length of normal translation table
587 caps - Code page for translating keys when CAPSLOCK is down
588 capsLen - Length of CAPSLOCK translation table
589 shift - Code page for shifted keys (ie: shift key is held down)
590 shiftLen - Length of shifted translation table
591 shiftCaps - Code page for shifted keys when CAPSLOCK is down
592 shiftCapsLen - Length of shifted CAPSLOCK translation table
593 ctrl - Code page for ctrl'ed keys (ie: ctrl key is held down)
594 ctrlLen - Length of ctrl'ed translation table
595 numPad - Code page for NUMLOCK'ed keypad keys
596 numPadLen - Length of NUMLOCK'ed translation table
597 ****************************************************************************/
600 codepage_entry_t *normal;
602 codepage_entry_t *caps;
604 codepage_entry_t *shift;
606 codepage_entry_t *shiftCaps;
608 codepage_entry_t *ctrl;
610 codepage_entry_t *numPad;
615 typedef ibool (EVTAPIP _EVT_userEventFilter)(event_t *evt);
617 typedef void (EVTAPIP _EVT_mouseMoveHandler)(int x,int y);
619 typedef void (EVTAPIP _EVT_heartBeatCallback)(void *params);
621 /* Macro to find the size of a static array */
623 #define EVT_ARR_SIZE(a) (sizeof(a)/sizeof((a)[0]))
627 /*--------------------------- Global variables ----------------------------*/
630 extern "C" { /* Use "C" linkage when in C++ mode */
633 /* Standard code page tables */
635 extern codepage_t _CP_US_English;
637 /*------------------------- Function Prototypes ---------------------------*/
639 /* Public API functions for user applications */
641 ibool EVTAPI EVT_getNext(event_t *evt,ulong mask);
642 ibool EVTAPI EVT_peekNext(event_t *evt,ulong mask);
643 ibool EVTAPI EVT_post(ulong which,ulong what,ulong message,ulong modifiers);
644 void EVTAPI EVT_flush(ulong mask);
645 void EVTAPI EVT_halt(event_t *evt,ulong mask);
646 ibool EVTAPI EVT_isKeyDown(uchar scanCode);
647 void EVTAPI EVT_setMousePos(int x,int y);
648 void EVTAPI EVT_getMousePos(int *x,int *y);
650 /* Function to enable/disable updating of keyboard LED status indicators */
652 void EVTAPI EVT_allowLEDS(ibool enable);
654 /* Function to install a custom keyboard code page. Default is US English */
656 codepage_t *EVTAPI EVT_getCodePage(void);
657 void EVTAPI EVT_setCodePage(codepage_t *page);
659 /* Functions for fine grained joystick calibration */
661 void EVTAPI EVT_pollJoystick(void);
662 int EVTAPI EVT_joyIsPresent(void);
663 void EVTAPI EVT_joySetUpperLeft(void);
664 void EVTAPI EVT_joySetLowerRight(void);
665 void EVTAPI EVT_joySetCenter(void);
667 /* Install user supplied event filter callback */
669 void EVTAPI EVT_setUserEventFilter(_EVT_userEventFilter filter);
671 /* Install user supplied event heartbeat callback function */
673 void EVTAPI EVT_setHeartBeatCallback(_EVT_heartBeatCallback callback,void *params);
674 void EVTAPI EVT_getHeartBeatCallback(_EVT_heartBeatCallback *callback,void **params);
676 /* Internal functions to initialise and kill the event manager. MGL
677 * applications should never call these functions directly as the MGL
678 * libraries do it for you.
682 void EVTAPI EVT_init(_EVT_mouseMoveHandler mouseMove);
684 void EVTAPI EVT_setMouseRange(int xRes,int yRes);
686 void EVTAPI EVT_suspend(void);
688 void EVTAPI EVT_resume(void);
690 void EVTAPI EVT_exit(void);
693 } /* End of "C" linkage for C++ */
694 #endif /* __cplusplus */
696 #endif /* __EVENT_H */