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 and y 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 and tiley 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 and y 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 and tiley 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 and y 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 and tiley 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 and y 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 and y 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

TCOD

TCOD::Color

TCOD::Console

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.

cpanm TCOD

perl -MCPAN -e shell
install TCOD