view release on metacpan or  search on metacpan

lib/SDL2/mouse.pm  view on Meta::CPAN

        [ SDL_BUTTON_LEFT   => 1 ],
        [ SDL_BUTTON_MIDDLE => 2 ],
        [ SDL_BUTTON_RIGHT  => 3 ],
        [ SDL_BUTTON_X1     => 4 ],
        [ SDL_BUTTON_X2     => 5 ],
        [ SDL_BUTTON_LMASK  => sub () { SDL2::FFI::SDL_BUTTON( SDL2::FFI::SDL_BUTTON_LEFT() ) } ],
        [ SDL_BUTTON_MMASK  => sub () { SDL2::FFI::SDL_BUTTON( SDL2::FFI::SDL_BUTTON_MIDDLE() ) } ],
        [ SDL_BUTTON_RMASK  => sub () { SDL2::FFI::SDL_BUTTON( SDL2::FFI::SDL_BUTTON_RIGHT() ) } ],
        [ SDL_BUTTON_X1MASK => sub () { SDL2::FFI::SDL_BUTTON( SDL2::FFI::SDL_BUTTON_X1() ) } ],
        [ SDL_BUTTON_X2MASK => sub () { SDL2::FFI::SDL_BUTTON( SDL2::FFI::SDL_BUTTON_X2() ) } ]
    ];

=encoding utf-8

=head1 NAME

SDL2::mouse - SDL Mouse Event Handling

=head1 SYNOPSIS

    use SDL2 qw[:mouse];

=head1 DESCRIPTION

SDL2::keyboard

=head1 Functions

These may be imported by name or with the C<:mouse> tag.

=head2 C<SDL_GetMouseFocus( )>

Get the window which currently has mouse focus.

Returns the window with mouse focus.

=head2 C<SDL_GetMouseState( ... )>

Retrieve the current state of the mouse.

The current button state is returned as a button bitmask, which can be tested
using the C<SDL_BUTTON(X)> function (where C<X> is generally 1 for the left, 2
for middle, 3 for the right button), and C<x> and C<y> are set to the mouse
cursor position relative to the focus window. You can pass NULL for either C<x>
or C<y>.

Expected parameters include:

=over

=item C<x> - the x coordinate of the mouse cursor position relative to the focus window

=item C<y> - the y coordinate of the mouse cursor position relative to the focus window

=back

Returns a 32-bit button bitmask of the current button state.

=head2 C<SDL_GetGlobalMouseState( ... )>

Get the current state of the mouse in relation to the desktop.

This works similarly to L<< C<SDL_GetMouseState( ... )>|/C<SDL_GetMouseState(
... )> >>, but the coordinates will be reported relative to the top-left of the
desktop. This can be useful if you need to track the mouse outside of a
specific window and L<< C<SDL_CaptureMouse( ... )>|/C<SDL_CaptureMouse( ... )>
>> doesn't fit your needs. For example, it could be useful if you need to track
the mouse while dragging a window, where coordinates relative to a window might
not be in sync at all times.

Note: L<< C<SDL_GetMouseState( ... )>|/C<SDL_GetMouseState( ... )> >> returns
the mouse position as SDL understands it from the last pump of the event queue.
This function, however, queries the OS for the current mouse position, and as
such, might be a slightly less efficient function. Unless you know what you're
doing and have a good reason to use this function, you probably want L<<
C<SDL_GetMouseState( ... )>|/C<SDL_GetMouseState( ... )> >> instead.

Expected parameters include:

=over

=item C<x> - filled in with the current X coord relative to the desktop; can be C<undef>

=item C<y> - filled in with the current Y coord relative to the desktop; can be C<undef>

=back

Returns the current button state as a bitmask which can be tested using C<the
SDL_BUTTON( X )> macros.

=head2 C<SDL_GetRelativeMouseState( ... )>

Retrieve the relative state of the mouse.

The current button state is returned as a button bitmask, which can be tested
using the C<SDL_BUTTON( X )> functions (where C<X> is generally 1 for the left,
2 for middle, 3 for the right button), and C<x> and C<y> are set to the mouse
deltas since the last call to SDL_GetRelativeMouseState() or since event
initialization. You can pass C<undef> for either C<x> or C<y>.

Expected parameters include:

=over

=item C<x> - a pointer filled with the last recorded x coordinate of the mouse

=item C<y> - a pointer filled with the last recorded y coordinate of the mouse

=back

=head2 C<SDL_WarpMouseInWindow( ... )>

Move the mouse cursor to the given position within the window.

This function generates a mouse motion event.

Expected parameters include:

=over

=item C<window> - the window to move the mouse into, or C<undef> for the current mouse focus

=item C<x> - the x coordinate within the window

=item C<y> - the y coordinate within the window

=back

=head2 C<SDL_WarpMouseGlobal( ... )>

Move the mouse to the given position in global screen space.

This function generates a mouse motion event.

A failure of this function usually means that it is unsupported by a platform.

Expected parameters include:

=over

=item C<x> - the x coordinate

=item C<y> - the y coordinate