---
name: "SDLmm_EventHandler"
section: "3"
platform: "linux"
package: "libsdl-mm0.1"
version: "0.1.8-4"
release: "Debian 3.0 (Woody)"
platforms: ["linux"]
url: "https://new.carta.tech/SDLmm_EventHandler"
---

# SDLmm\_EventHandler(3)

The base class used for custom Event handlers.

## NAME

SDLmm::EventHandler - The base class used for custom **Event** handlers.

## SYNOPSIS

`#include <sdlmm_eventhandler.h>`

### Public Methods

virtual bool **HandleEvent** (SDL\_Event &event)\
 *Catch-all event handler.*

**Keyboard Events**\

virtual bool **HandleKeyboardEvent** (SDL\_keysym &keysym, bool pressed)\
 *Keyboard event callback.* virtual bool **HandleKeyPressEvent** (SDL\_keysym &keysym)\
 *Keyboard press event callback.* virtual bool **HandleKeyReleaseEvent** (SDL\_keysym &keysym)\
 *Keyboard release event callback.*

**Mouse Events**\

virtual bool **HandleMouseMotionEvent** (Uint8 state, Uint16 x, Uint16 y, Sint16 xrel, Sint16 yrel)\
 *Mouse motion event callback.* virtual bool **HandleMouseButtonEvent** (Uint8 button, Uint16 x, Uint16 y, bool pressed)\
 *Mouse button event callback.* virtual bool **HandleMouseButtonPressEvent** (Uint8 button, Uint16 x, Uint16 y)\
 *Mouse button press event callback.* virtual bool **HandleMouseButtonReleaseEvent** (Uint8 button, Uint16 x, Uint16 y)\
 *Mouse button release event callback.*

**Joystick Events**\

virtual bool **HandleJoyAxisEvent** (Uint8 joystick, Uint8 axis, Sint16 value)\
 **Joystick** *axis motion event callback.* virtual bool **HandleJoyButtonEvent** (Uint8 joystick, Uint8 button, bool pressed)\
 **Joystick** *button event callback.* virtual bool **HandleJoyButtonPressEvent** (Uint8 joystick, Uint8 button)\
 **Joystick** *button press event callback.* virtual bool **HandleJoyButtonReleaseEvent** (Uint8 joystick, Uint8 button)\
 **Joystick** *button release event callback.* virtual bool **HandleJoyHatEvent** (Uint8 joystick, Uint8 hat, Uint8 value)\
 **Joystick** *hat position change event callback.* virtual bool **HandleJoyBallEvent** (Uint8 joystick, Uint8 ball, Sint16 xrel, Sint16 yrel)\
 **Joystick** *trackball motion event callback.*

**Window / Display Events**\

virtual bool **HandleActiveEvent** (bool gain, Uint8 state)\
 *Application visibility event callback.* virtual bool **HandleResizeEvent** (int w, int h)\
 *Window resize event callback.* virtual bool **HandleSysWMEvent** ()\
 *Platform-dependent window manager event callback.*

**Other Events**\

virtual bool **HandleUserEvent** (Uint8 type, int code, void \*data1, void \*data2)\
 virtual bool **HandleQuitEvent** ()\
 *Quit requested event callback.*

## DETAILED DESCRIPTION

The base class used for custom **Event** handlers.

The event handling in **SDLmm** is rather different to that of SDL in  that it uses classes derived from the **EventHandler**. This allows for clean, type-safe code much closer to the spirit of C++ than the use of a union with a type field. To handle one or more events, you simply build a class derived from this, reimplementing the only functions for the events you need to handle.

**See also:**  **Event::HandleEvents**()

## MEMBER FUNCTION DOCUMENTATION

### bool SDLmm::EventHandler::HandleActiveEvent (bool gain, Uint8 state)` [inline, virtual]`

Application visibility event callback.

This callback is called when an event of type SDL\_ACTIVEEVENT is reported.

When the mouse leaves or enters the window area a SDL\_APPMOUSEFOCUS type activation event occurs, if the mouse entered the window then *gain* will be true, otherwise *gain* will be false. A SDL\_APPINPUTFOCUS type activation event occurs when the application loses or gains keyboard focus. This usually occurs when another application is made active. Finally, a SDL\_APPACTIVE *type* event occurs when the application is either minimised/iconified (*gain=false)* or restored.

**Parameters:**

- *gain*

  *false if the event is a loss or true if it's a gain*

- *state*

  *SDL\_APPMOUSEFOCUS if mouse focus was gained or lost, SDL\_APPINPUTFOCUS if input focus was gained or lost, or SDL\_APPACTIVE if the application was iconified (gain=false) or restored (gain=true)*

**Returns:**  *true if the event was handled, false if it was not. If the event wasn't handled, it will be handed over to the generic* **HandleEvent***() method.*

### bool SDLmm::EventHandler::HandleEvent (SDL\_Event & event)` [inline, virtual]`

*Catch-all event handler.*

*This method is called if none of the event specific callbacks handled event (i.e they returned false).*

**Note:**  *It's both easier and more efficient to use the event-specific callbacks, so unless you really want to do all the work yourself, you want to use those.*

**Parameters:**

- *event*

  *the current event*

**Returns:**  *true if the event was handled, false if it was not*

### bool SDLmm::EventHandler::HandleJoyAxisEvent (Uint8 joystick, Uint8 axis, Sint16 value)` [inline, virtual]`

**Joystick** *axis motion event callback.*

*This is used when an event of type SDL\_JOYAXISMOTION is reported.*

*A SDL\_JOYAXISMOTION event occurs when ever a user moves an axis on the joystick.*

**Parameters:**

- *joystick*

  *the index of the joystick that reported the event*

- *axis*

  *the index of the axis (for a more detailed explaination see the* **Joystick** *section of the SDL manual).*

**ams value is the current position of the axis.**

**Returns:**  *true if the event was handled, false if it was not. If the event wasn't handled, it will be handed over to the generic* **HandleEvent***() method.*

### bool SDLmm::EventHandler::HandleJoyBallEvent (Uint8 joystick, Uint8 ball, Sint16 xrel, Sint16 yrel)` [inline, virtual]`

**Joystick** *trackball motion event callback.*

*Thyis is used when an event of type SDL\_JOYBALLMOTION is reported.*

*A SDL\_JOYBALLMOTION event occurs when a user moves a trackball on the joystick. The field joystick is the index of the joystick that reported the event and ball is the index of the trackball (for a more detailed explaination see the* **Joystick** *section in the SDL documentation). Trackballs only return relative motion, this is the change in position on the ball since it was last polled (last cycle of the event loop) and it is stored in xrel and yrel.*

**Parameters:**

- *joystick*

  *joystick device index*

- *ball*

  *joystick trackbal index*

- *xrel, yrel*

  *relative motion in the x/y directions*

**Returns:**  *true if the event was handled, false if it was not. If the event wasn't handled, it will be handed over to the generic* **HandleEvent***() method.*

### bool SDLmm::EventHandler::HandleJoyButtonEvent (Uint8 joystick, Uint8 button, bool pressed)` [inline, virtual]`

**Joystick** *button event callback.*

*This is used when an event of type SDL\_JOYBUTTONDOWN or SDL\_JOYBUTTONUP is reported.*

*These events occurs when ever a user presses or releases a button on a joystick.*

**Note:**  *This function is only called if the default* **HandleJoyButtonPressEvent***() and / or* **HandleJoyButtonReleaseEvent***() methods are used.*

**Parameters:**

- *joystick*

  *the index of the joystick that reported the event*

- *button*

  *the index of the pressed button (for a more detailed explaination see the* **Joystick** *section of the SDL manual).*

- *pressed*

  *true for SDL\_JOYBUTTONDOWN, false for SDL\_JOYBUTTONUP.*

**Returns:**  *true if the event was handled, false if it was not. If the event wasn't handled, it will be handed over to the generic* **HandleEvent***() method.*

### bool SDLmm::EventHandler::HandleJoyButtonPressEvent (Uint8 joystick, Uint8 button)` [inline, virtual]`

**Joystick** *button press event callback.*

*This is used when an event of type SDL\_JOYBUTTONDOWN is reported.*

*A SDL\_JOYBUTTONDOWN event occurs when ever a user presses a button on a joystick.*

**Note:**  *The default declaration of this method calls the* **HandleJoyButtonEvent***() method. If you want to handle both button presses and releases in the same method, just redefine* **HandleJoyButtonEvent***().*

**Parameters:**

- *joystick*

  *the index of the joystick that reported the event*

- *button*

  *the index of the pressed button (for a more detailed explaination see the* **Joystick** *section of the SDL manual).*

**Returns:**  *true if the event was handled, false if it was not. If the event wasn't handled, it will be handed over to the generic* **HandleEvent***() method.*

### bool SDLmm::EventHandler::HandleJoyButtonReleaseEvent (Uint8 joystick, Uint8 button)` [inline, virtual]`

**Joystick** *button release event callback.*

*This is used when an event of type SDL\_JOYBUTTONUP is reported.*

*A SDL\_JOYBUTTONUP event occurs when ever a user releases a button on a joystick.*

**Note:**  *The default declaration of this method calls the* **HandleJoyButtonEvent***() method. If you want to handle both button presses and releases in the same method, just redefine* **HandleJoyButtonEvent***().*

**Parameters:**

- *joystick*

  *the index of the joystick that reported the event*

- *button*

  *the index of the released button (for a more detailed explaination see the* **Joystick** *section of the SDL manual).*

**Returns:**  *true if the event was handled, false if it was not. If the event wasn't handled, it will be handed over to the generic* **HandleEvent***() method.*

### bool SDLmm::EventHandler::HandleJoyHatEvent (Uint8 joystick, Uint8 hat, Uint8 value)` [inline, virtual]`

**Joystick** *hat position change event callback.*

*This is used when an event of type SDL\_JOYHATMOTION is reported.*

*A SDL\_JOYHATMOTION event occurs when ever a user moves a hat on the joystick. The field joystick is the index of the joystick that reported the event and hat is the index of the hat (for a more detailed exlaination see the* **Joystick** *section in the SDL documentation). value is the current position of the hat. It is a logically OR'd combination of the following values (whose meanings should be pretty obvious):*

- *SDL\_HAT\_CENTERED*

  - *SDL\_HAT\_UP*

  - *SDL\_HAT\_RIGHT*

  - *SDL\_HAT\_DOWN*

  - *SDL\_HAT\_LEFT*

  *The following defines are also provided:*

- *SDL\_HAT\_RIGHTUP*

  - *SDL\_HAT\_RIGHTDOWN*

  - *SDL\_HAT\_LEFTUP*

  - *SDL\_HAT\_LEFTDOWN*

  **Parameters:**

- *joystick*

  *joystick device index*

- *hat*

  *joystick hat index*

- *value*

  *hat position*

**Returns:**  *true if the event was handled, false if it was not. If the event wasn't handled, it will be handed over to the generic* **HandleEvent***() method.*

### bool SDLmm::EventHandler::HandleKeyPressEvent (SDL\_keysym & keysym)` [inline, virtual]`

*Keyboard press event callback.*

*This callback is used when an event of type SDL\_KEYDOWN is reported. A keyboard press event occurs when a key is pressed.*

**Note:**  *Repeating SDL\_KEYDOWN events will occur if key repeat is enabled (see EnableKeyRepeat()).*  *The default declaration of this method calls the* **HandleKeyboardEvent***() method. If you want to handle both key presses and key releases in the same method, just redefine* **HandleKeyboardEvent***().*

**Parameters:**

- *keysym*

  *information about the pressed key*

**Returns:**  *true if the event was handled, false if it was not. If the event wasn't handled, it will be handed over to the generic* **HandleEvent***() method.*

### bool SDLmm::EventHandler::HandleKeyReleaseEvent (SDL\_keysym & keysym)` [inline, virtual]`

*Keyboard release event callback.*

*This callback is used when an event of type SDL\_KEYUP is reported. A keyboard press event occurs when a key is released.*

**Parameters:**

- *keysym*

  *the information about the released key*

**Note:**  *The default declaration of this method calls the* **HandleKeyboardEvent***() method. If you want to handle both key presses and releases in the same method, just redefine* **HandleKeyboardEvent***().*

**Returns:**  *true if the event was handled, false if it was not. If the event wasn't handled, it will be handed over to the generic* **HandleEvent***() method.*

### bool SDLmm::EventHandler::HandleKeyboardEvent (SDL\_keysym & keysym, bool pressed)` [inline, virtual]`

*Keyboard event callback.*

*This callback is used when an event of type SDL\_KEYDOWN or SDL\_KEYUP is reported. These occur when keys are pressed or released.*

**Note:**  *Repeating SDL\_KEYDOWN events will occur if key repeat is enabled (see EnableKeyRepeat()).*  *This function is only called if the default* **HandleKeyPressEvent***() and / or* **HandleKeyReleaseEvent***() methods are used.*

**Parameters:**

- *keysym*

  *information about the pressed key*

- *pressed*

  *true for SDL\_KEYDOWN, false for SDL\_KEYUP*

**Returns:**  *true if the event was handled, false if it was not. If the event wasn't handled, it will be handed over to the generic* **HandleEvent***() method.*

### bool SDLmm::EventHandler::HandleMouseButtonEvent (Uint8 button, Uint16 x, Uint16 y, bool pressed)` [inline, virtual]`

*Mouse button event callback.*

*This is used when an event of type SDL\_MOUSEBUTTONDOWN or SDL\_MOUSEBUTTONUP is reported.*

*When a mouse button press is detected the number of the button pressed (from 1 to 255, with 1 usually being the left button and 2 the right) is placed into button. The position of the mouse when this event occured is stored in x and y.*

**Note:**  *This function is only called if the default* **HandleMouseButtonPressEvent***() and / or* **HandleMouseButtonReleaseEvent***() methods are used.*

**Parameters:**

- *button*

  *the mouse button index*

- *x, y*

  *the x/y coordinates of the mouse at press time*

- *pressed*

  *true for SDL\_MOUSEBUTTONDOWN, false for SDL\_MOUSEBUTTONUP.*

**Returns:**  *true if the event was handled, false if it was not. If the event wasn't handled, it will be handed over to the generic* **HandleEvent***() method.*

### bool SDLmm::EventHandler::HandleMouseButtonPressEvent (Uint8 button, Uint16 x, Uint16 y)` [inline, virtual]`

*Mouse button press event callback.*

*This is used when an event of type SDL\_MOUSEBUTTONDOWN is reported.*

*When a mouse button press is detected the number of the button pressed (from 1 to 255, with 1 usually being the left button and 2 the right) is placed into button. The position of the mouse when this event occured is stored in x and y.*

**Note:**  *The default declaration of this method calls the* **HandleMouseButtonEvent***() method. If you want to handle both button presses and releases in the same method, just redefine* **HandleMouseButtonEvent***().*

**Parameters:**

- *button*

  *the mouse button index*

- *x, y*

  *the x/y coordinates of the mouse at press time*

**Returns:**  *true if the event was handled, false if it was not. If the event wasn't handled, it will be handed over to the generic* **HandleEvent***() method.*

### bool SDLmm::EventHandler::HandleMouseButtonReleaseEvent (Uint8 button, Uint16 x, Uint16 y)` [inline, virtual]`

*Mouse button release event callback.*

*This is used when an event of type SDL\_MOUSEBUTTONUP is reported.*

*When a mouse button release is detected the number of the button release (from 1 to 255, with 1 usually being the left button and 2 the right) is placed into button. The position of the mouse when this event occured is stored in x and y.*

**Note:**  *The default declaration of this method calls the* **HandleMouseButtonEvent***() method. If you want to handle both button presses and releases in the same method, just redefine* **HandleMouseButtonEvent***().*

**Parameters:**

- *button*

  *the mouse button index*

- *x, y*

  *the x/y coordinates of the mouse at press time*

**Returns:**  *true if the event was handled, false if it was not. If the event wasn't handled, it will be handed over to the generic* **HandleEvent***() method.*

### bool SDLmm::EventHandler::HandleMouseMotionEvent (Uint8 state, Uint16 x, Uint16 y, Sint16 xrel, Sint16 yrel)` [inline, virtual]`

*Mouse motion event callback.*

*This is used when an event of type SDL\_MOUSEMOTION is reported.*

*Simply put, a SDL\_MOUSEMOTION type event occurs when a user moves the mouse within the application window or when SDL\_WarpMouse is called. Both the absolute (x and y) and relative (xrel and yrel) coordinates are reported along with the current button states (state). The button state can be interpreted using the SDL\_BUTTON macro (see GetMouseState()).*

*If the cursor is hidden (Display::HideCursor()) and the input is grabbed (Display::GrabInput(SDL\_GRAB\_ON)) then the mouse will give relative motion events even when the cursor reaches the edge of the screen. This is currently only implemented on Windows and Linux/Unix-a-likes.*

**Parameters:**

- *state*

  *the current button state.*

- *x, y*

  *the absolute x/y coordinates of the mouse pointer*

- *xrel, yrel*

  *relative motion in the x/y directions*

**Returns:**  *true if the event was handled, false if it was not. If the event wasn't handled, it will be handed over to the generic* **HandleEvent***() method.*

### bool SDLmm::EventHandler::HandleQuitEvent ()` [inline, virtual]`

*Quit requested event callback.*

*This is used whan an event of type SDL\_QUIT is reported.*

*The SDL\_QUIT event is very important. If you filter out or ignore a quit event it is impossible for the user to close the window. On the other hand, if you do accept a quit event, the application window will be closed, and screen updates will still report success, even though the application will no longer be visible.*

**Note:**  *The macro SDL\_QuitRequested will return non-zero if a quit event is pending.*

**Returns:**  *true if the event was handled, false if it was not. If the event wasn't handled, it will be handed over to the generic* **HandleEvent***() method.*

### bool SDLmm::EventHandler::HandleResizeEvent (int w, int h)` [inline, virtual]`

*Window resize event callback.*

*This is used when an event of type SDL\_VIDEORESIZE is reported.*

*When SDL\_RESIZABLE is passed as a flag to* **Display::SetVideoMode***() the user is allowed to resize the applications window. When the window is resized an SDL\_VIDEORESIZE is reported, with the new window width and height values stored in w and h, respectively. When an SDL\_VIDEORESIZE is recieved the window should be resized to the new dimensions using* **Display::SetVideoMode***();*

**Parameters:**

- *w, h*

  *new width and height of the window.*

**Returns:**  *true if the event was handled, false if it was not. If the event wasn't handled, it will be handed over to the generic* **HandleEvent***() method.*

### bool SDLmm::EventHandler::HandleSysWMEvent ()` [inline, virtual]`

*Platform-dependent window manager event callback.*

*The system window manager event contains a pointer to system-specific information about unknown window manager events. If you enable this event using* **Event::EventState***(), it will be generated whenever unhandled events are received from the window manager. This can be used, for example, to implement cut-and-paste in your application.*

*If you want to obtain system-specific information about the window manager, you can fill the version member of a SDL\_SysWMinfo structure (details can be found in SDL\_syswm.h, which must be included) using the SDL\_VERSION() macro found in SDL\_version.h, and pass it to the function:*

```
      int SDL_GetWMInfo(SDL_SysWMinfo *info);
```

**Returns:**  *true if the event was handled, false if it was not. If the event wasn't handled, it will be handed over to the generic* **HandleEvent***() method.*

### bool SDLmm::EventHandler::HandleUserEvent (Uint8 type, int code, void \* data1, void \* data2)` [inline, virtual]`

*This event is unique - it is never created by SDL but only by the user. The event can be pushed onto the event queue using* **Event::Push***(). The contents of data1 and data2 are completely up to the programmer. The only requirement is that type is a value from SDL\_USEREVENT to SDL\_NUMEVENTS-1 (inclusive).*

**Parameters:**

- *type*

  *SDL\_USEREVENT through to SDL\_NUMEVENTS-1*

- *code*

  *user defined event code*

- *data1, data2*

  *user defined data pointers*

**Returns:**  *true if the event was handled, false if it was not. If the event wasn't handled, it will be handed over to the generic* **HandleEvent***() method.*

## AUTHOR

*Generated automatically by Doxygen for SDLmm from the source code.*