SDLmm::EventHandler(3)SDLmm::EventHandler(3)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.
SDLmm 16 Jul 2001 SDLmm::EventHandler(3)
