Previous  Up  Next

Module Sdl.Event


module Event: sig .. end
Event handling allows the application to receive input from the user.

Event handling is initalised (along with video) with a call to init [VIDEO]

Internally, SDL stores all the events waiting to be handled in an event queue. Using functions like poll_event, peep_events and wait_event you can observe and handle waiting input events.

The key to event handling in SDL is the event type. The event queue itself is composed of a series of events, one for each waiting event. events are read from the queue with the poll_event function and it is then up to the application to process the information stored with them.


type que_dis_ena =
| QUERY
| DISABLE
| ENABLE
Query, Enable or Disable flags

type off_on =
| OFF
| ON
On\Off flags
type pointer
Pointer for user-defined event data

type app_state =
| APPMOUSEFOCUS
| APPINPUTFOCUS
| APPACTIVE
Application state: application has mouse focus, input focus, active
val get_app_state : unit -> app_state list
get_app_state -> app_state list

This function returns the current state of the application. The value returned is list containing one or more of: APPMOUSEFOCUS The application has mouse focus. APPINPUTFOCUS The application has keyboard focus APPACTIVE The application is visible


type key =
| K_UNKNOWN
| K_FIRST
| K_BACKSPACE
| K_TAB
| K_CLEAR
| K_RETURN
| K_PAUSE
| K_ESCAPE
| K_SPACE
| K_EXCLAIM
| K_QUOTEDBL
| K_HASH
| K_DOLLAR
| K_AMPERSAND
| K_QUOTE
| K_LEFTPAREN
| K_RIGHTPAREN
| K_ASTERISK
| K_PLUS
| K_COMMA
| K_MINUS
| K_PERIOD
| K_SLASH
| K_0
| K_1
| K_2
| K_3
| K_4
| K_5
| K_6
| K_7
| K_8
| K_9
| K_COLON
| K_SEMICOLON
| K_LESS
| K_EQUALS
| K_GREATER
| K_QUESTION
| K_AT
| K_LEFTBRACKET
| K_BACKSLASH
| K_RIGHTBRACKET
| K_CARET
| K_UNDERSCORE
| K_BACKQUOTE
| K_A
| K_B
| K_C
| K_D
| K_E
| K_F
| K_G
| K_H
| K_I
| K_J
| K_K
| K_L
| K_M
| K_N
| K_O
| K_P
| K_Q
| K_R
| K_S
| K_T
| K_U
| K_V
| K_W
| K_X
| K_Y
| K_Z
| K_DELETE
| K_WORLD_0
| K_WORLD_1
| K_WORLD_2
| K_WORLD_3
| K_WORLD_4
| K_WORLD_5
| K_WORLD_6
| K_WORLD_7
| K_WORLD_8
| K_WORLD_9
| K_WORLD_10
| K_WORLD_11
| K_WORLD_12
| K_WORLD_13
| K_WORLD_14
| K_WORLD_15
| K_WORLD_16
| K_WORLD_17
| K_WORLD_18
| K_WORLD_19
| K_WORLD_20
| K_WORLD_21
| K_WORLD_22
| K_WORLD_23
| K_WORLD_24
| K_WORLD_25
| K_WORLD_26
| K_WORLD_27
| K_WORLD_28
| K_WORLD_29
| K_WORLD_30
| K_WORLD_31
| K_WORLD_32
| K_WORLD_33
| K_WORLD_34
| K_WORLD_35
| K_WORLD_36
| K_WORLD_37
| K_WORLD_38
| K_WORLD_39
| K_WORLD_40
| K_WORLD_41
| K_WORLD_42
| K_WORLD_43
| K_WORLD_44
| K_WORLD_45
| K_WORLD_46
| K_WORLD_47
| K_WORLD_48
| K_WORLD_49
| K_WORLD_50
| K_WORLD_51
| K_WORLD_52
| K_WORLD_53
| K_WORLD_54
| K_WORLD_55
| K_WORLD_56
| K_WORLD_57
| K_WORLD_58
| K_WORLD_59
| K_WORLD_60
| K_WORLD_61
| K_WORLD_62
| K_WORLD_63
| K_WORLD_64
| K_WORLD_65
| K_WORLD_66
| K_WORLD_67
| K_WORLD_68
| K_WORLD_69
| K_WORLD_70
| K_WORLD_71
| K_WORLD_72
| K_WORLD_73
| K_WORLD_74
| K_WORLD_75
| K_WORLD_76
| K_WORLD_77
| K_WORLD_78
| K_WORLD_79
| K_WORLD_80
| K_WORLD_81
| K_WORLD_82
| K_WORLD_83
| K_WORLD_84
| K_WORLD_85
| K_WORLD_86
| K_WORLD_87
| K_WORLD_88
| K_WORLD_89
| K_WORLD_90
| K_WORLD_91
| K_WORLD_92
| K_WORLD_93
| K_WORLD_94
| K_WORLD_95
| K_KP0
| K_KP1
| K_KP2
| K_KP3
| K_KP4
| K_KP5
| K_KP6
| K_KP7
| K_KP8
| K_KP9
| K_KP_PERIOD
| K_KP_DIVIDE
| K_KP_MULTIPLY
| K_KP_MINUS
| K_KP_PLUS
| K_KP_ENTER
| K_KP_EQUALS
| K_UP
| K_DOWN
| K_RIGHT
| K_LEFT
| K_INSERT
| K_HOME
| K_END
| K_PAGEUP
| K_PAGEDOWN
| K_F1
| K_F2
| K_F3
| K_F5
| K_F6
| K_F7
| K_F8
| K_F9
| K_F10
| K_F11
| K_F12
| K_F13
| K_F14
| K_F15
| K_NUMLOCK
| K_CAPSLOCK
| K_SCROLLLOCK
| K_RSHIFT
| K_LSHIFT
| K_RCTRL
| K_LCTRL
| K_RALT
| K_LAT
| K_RMETA
| K_LMETA
| K_LSUPER
| K_RSUPER
| K_MODE
| K_COMPOSE
| K_HELP
| K_PRINT
| K_SYSREQ
| K_BREAK
| K_MENU
| K_POWER
| K_EURO
SDLKey enum

An enumeration of keysym definitions.

Note : A lot of the keysyms are unavailable on most keyboards. For example, the K_1 keysym can't be accessed on a french keyboard. You get the K_AMPERSAND instead. So, you should not hardcode any keysym unless it's one of the universal keys that are available on all keyboards. Also, remember that the position of the letters can vary and so, although all of them are available on most keyboards, their position might not be practical for your application.

And at last, never ever ever write your own custom ASCII conversion table. If you do that, you'll get angry non US users that will pester you to fix the keyboard handling for them, one for each keyboard layout existing in the world. If you want to know the symbol entered by the user, the keyboard_event event is the good place to do it.


type key_mod =
| KMOD_NONE
| KMOD_LSHIFT
| KMOD_RSHIFT
| KMOD_LCTRL
| KMOD_RCTRL
| KMOD_LALT
| KMOD_RALT
| KMOD_LMETA
| KMOD_RMETA
| KMOD_NUM
| KMOD_CAPS
| KMOD_MODE
| KMOD_RESERVED
SDLMod enum

An enumeration of key modifier definitions.

val enable_unicode : que_dis_ena -> off_on
enable_unicode query/disable/enable -> on/off

Enables/Disables Unicode keyboard translation.

To obtain the character codes corresponding to received keyboard events, Unicode translation must first be turned on using this function. The translation incurs a slight overhead for each keyboard event and is therefore disabled by default. For each subsequently received key down event, the unicode member of the keyboard_event structure will then contain the corresponding character code, or zero for key syms that do not correspond to any character code.

ENABLE enables Unicode translation; DISABLE disables it, and QUERY leaves it unchanged (useful for querying the current translation mode).

Note that only key press events will be translated, not release events.

val default_repeat_delay : int
Default keyboard repeat delay
val default_repeat_interval : int
Default keyboard repeat interval
val enable_key_repeat : int -> int -> unit
enable_key_repeat repeat_delay repeat_interval

Enables or disables the keyboard repeat rate. delay specifies how long the key must be pressed before it begins repeating, it then repeats at the speed specified by interval. Both delay and interval are expressed in milliseconds. Setting delay to 0 disables key repeating completely. Good default values are default_repeat_delay and default_repeat_interval

val get_mod_state : unit -> key_mod list
get_mod_state -> key_mod list

Returns a list of the current state of the modifier keys (CTRL, ALT, etc.).

val set_mod_state : key_mod list -> unit
set_mod_state key_mod list

Sets the current state of the modifier keys (CTRL, ALT, etc.) in the input list.

val get_key_name : key -> string
get_key_name key keyname

Returns the SDL-defined name of the key in key


type event_type =
| NOEVENT
| ACTIVEEVENT
| KEYDOWN
| KEYUP
| MOUSEMOTION
| MOUSEBUTTONDOWN
| MOUSEBUTTONUP
| JOYAXISMOTION
| JOYBALLMOTION
| JOYHATMOTION
| JOYBUTTONDOWN
| JOYBUTTONUP
| QUIT
| SYSWMEVENT
| EVENT_RESERVEDA
| EVENT_RESERVEDB
| VIDEORESIZE
| VIDEOEXPOSE
| EVENT_RESERVED2
| EVENT_RESERVED3
| EVENT_RESERVED4
| EVENT_RESERVED5
| EVENT_RESERVED6
| EVENT_RESERVED7
| USEREVENT
Event enum

type press_release =
| RELEASED
| PRESSED
Released/Pressed

type lost_gained =
| LOST
| GAINED
Focus lost/gained

type active_event = {
   focus : lost_gained;
   state : app_state;
}
Active event type, containing the application state and focus

type keyboard_event = {
   keystate : press_release; (*The key state (PRESSED or RELEASED)*)
   scancode : int; (*The key scan code*)
   sym : key; (*The key sym*)
   modifiers : key_mod list; (*Key modifiers (CTRL, ALT etc)*)
   unicode : int; (*Unicode respresentation of key*)
}
Keyboard event type

type mouse_button =
| LEFT
| MIDDLE
| RIGHT
| WHEELUP
| WHEELDOWN
Mouse button types: left, right, middle, and the scroll wheel (up or down)

type mouse_motion_event = {
   mousestate : press_release; (*The mouse button state (PRESSED or RELEASED)*)
   x : int; (*x coordinate of cursor*)
   y : int; (*y coordinate of cursor*)
   xrel : int; (*Amount in x coordinate moved since last mouse motion event*)
   yrel : int; (*Amount in y coordinate moved since last mouse motion event*)
}
Mouse motion event

type mouse_button_event = {
   mousebutton : mouse_button; (*left, right, middle, and the scroll wheel (up or down)*)
   buttonstate : press_release; (*Pressed\Released*)
   x : int; (*x coordinate of cursor*)
   y : int; (*y coordinate of cursor*)
}
Mouse button event

type joy_axis_event = {
   which_axis : int; (*Which joystick generated the event*)
   axis : int; (*Which joystick axis, X (0) or Y (1)*)
   value : int; (*The current position along that axis*)
}
Joystick axis event

type joy_ball_event = {
   which_ball : int; (*Which joystick generated the event*)
   ball : int; (*Which joystick ball*)
   xrel : int; (*Amount in x coordinate moved since last joystick ball event*)
   yrel : int; (*Amount in y coordinate moved since last joystick ball event*)
}
Joystick ball event

type joy_hat_event = {
   which_hat : int; (*Which joystick generated the event*)
   hat : int; (*Which joystick hat*)
   value : int; (*The current hat position*)
}
Joystick hat event

type joy_button_event = {
   which_button : int; (*Which joystick generated the event*)
   joybutton : int; (*Which joystick button*)
   state : press_release; (*Pressed\Released*)
}
Joystick button event

type resize_event = {
   w : int; (*New width*)
   h : int; (*New height*)
}
Window resize event

type user_event = {
   code : int;
   data1 : pointer;
   data2 : pointer;
}
User defined SDL event type
type sys_wm_event
tsyswmevent not implemented in trial version

type event =
| NoEvent
| Active of active_event (*Activation event*)
| Key of keyboard_event (*Keyboard event*)
| Motion of mouse_motion_event (*Mouse motion event*)
| Button of mouse_button_event (*Mouse button event*)
| Jaxis of joy_axis_event (*Joystick axis motion event*)
| Jball of joy_ball_event (*Joystick trackball motion event*)
| Jhat of joy_hat_event (*Joystick hat motion event*)
| Jbutton of joy_button_event (*Joystick button event*)
| Resize of resize_event (*Application window resize event*)
| Expose (*Application window expose event*)
| Quit (*Application quit request event*)
| User of user_event (*User defined event*)
| Syswm of sys_wm_event (*Undefined window manager event*)
event type
val pump_events : unit -> unit
pump_events

Pumps the event loop, gathering events from the input devices.

pump_events gathers all the pending input information from devices and places it on the event queue. Without calls to pump_events no events would ever be placed on the queue. Often the need for calls to pump_events is hidden from the user since poll_event and wait_event implicitly call pump_events. However, if you are not polling or waiting for events (e.g. you are filtering them), then you must call pump_events to force an event queue update.

Note: You can only call this function in the thread that set the video mode.

val poll_event : unit -> event
poll_event -> event

Polls for currently pending events. If there are any events, the next event is removed from the queue and stored in the event structure pointed to by event.

val wait_event : unit -> event
wait_event -> event

Waits indefinitely for the next available event,

If there are any events, the next event is removed from the queue and stored in that area.

val event_state : event_type -> que_dis_ena -> off_on
event_state event_type state -> on\off

This function allows you to set the state of processing certain event types.

If state is set to DISABLE, that event type will be automatically dropped from the event queue and will not be filtered.

If state is set to ENABLE, that event type will be processed normally.

If state is set to QUERY, event_state will return the current processing state of the specified event type.