NAME
TCOD::Event - A TCOD wrapper around SDL2 events
SYNOPSIS
use TCOD;
# Block until there is an event
my $iter = TCOD::Event::wait;
# Get each event in turn
while ( my $event = $iter->() ) {
exit if $event->type eq 'QUIT';
}
DESCRIPTION
This class is a thin wrapper around SDL2 events.
METHODS
new
$tcod_event = TCOD::Event->new( $sdl_event );
Wrap an SDL2 event in a TCOD event. You will most likely not have to use this yourself, but it is called internally by the methods below.
FUNCTIONS
wait
$iterator = TCOD::Event::wait( $timeout );
Block until events exist, then return an event iterator.
The value in $timeout
is the maximum number of seconds to wait for the next event. If none is provided, or the value is 0, the code will block for as long as it takes for the next event to be registered.
Returns the same iterator as a call get.
get
$iterator = TCOD::Event::get;
Return a coderef that can be used as an iterator for all pending events. Calling the coderef will return the next available event.
Events are processed as the iterator is consumed. Breaking out of, or discarding the iterator will leave the remaining events on the event queue.
EVENT TYPES
All these events have a type
method that returns a string identifying their type as a string, and wrap around an SDL2 event from which they get their data They also have a as_string
method that can be used to transform the event into a printable string, useful for logging and debugging.
TCOD::Event::Quit
An application quit request event. See the SDL2 documentation for more info on when this event may be triggered.
type
Always returns
QUIT
.
TCOD::Event::KeyDown
Triggered when a keyboard key is pressed.
type
Always returns
KEYDOWN
.sym
Returns the
sym
value of the SDL2 keyboard event. This is a value in this module's Keycode enum.scancode
Returns the
scancode
value of the SDL2 keyboard event. This is a value in this module's Scancode enum.mod
Returns the
mod
value of the SDL2 keyboard event. This is a value in this module's Keymod enum.repeat
Returns a true value if this is a repeat event for this key (eg. this key is being held down).
TCOD::Event::KeyUp
Triggered when a keyboard key is released.
type
Always returns
KEYUP
.sym
Returns the
sym
value of the SDL2 keyboard event. This is a value in this module's Keycode enum.scancode
Returns the
scancode
value of the SDL2 keyboard event. This is a value in this module's Scancode enum.mod
Returns the
mod
value of the SDL2 keyboard event. This is a value in this module's Keymod enum.repeat
Returns a true value if this is a repeat event for this key (eg. this key is being held down).
TCOD::Event::MouseButtonUp
Triggered when a mouse button is released.
type
Always returns
MOUSEBUTTONUP
.xy
Returns an array reference with the pixel coordinates of this mouse event. The individual components of this coordinate are also available through the
x
andy
accessors.tilexy
If this event has been processed with TCOD::Context::convert_event, this will returns an array reference with the tile coordinates of this mouse event. Otherwise, this will return
undef
.The individual components of this coordinate are also available through the
tilex
andtiley
accessors.state
A bitfield with all the buttons that are currently being held. This can be checked against the values in this module's MouseButton enum.
button
The button that triggered this mouse event. It will be one of the values in this module's MouseButton enum.
TCOD::Event::MouseButtonDown
Triggered when a mouse button is pressed.
type
Always returns
MOUSEBUTTONDOWN
.xy
Returns an array reference with the pixel coordinates of this mouse event. The individual components of this coordinate are also available through the
x
andy
accessors.tilexy
If this event has been processed with TCOD::Context::convert_event, this will returns an array reference with the tile coordinates of this mouse event. Otherwise, this will return
undef
.The individual components of this coordinate are also available through the
tilex
andtiley
accessors.state
A bitfield with all the buttons that are currently being held. This can be checked against the values in this module's MouseButton enum.
button
The button that triggered this mouse event. It will be one of the values in this module's MouseButton enum.
TCOD::Event::MouseMotion
Triggered when the mouse is moved.
type
Always returns
MOUSEMOTION
.xy
Returns an array reference with the pixel coordinates of this mouse event. The individual components of this coordinate are also available through the
x
andy
accessors.tilexy
If this event has been processed with TCOD::Context::convert_event, this will returns an array reference with the tile coordinates of this mouse event. Otherwise, this will return
undef
.The individual components of this coordinate are also available through the
tilex
andtiley
accessors.state
A bitfield with all the buttons that are currently being held. This can be checked against the values in this module's MouseButton enum.
TCOD::Event::MouseWheel
Triggered when the mouse wheel is rolled.
type
Always returns
MOUSEWHEEL
.xy
Returns an array reference with the amount that was scrolled, horizontally and vertically, in pixels. Negative values point left and up, while positive values point in the opposite direction.
The individual components of this array reference are also available through the
x
andy
accessors.flipped
Returns a true value if either the user or the operating system has set the mouse to be flipped.
TCOD::Event::TextInput
Triggered when the user has entered some text.
type
Always returns
TEXTINPUT
.text
The text that was input.
TCOD::Event::WindowClose
Triggered when the window manager has requested the window to be closed.
type
Always returns
WINDOWCLOSE
.
TCOD::Event::WindowEnter
Triggered when the window has gained mouse focus.
type
Always returns
WINDOWENTER
.
TCOD::Event::WindowLeave
Triggered when the window has lost mouse focus.
type
Always returns
WINDOWLEAVE
.
TCOD::Event::WindowRestored
Triggered when the window has been restored to its normal size and position.
type
Always returns
WINDOWRESTORED
.
TCOD::Event::WindowMinimized
Triggered when the window has been minimised.
type
Always returns
WINDOWMINIMIZED
.
TCOD::Event::WindowMaximized
Triggered when the window has been maximised.
type
Always returns
WINDOWMAXIMIZED
.
TCOD::Event::WindowExposed
Triggered when a part of the window that was hidden has been exposed. This normally means the window needs to be redrawn.
type
Always returns
WINDOWEXPOSED
.
TCOD::Event::WindowFocusGained
Triggered when the window has gained keyboard focus.
type
Always returns
WINDOWFOCUSGAINED
.
TCOD::Event::WindowFocusLost
Triggered when the window has lost keyboard focus.
type
Always returns
WINDOWFOCUSLOST
.
TCOD::Event::WindowTakeFocus
Triggered when the window is being offered focus.
type
Always returns
WINDOWTAKEFOCUS
.
TCOD::Event::WindowShown
Triggered when the window has been shown.
type
Always returns
WINDOWSHOWN
.
TCOD::Event::WindowHidden
Triggered when the window has been hidden.
type
Always returns
WINDOWHIDDEN
.
TCOD::Event::WindowHitTest
Triggered when the window has had a hit test.
type
Always returns
WINDOWHITTEST
.
TCOD::Event::WindowMoved
Triggered when the window has been moved.
type
Always returns
WINDOWMOVED
.xy
Returns an array reference with the screen coordinates the window has been moved to.
The individual components of this coordinate are also available through the
x
andy
accessors.
TCOD::Event::WindowResized
Triggered when the window has been resized.
type
Always returns
WINDOWRESIZED
.width
Returns the window's new width in pixels.
height
Returns the window's new height in pixels.
TCOD::Event::Undefined
A default event generated when no mapping could be found.
type
Always returns
UNDEFINED
.
package TCOD::Event::WindowEvent { our @ISA = 'TCOD::Event::Base'; sub init { my $self = shift;
my ( $e, $k ) = @{ $self }{qw( sdl_event !key )};
my $w = $e->$k if $k;
$self->{type} = $TCOD::SDL2::WindowEventID{ $w->event }
// return TCOD::Event::Undefined->new($e)->init;
$self->{type} =~ s/WINDOWEVENT_/WINDOW_/;
$self->{type} =~ s/([A-Z])([A-Z]*)_/$1\L$2/g;
$self;
}
}
ENUMS
The enums listed below are available as constants like the ones defined using constant, which means the same caveats apply here.
To provide introspection into the values of the enums, they are also made available as package variables with the names of each enum. This makes it possible to get the name of a value in a given enum with code like the following:
say $TCOD::Event::Keycode{ TCOD::Event::K_UP }; # Prints 'K_UP'
Keycode
A translation of the SDL_Keycode enum in SDL2. Keys and values should be the same as those in SDL2, without the SDL_
prefix (so SDLK_UP
becomes TCOD::Event::K_UP
).
Keymod
A translation of the SDL_Keymod enum in SDL2. Keys and values should be the same as those in SDL2 (eg. TCOD::Event::KMOD_SHIFT
).
Scancode
A translation of the SDL_Scancode enum in SDL2. Keys and values should be the same as those in SDL2, without the SDL_SCANCODE_
prefix (so SDL_SCANCODE_UP
becomes TCOD::Event::UP
).
MouseButton
Can be used to check the button
key of mouse button events for the button that triggered the event.
BUTTON_LEFT
BUTTON_MIDDLE
BUTTON_RIGHT
BUTTON_X1
BUTTON_X2
MouseButtonMask
Can be used to check the state
key of MouseMotion events for the buttons that are currently being held.
BUTTON_LMASK
BUTTON_MMASK
BUTTON_RMASK
BUTTON_X1MASK
BUTTON_X2MASK
SEE ALSO
COPYRIGHT AND LICENSE
Copyright 2021 José Joaquín Atria
This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.