Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
pods::SDL::Event(3)   User Contributed Perl Documentation  pods::SDL::Event(3)

NAME
       SDL::Event - General event structure

   CATEGORY
       Core, Events, Structure

SYNOPSIS
	use SDL::Event;	 # for the event object	itself
	use SDL::Events; # functions for event queue handling

	SDL::init(SDL_INIT_VIDEO);
	my $event = SDL::Event->new();

	while(1)
	{
	    SDL::Events::pump_events();

	    if(SDL::Events::poll_event($event))
	    {
	       if($event->type == SDL_MOUSEBUTTONDOWN)
	       {
		   # now you can handle	the details
		   $event->button_which;
		   $event->button_button;
		   $event->button_x;
		   $event->button_y;
	       }

	       last if $event->type == SDL_QUIT;
	    }

	    # your screen drawing code will be here
	}

DESCRIPTION
       Event handling allows your application to receive input from the	user.
       Event handling is initalised (along with	video) with a call to:

       "SDL::init(SDL_INIT_VIDEO);"

       Internally, SDL stores all the events waiting to	be handled in an event
       queue.  Using functions like "SDL::Events::poll_event()",
       "SDL::Events::peep_events" and "SDL::Events::wait_event()" you can
       observe and handle waiting input	events.

       The key to event	handling in SDL	is the "SDL::Event" union.  The	event
       queue itself is composed	of a series of "SDL::Event" unions, one	for
       each waiting event.  "SDL::Event" unions	are read from the queue	with
       the "SDL::Events::poll_event()" function	and it is then up to the
       application to process the information stored with them.

METHODS
   new
       "new" creates an	empty event-object, which can be used store
       information.  Either by calling "poll_event($event)" that transfers one
       event from the queue into our object or by setting all the needed data
       manually	in order to push the event to the queue.

	use SDL::Event;

	my $event = SDL::Event->new();

   type
       SDL::Event is a union of	all event structures used in SDL, using	it is
       a simple	matter of knowing which	union member relates to	which event
       "type".

	print 'heureka'	if $event->type	== SDL_MOUSEBUTTONDOWN;

       Available type constants:

       o   SDL_ACTIVEEVENT - Application visibility event structure

       o   SDL_KEYDOWN - Keyboard event	structure

       o   SDL_KEYUP - Keyboard	event structure

       o   SDL_MOUSEMOTION - Mouse motion event	structure

       o   SDL_MOUSEBUTTONDOWN - Mouse button event structure

       o   SDL_MOUSEBUTTONUP - Mouse button event structure

       o   SDL_JOYAXISMOTION - Joystick	axis motion event structure

       o   SDL_JOYBALLMOTION - Joystick	trackball motion event structure

       o   SDL_JOYHATMOTION - Joystick hat position change event structure

       o   SDL_JOYBUTTONDOWN - Joystick	button event structure

       o   SDL_JOYBUTTONUP - Joystick button event structure

       o   SDL_VIDEORESIZE - Window resize event structure

       o   SDL_VIDEOEXPOSE - Window expose event

       o   SDL_QUIT - Quit requested event

       o   SDL_USEREVENT - A user-defined event	type

       o   SDL_SYSWMEVENT - Platform-dependent window manager event.

       Event types are grouped by masks. "SDL_EVENTMASK($type)"	will return
       the proper mask for the given "type".

       Available event mask constants:

       o   SDL_ACTIVEEVENTMASK

       o   SDL_KEYDOWNMASK

       o   SDL_KEYUPMASK

       o   SDL_KEYEVENTMASK

       o   SDL_MOUSEMOTIONMASK

       o   SDL_MOUSEBUTTONDOWNMASK

       o   SDL_MOUSEBUTTONUPMASK

       o   SDL_MOUSEEVENTMASK

       o   SDL_JOYAXISMOTIONMASK

       o   SDL_JOYBALLMOTIONMASK

       o   SDL_JOYHATMOTIONMASK

       o   SDL_JOYBUTTONDOWNMASK

       o   SDL_JOYBUTTONUPMASK

       o   SDL_JOYEVENTMASK

       o   SDL_VIDEORESIZEMASK

       o   SDL_VIDEOEXPOSEMASK

       o   SDL_QUITMASK

       o   SDL_SYSWMEVENTMASK

       This way	you can	check if a given "type"	matches	a mask:

	(SDL_EVENTMASK(SDL_JOYBUTTONDOWN)   & SDL_MOUSEEVENTMASK) # is false
	(SDL_EVENTMASK(SDL_MOUSEBUTTONDOWN) & SDL_MOUSEEVENTMASK) # is true
	(SDL_EVENTMASK(SDL_MOUSEBUTTONUP)   & SDL_MOUSEEVENTMASK) # is true
	(SDL_EVENTMASK(SDL_MOUSEMOTION)	    & SDL_MOUSEEVENTMASK) # is true

	# and also true	is:

	(SDL_MOUSEEVENTMASK == SDL_EVENTMASK(SDL_MOUSEBUTTONDOWN)
			     | SDL_EVENTMASK(SDL_MOUSEBUTTONUP)
			     | SDL_EVENTMASK(SDL_MOUSEMOTION))

   Application visibility events
       "active"	is used	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 1, otherwise gain will be 0.

       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=0) or restored.

       A single	event can have multiple	values set in state.

       Note: This event	does not occur when an application window is first
       created.

       A new ActiveEvent (to fake focus	loss) will be created like this:

	my $event = SDL::Event->new();
	   $event->type(SDL_ACTIVEEVENT);
	   $event->active_gain(0);
	   $event->active_state(SDL_APPMOUSEFOCUS);

	# I think this is wrong, ->active_type() should	get SDL_APPMOUSEFOCUS, but what	state gets?

       active_gain

       See "active". 0 if the event is a loss or 1 if it is a gain.

       active_state

       A bitmask of the	following values: SDL_APPMOUSEFOCUS if mouse focus was
       gained or lost, SDL_APPINPUTFOCUS if input focus	was gained or lost,
       and SDL_APPACTIVE if the	application was	iconified (gain=0) or
       restored(gain=1).

   Keyboard events
       "key" is	used when an event of type "SDL_KEYDOWN" or "SDL_KEYUP"	is
       reported.

       The type	and state actually report the same information,	they just use
       different values	to do it.  A keyboard event generally occurs when a
       key is released ("type=SDL_KEYUP" or "key_state=SDL_RELEASED") and when
       a key is	pressed	("type=SDL_KEYDOWN" or "key_state=SDL_PRESSED").

       The "SDLK_CAPSLOCK" and "SDLK_NUMLOCK" keys are special cases and
       report an "SDL_KEYDOWN" when first pressed, then	an "SDL_RELEASED" when
       released	and pressed again. For these keys "KEYUP" and "KEYDOWN"	events
       are therefore analogous to the state of the caps	lock and num lock LEDs
       rather than the keys themselves.	 These special cases are required for
       compatibility with Sun workstations.

       Note: Repeating "SDL_KEYDOWN" events will occur if key repeat is
       enabled (see SDL::Events::enable_key_repeat).

       key_state

       "SDL_PRESSED" or	"SDL_RELEASED"

       key_scancode

       The "scancode" field should generally be	left alone, it is the
       hardware-dependent scancode returned by the keyboard.

       key_sym

       The "sym" field is extremely useful. It is the SDL-defined value	of the
       key (see	the keysym definitions in SDLKey).  This field is very useful
       when you	are checking for certain key presses, like so:

	while(poll_event($event))
	{
	    switch($event->type)
	    {
		case SDL_KEYDOWN:
		    move_left()	if($event->key_sym == SDLK_LEFT);
		    break;
		.
		.
		.
	    }
	}

       key_mod

       "mod" stores the	current	state of the keyboard modifiers	as explained
       in SDL_GetModState.

       key_unicode

       The "unicode" field is only used	when UNICODE translation is enabled
       with SDL::Events::enable_unicode.  If "unicode" is non-zero then	this
       is the UNICODE character	corresponding to the keypress.	If the high 9
       bits of the character are 0, then this maps to the equivalent ASCII
       character:

	my $char;
	if(($event->key_unicode	& 0xFF80) == 0)
	{
	    $char = $event->key_unicode	& 0x7F;
	}
	else
	{
	    print("An International Character.\n");
	}

       UNICODE translation does	create a slight	overhead so don't enable it
       unless its needed.

       NOTE: Key release events	(SDL_KEYUP) won't necessarily (ever?) contain
       unicode information.  See
       <http://lists.libsdl.org/pipermail/sdl-libsdl.org/2005-January/048355.html>

   Mouse motion	events
       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 ("motion_x" and "motion_y") and relative
       ("motion_xrel" and "motion_yrel") coordinates are reported along	with
       the current button states ("motion_state").

       motion_state

       The button state	can be interpreted using the "SDL_BUTTON" macro	(see
       SDL::Events::get_mouse_state).

       motion_x, motion_y

       The X/Y coordinates of the mouse

       motion_xrel, motion_yrel

       Relative	motion in the X/Y direction.

       If the cursor is	hidden (SDL_ShowCursor(0)) and the input is grabbed
       (SDL_WM_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-alikes.

   Mouse button	events
       When a mouse button press or release 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_button". The	position of the	mouse
       when this event occurred	is stored in the "button_x" and	the "button_y"
       fields. Like a keyboard event, information on whether the event was a
       press or	a release event	is stored in both the "button_type" and
       "button_state" fields, but this should be obvious.

       Mouse wheel events are reported as buttons 4 (up) and 5 (down). Two
       events are generated i.e. you get a "SDL_MOUSEBUTTONDOWN" followed by a
       "SDL_MOUSEBUTTONUP" event.

       button_which

       The input device	index

       button_button

       The mouse button	index ("SDL_BUTTON_LEFT", "SDL_BUTTON_MIDDLE",
       "SDL_BUTTON_RIGHT", "SDL_BUTTON_WHEELUP", "SDL_BUTTON_WHEELDOWN")

       button_state

       "SDL_PRESSED" or	"SDL_RELEASED"

       button_x, button_y

       The X/Y coordinates of the mouse	at press/release time

   Joystick axis events
       A "SDL_JOYAXISMOTION" event occurs whenever a user moves	an axis	on the
       joystick.

       jaxis_which

       The field "jaxis_which" is the index of the joystick that reported the
       event.

       jaxis_axis

       The "jaxis_axis"	is the index of	the axis (for a	more detailed
       explanation see the Joystick section).

       jaxis_value

       "jaxis_value" is	the current position of	the axis (range: -32768	to
       32767).

   Joystick button events
       A "SDL_JOYBUTTONDOWN" or	"SDL_JOYBUTTONUP" event	occurs when ever a
       user presses or releases	a button on a joystick.

       jbutton_which

       The field "jbutton_which" is the	index of the joystick that reported
       the event.

       jbutton_button

       The "jbutton_button" is the index of the	button (for a more detailed
       explanation see the Joystick section).

       jbutton_state

       "jbutton_state" is the current state of the button which	is either
       "jbutton_SDL_PRESSED" or	"jbutton_SDL_RELEASED".

   Joystick hat	events
       A "SDL_JOYHATMOTION" event occurs when ever a user moves	a hat on the
       joystick.

       jhat_which

       The field "jhat_which" is the index of the joystick that	reported the
       event.

       jhat_hat

       "jhat_hat" is the index of the hat (for a more detailed explanation see
       the Joystick section).

       jhat_value

       "jhat_value" is the current position of the hat.	It is a	bitwise	OR'd
       combination of the following values (whose meanings should be pretty
       obvious):

       o   "SDL_HAT_CENTERED"

       o   "SDL_HAT_UP"

       o   "SDL_HAT_RIGHT"

       o   "SDL_HAT_DOWN"

       o   "SDL_HAT_LEFT"

       The following defines are also provided:

       o   "SDL_HAT_RIGHTUP"

       o   "SDL_HAT_RIGHTDOWN"

       o   "SDL_HAT_LEFTUP"

       o   "SDL_HAT_LEFTDOWN"

   Joystick trackball events
       A "SDL_JOYBALLMOTION" event occurs when a user moves a trackball	on the
       joystick.

       jball_which

       The field "jball_which" is the index of the joystick that reported the
       event.

       jball_ball

       "jball_ball" is the index of the	trackball (for a more detailed
       explanation see the Joystick section).

       jball_xrel, jball_yrel

       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 "jball_xrel" and	"jball_yrel".

   Window resize events
       resize_w, resize_h

       When "SDL_RESIZABLE" is passed as a flag	to "SDL_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 the resize structure's "resize_w" and
       "resize_h".  When an "SDL_VIDEORESIZE" is received the window should be
       resized to the new dimensions using SDL_SetVideoMode.

   Window expose events
       A "VIDEOEXPOSE" event is	triggered when the screen has been modified
       outside of the application, usually by the window manager and needs to
       be redrawn.

   System window manager events
       The system window manager event contains	a system-specific information
       about unknown window manager events. If you enable this event using
       "SDL_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 in	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);

       See <http://www.libsdl.org/cgi/docwiki.cgi/SDL_SysWMEvent>

       syswm_msg

   User	defined	events
       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
       "SDL::Events::push_event". The contents of the structure	members	are
       completely up to	the programmer,	the only requirement is	that type is a
       value from "SDL_USEREVENT" to "SDL_NUMEVENTS-1" (inclusive)

	my $event = SDL::Event->new();
	   $event->type	( SDL_USEREVENT	+ 3 );
	   $event->user_code(10);
	   $event->user_data1('hello event');

	SDL::Events::push_event($event);

       user_code

       User defined event code (integer).

       user_data1, user_data2

       User defined data.

   Quit	event
       As can be seen, the "SDL_QuitEvent" structure serves no useful purpose.
       The event itself, on the	other hand, is very important. If you filter
       out or ignore a quit event then it is impossible	for the	user to	close
       the window. On the other	hand, if you do	accept a quit event then 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

AUTHORS
       See "AUTHORS" in	SDL.

SEE ALSO
       perl

perl v5.24.1			  2017-07-11		   pods::SDL::Event(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | AUTHORS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=pods::SDL::Event&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help