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

FreeBSD Manual Pages

  
 
  

home | help
ALLEGRO_EVENT(3)					      ALLEGRO_EVENT(3)

NAME
       ALLEGRO_EVENT - Allegro 5 API

SYNOPSIS
	      #include <allegro5/allegro.h>

	      typedef union ALLEGRO_EVENT ALLEGRO_EVENT;

DESCRIPTION
       An  ALLEGRO_EVENT  is a union of	all builtin event structures, i.e.  it
       is an object large enough to hold the data  of  any  event  type.   All
       events have the following fields	in common:

       type (ALLEGRO_EVENT_TYPE)
	      Indicates	the type of event.

       any.source (ALLEGRO_EVENT_SOURCE	*)
	      The event	source which generated the event.

       any.timestamp (double)
	      When the event was generated.

       By  examining  the type field you can then access type-specific fields.
       The any.source field tells you which event source generated  that  par-
       ticular	event.	 The  any.timestamp field tells	you when the event was
       generated.  The time is	referenced  to	the  same  starting  point  as
       al_get_time(3).

       Each  event  is	of  one	of the following types,	with the usable	fields
       given.

   ALLEGRO_EVENT_JOYSTICK_AXIS
       A joystick axis value changed.

       joystick.id (ALLEGRO_JOYSTICK *)
	      The joystick which generated the event.  This is not the same as
	      the event	source joystick.source.

       joystick.stick (int)
	      The  stick  number,  counting from zero.	Axes on	a joystick are
	      grouped into "sticks".

       joystick.axis (int)
	      The axis number on the stick, counting from zero.

       joystick.pos (float)
	      The axis position, from -1.0 to +1.0.

   ALLEGRO_EVENT_JOYSTICK_BUTTON_DOWN
       A joystick button was pressed.

       joystick.id (ALLEGRO_JOYSTICK *)
	      The joystick which generated the event.

       joystick.button (int)
	      The button which was pressed, counting from zero.

   ALLEGRO_EVENT_JOYSTICK_BUTTON_UP
       A joystick button was released.

       joystick.id (ALLEGRO_JOYSTICK *)
	      The joystick which generated the event.

       joystick.button (int)
	      The button which was released, counting from zero.

   ALLEGRO_EVENT_JOYSTICK_CONFIGURATION
       A joystick  was	plugged	 in  or	 unplugged.   See  al_reconfigure_joy-
       sticks(3) for details.

   ALLEGRO_EVENT_KEY_DOWN
       A keyboard key was pressed.

       keyboard.keycode	(int)
	      The  code	 corresponding	to the physical	key which was pressed.
	      See the "Key codes" section for the list of  ALLEGRO_KEY_*  con-
	      stants.

       keyboard.display	(ALLEGRO_DISPLAY *)
	      The display which	had keyboard focus when	the event occurred.

	      Note: this event is about	the physical keys being	pressed	on the
	      keyboard.	 Look for ALLEGRO_EVENT_KEY_CHAR events	for  character
	      input.

   ALLEGRO_EVENT_KEY_UP
       A keyboard key was released.

       keyboard.keycode	(int)
	      The  code	 corresponding to the physical key which was released.
	      See the "Key codes" section for the list of  ALLEGRO_KEY_*  con-
	      stants.

       keyboard.display	(ALLEGRO_DISPLAY *)
	      The display which	had keyboard focus when	the event occurred.

   ALLEGRO_EVENT_KEY_CHAR
       A  character  was  typed	 on  the keyboard, or a	character was auto-re-
       peated.

       keyboard.keycode	(int)
	      The code corresponding  to  the  physical	 key  which  was  last
	      pressed.	 See  the  "Key	 codes"	 section for the list of ALLE-
	      GRO_KEY_*	constants.

       keyboard.unichar	(int)
	      A	Unicode	code point (character).	 This may be zero or  negative
	      if  the  event was generated for a non-visible "character", such
	      as an arrow or Function key.  In that case you can act upon  the
	      keycode field.

	      Some  special  keys will set the unichar field to	their standard
	      ASCII values: Tab=9, Return=13, Escape=27.  In addition  if  you
	      press  the  Control  key	together with A	to Z the unichar field
	      will have	the values 1 to	 26.   For  example  Ctrl-A  will  set
	      unichar to 1 and Ctrl-H will set it to 8.

	      As of Allegro 5.0.2 there	are some inconsistencies in the	treat-
	      ment of Backspace	(8 or 127) and Delete (127 or 0) keys on  dif-
	      ferent  platforms.   These  can be worked	around by checking the
	      keycode field.

       keyboard.modifiers (unsigned)
	      This is a	bitfield of the	modifier keys which were pressed  when
	      the  event occurred.  See	"Keyboard modifier flags" for the con-
	      stants.

       keyboard.repeat (bool)
	      Indicates	if this	is a repeated character.

       keyboard.display	(ALLEGRO_DISPLAY *)
	      The display which	had keyboard focus when	the event occurred.

	      Note:  in	 many  input  methods,	characters  are	 not   entered
	      one-for-one with physical	key presses.  Multiple key presses can
	      combine to generate a single character, e.g.  apostrophe + e may
	      produce  'A(C)'.	Fewer key presses can also generate more char-
	      acters, e.g.  macro sequences expanding to common	phrases.

   ALLEGRO_EVENT_MOUSE_AXES
       One or more mouse axis values changed.

       mouse.x (int)
	      x-coordinate

       mouse.y (int)
	      y-coordinate

       mouse.z (int)
	      z-coordinate.  This usually means	the vertical axis of  a	 mouse
	      wheel, where up is positive and down is negative.

       mouse.w (int)
	      w-coordinate.  This usually means	the horizontal axis of a mouse
	      wheel.

       mouse.dx	(int)
	      Change in	 the  x-coordinate  value  since  the  previous	 ALLE-
	      GRO_EVENT_MOUSE_AXES event.

       mouse.dy	(int)
	      Change  in  the  y-coordinate  value  since  the	previous ALLE-
	      GRO_EVENT_MOUSE_AXES event.

       mouse.dz	(int)
	      Change in	 the  z-coordinate  value  since  the  previous	 ALLE-
	      GRO_EVENT_MOUSE_AXES event.

       mouse.dw	(int)
	      Change  in  the  w-coordinate  value  since  the	previous ALLE-
	      GRO_EVENT_MOUSE_AXES event.

       mouse.display (ALLEGRO_DISPLAY *)
	      The display which	had mouse focus.

	      Note: Calling al_set_mouse_xy(3) also will result	in a change of
	      axis   values,   but  such  a  change  is	 reported  with	 ALLE-
	      GRO_EVENT_MOUSE_WARPED events instead.

	      Note: currently mouse.display may	be NULL	if an event is	gener-
	      ated in response to al_set_mouse_axis(3).

   ALLEGRO_EVENT_MOUSE_BUTTON_DOWN
       A mouse button was pressed.

       mouse.x (int)
	      x-coordinate

       mouse.y (int)
	      y-coordinate

       mouse.z (int)
	      z-coordinate

       mouse.w (int)
	      w-coordinate

       mouse.button (unsigned)
	      The mouse	button which was pressed, numbering from 1.

       mouse.display (ALLEGRO_DISPLAY *)
	      The display which	had mouse focus.

   ALLEGRO_EVENT_MOUSE_BUTTON_UP
       A mouse button was released.

       mouse.x (int)
	      x-coordinate

       mouse.y (int)
	      y-coordinate

       mouse.z (int)
	      z-coordinate

       mouse.w (int)
	      w-coordinate

       mouse.button (unsigned)
	      The mouse	button which was released, numbering from 1.

       mouse.display (ALLEGRO_DISPLAY *)
	      The display which	had mouse focus.

   ALLEGRO_EVENT_MOUSE_WARPED
       al_set_mouse_xy(3) was called to	move the mouse.	 This event is identi-
       cal to ALLEGRO_EVENT_MOUSE_AXES otherwise.

   ALLEGRO_EVENT_MOUSE_ENTER_DISPLAY
       The mouse cursor	entered	a window opened	by the program.

       mouse.x (int)
	      x-coordinate

       mouse.y (int)
	      y-coordinate

       mouse.z (int)
	      z-coordinate

       mouse.w (int)
	      w-coordinate

       mouse.display (ALLEGRO_DISPLAY *)
	      The display which	had mouse focus.

   ALLEGRO_EVENT_MOUSE_LEAVE_DISPLAY
       The mouse cursor	leave the boundaries of	a window opened	 by  the  pro-
       gram.

       mouse.x (int)
	      x-coordinate

       mouse.y (int)
	      y-coordinate

       mouse.z (int)
	      z-coordinate

       mouse.w (int)
	      w-coordinate

       mouse.display (ALLEGRO_DISPLAY *)
	      The display which	had mouse focus.

   ALLEGRO_EVENT_TIMER
       A timer counter incremented.

       timer.source (ALLEGRO_TIMER *)
	      The timer	which generated	the event.

       timer.count (int64_t)
	      The timer	count value.

   ALLEGRO_EVENT_DISPLAY_EXPOSE
       The display (or a portion thereof) has become visible.

       display.source (ALLEGRO_DISPLAY *)
	      The display which	was exposed.

       display.x (int)
		display.y (int)

       The top-left corner of the display which	was exposed.

       display.width (int)
		display.height (int)
       The width and height of the rectangle which was exposed.

	      Note:  The display needs to be created with ALLEGRO_GENERATE_EX-
	      POSE_EVENTS flag for these events	to be generated.

   ALLEGRO_EVENT_DISPLAY_RESIZE
       The window has been resized.

       display.source (ALLEGRO_DISPLAY *)
	      The display which	was resized.

       display.x (int)
		display.y (int)
       The position of the top-level corner of the display.

       display.width (int)
	      The new width of the display.

       display.height (int)
	      The new height of	the display.

       You should normally respond to  these  events  by  calling  al_acknowl-
       edge_resize(3).	 Note  that  further resize events may be generated by
       the time	you process the	event, so these	fields may hold	 outdated  in-
       formation.

   ALLEGRO_EVENT_DISPLAY_CLOSE
       The close button	of the window has been pressed.

       display.source (ALLEGRO_DISPLAY *)
	      The display which	was closed.

   ALLEGRO_EVENT_DISPLAY_LOST
       When using Direct3D, displays can enter a "lost"	state.	In that	state,
       drawing calls are ignored, and upon entering the	state, bitmap's	 pixel
       data  can become	undefined.  Allegro does its best to preserve the cor-
       rect contents of	bitmaps	(see ALLEGRO_NO_PRESERVE_TEXTURE) and  restore
       them  when  the	device	is  "found" (see ALLEGRO_EVENT_DISPLAY_FOUND).
       However,	this is	not 100% fool proof.

       To ensure that all bitmap contents are restored	accurately,  one  must
       take  additional	 steps.	  The  best procedure to follow	if bitmap con-
       stancy is important to you is as	follows: first,	always have the	 ALLE-
       GRO_NO_PRESERVE_TEXTURE	flag  set to true when creating	bitmaps, as it
       incurs pointless	overhead when using this  method.   Second,  create  a
       mechanism  in your game for easily reloading all	of your	bitmaps	-- for
       example,	wrap them in a class or	data structure and have	a "bitmap man-
       ager"  that  can	reload them back to the	desired	state.	Then, when you
       receive an ALLEGRO_EVENT_DISPLAY_FOUND event, tell the  bitmap  manager
       (or whatever your mechanism is) to restore your bitmaps.

       display.source (ALLEGRO_DISPLAY *)
	      The display which	was lost.

   ALLEGRO_EVENT_DISPLAY_FOUND
       Generated when a	lost device is restored	to operating state.  See ALLE-
       GRO_EVENT_DISPLAY_LOST.

       display.source (ALLEGRO_DISPLAY *)
	      The display which	was found.

   ALLEGRO_EVENT_DISPLAY_SWITCH_OUT
       The window is no	longer active, that is the  user  might	 have  clicked
       into another window or "tabbed" away.

       display.source (ALLEGRO_DISPLAY *)
	      The display which	was switched out of.

   ALLEGRO_EVENT_DISPLAY_SWITCH_IN
       The window is the active	one again.

       display.source (ALLEGRO_DISPLAY *)
	      The display which	was switched into.

   ALLEGRO_EVENT_DISPLAY_ORIENTATION
       Generated when the rotation or orientation of a display changes.

       display.source (ALLEGRO_DISPLAY *)
	      The display which	generated the event.

       event.display.orientation
	      Contains one of the following values:

	      o	ALLEGRO_DISPLAY_ORIENTATION_0_DEGREES

	      o	ALLEGRO_DISPLAY_ORIENTATION_90_DEGREES

	      o	ALLEGRO_DISPLAY_ORIENTATION_180_DEGREES

	      o	ALLEGRO_DISPLAY_ORIENTATION_270_DEGREES

	      o	ALLEGRO_DISPLAY_ORIENTATION_FACE_UP

	      o	ALLEGRO_DISPLAY_ORIENTATION_FACE_DOWN

SEE ALSO
       ALLEGRO_EVENT_SOURCE(3),	 ALLEGRO_EVENT_TYPE(3),	ALLEGRO_USER_EVENT(3),
       ALLEGRO_GET_EVENT_TYPE(3)

Allegro	reference manual				      ALLEGRO_EVENT(3)

NAME | SYNOPSIS | DESCRIPTION | SEE ALSO

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

home | help