Source

pygame / doc / src / sdlevent.xml

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE module SYSTEM "api.dtd">

<module name="pygame2.sdl.event">
  <short>SDL event wrapper</short>
  <desc>
    Pygame SDL event wrapper module. The event module manages the SDL
    related event system and allows one to receive, send and manipulate
    events.

    The event module is the main messaging system for SDL windows and
    uses a queue to deal with events such as mouse and keyboard input,
    window state changes or user-defined ones.
  </desc>

  <class name="Event">
    <constructor>Event (type, dict) -> Event</constructor>
    <desc>
      Creates a new event to be used in the event messaging system.
      
      The type can be one of the valid SDL event type constants. Each
      event carries a certain set of attributes, which are only
      available for that event within the event object.
      
      +--------------------------+-------------------------------------------+
      | Event type               | Attributes                                |
      +==========================+===========================================+
      | :const:`ACTIVEEVENT`     | | `state`: The activation state. This will|
      |                          |   be APPMOUSEFOCUS for the mouse focus,   |
      |                          |   APPINPUTFOCUS for keyboard input focus  |
      |                          |   and APPACTIVE on iconifying (`gain` = 0)|
      |                          |   or restoring (`gain` = 1) the window.   |
      |                          | | `gain`: 1 on gain, 0 on loss            |
      +--------------------------+-------------------------------------------+
      | :const:`KEYDOWN`         | | `state`: will always be PRESSED         | 
      |                          | | `scancode`: The hardware scancode       |
      |                          | | `sym`: same as `key`                    | 
      |                          | | `key`: The sdl constant of the key (e.g.|
      |                          |   K_a, K_TAB, ...)                        |
      |                          | | `mod`:  The currently pressed modifier  |
      |                          |   keys (e.g. KMOD_SHIFT)                  |
      |                          | | `unicode`: The unicode represenation of |
      |                          |   the key.                                |
      +--------------------------+-------------------------------------------+
      | :const:`KEYUP`           | | `state`: will always be RELEASED        |
      |                          | | `scancode`: The hardware scancode       |
      |                          | | `sym`: same as `key`                    |
      |                          | | `key`: The sdl constant of the key (e.g.|
      |                          |   K_a, K_TAB, ...)                        |
      |                          | | `mod`:  The currently pressed modifier  |
      |                          |   keys (e.g. KMOD_SHIFT)                  |
      |                          | | `unicode`: The unicode represenation of |
      |                          |   the key.                                |
      +--------------------------+-------------------------------------------+
      | :const:`MOUSEMOTION`     | | `state`: Bit-wise combination of the    |
      |                          |   button states (see `buttons`)           |
      |                          | | `x`: The current x-coordinate on the    |
      |                          |   window.                                 |
      |                          | | `y`: The current y-coordinate on the    |
      |                          |   window.                                 |
      |                          | | `xrel`: relative motion in x direction  |
      |                          |   since the last event poll               |
      |                          | | `yrel`: relative motion in y direction  |
      |                          |   since the last event poll               |
      |                          | | `pos`: The x/y coordinate as tuple      |
      |                          | | `rel`: the relative x/y motion as tuple |
      |                          | | `buttons`: 3-value tuple containing the |
      |                          |   mouse button states for the first three |
      |                          |   mouse buttons. Each of the values is    |
      |                          |   either *True* or *False*, indicating    |
      |                          |   whether the button is pressed or not    |
      +--------------------------+-------------------------------------------+
      | :const:`MOUSEBUTTONDOWN` | | `state`: will always be PRESSED         |
      |                          | | `x`: The current x-coordinate on the    |
      |                          |   window.                                 |
      |                          | | `y`: The current y-coordinate on the    |
      |                          |   window.                                 |
      |                          | | `pos`: The x/y coordinate as tuple      |
      |                          | | `button`: The pressed button (will be   |
      |                          |   either BUTTON_LEFT, BUTTON_MIDDLE or    |
      |                          |   BUTTON_RIGHT                            |
      +--------------------------+-------------------------------------------+
      | :const:`MOUSEBUTTONUP`   | | `state`: will always be RELEASED        |
      |                          | | `x`: The current x-coordinate on the    |
      |                          |   window.                                 |
      |                          | | `y`: The current y-coordinate on the    |
      |                          |   window.                                 |
      |                          | | `pos`: The x/y coordinate as tuple      |
      |                          | | `button`: The pressed button (will be   |
      |                          |   either BUTTON_LEFT, BUTTON_MIDDLE or    |
      |                          |   BUTTON_RIGHT                            |
      +--------------------------+-------------------------------------------+
      | :const:`JOYAXISMOTION`   | | `which`: The device index of the        |
      |                          |   joystick                                |
      |                          | | `joy`: same as `which`                  |
      |                          | | `axis`: The joystick axis index         |
      |                          | | `value`: The current position of the    |
      |                          |   axis (between -32768 and 32767)         |
      +--------------------------+-------------------------------------------+
      | :const:`JOYBALLMOTION`   | | `which`: The device index of the        |
      |                          |   joystick                                |
      |                          | | `joy`: same as `which`                  |
      |                          | | `ball`: The trackball index             |
      |                          | | `xrel`: The relative motion in x        |
      |                          |   direction since the last event poll     |
      |                          | | `yrel`: The relative motion in y        |
      |                          |   direction since the last event poll     |
      |                          | | `rel`: The relative x/y motion as tuple |
      +--------------------------+-------------------------------------------+
      | :const:`JOYHATMOTION`    | | `which`: The device index of the        |
      |                          |   joystick                                |
      |                          | | `joy`: same as `which`                  |
      |                          | | `hat`: The hat index                    |
      |                          | | `value`: The current hat position as    |
      |                          |   bit-wise combination (e.g. HAT_LEFTUP)  |
      +--------------------------+-------------------------------------------+
      | :const:`JOYBUTTONDOWN`   | | `which`: The device index of the        |
      |                          |   joystick                                |
      |                          | | `joy`: same as `which`                  |
      |                          | | `button`: The button index              |
      |                          | | `state`: wil always be PRESSED          |
      +--------------------------+-------------------------------------------+
      | :const:`JOYBUTTONUP`     | | `which`: The device index of the        |
      |                          |   joystick                                |
      |                          | | `joy`: same as `which`                  |
      |                          | | `button`: The button index              |
      |                          | | `state`: Will always be RELEASED        |
      +--------------------------+-------------------------------------------+
      | :const:`VIDEORESIZE`     | | `w`: The width to resize to             |
      |                          | | `h`: The height to resize to            |
      |                          | | `size`: The width and height as tuple   |
      +--------------------------+-------------------------------------------+
      | :const:`VIDEOEXPOSE`     | no attributes                             |
      +--------------------------+-------------------------------------------+
      | :const:`QUIT`            | no attributes                             |
      +--------------------------+-------------------------------------------+

      Some events have special or system-dependent attributes.
      
      +---------------------+-------------------------------------------------+
      | Event type          | Attributes                                      |
      +=====================+=================================================+
      | :const:`SYSWMEVENT` | | `hwnd`, `msg`, `wparam`, `lparam` for Windows |
      |                     | | `event`                           for X11     |
      |                     | | no attributes                     for others  |
      +---------------------+-------------------------------------------------+
      
      For user-defiend events, there is the special :const:`USEREVENT` type (and
      above). User-defined events can carry their own type, which must
      be in the range [:const:`USEREVENT`, (:const:`NUMEVENTS` - 1)]. If they
      are sent from pygame code directly, they do not carry specific attributes,
      just those given to them by the passed dictionary.

      If they come from another system (e.g. 3rd party library), they
      might carry the following attributes:

      +--------------------+--------------------------+
      | Event type         | Attributes               |
      +====================+==========================+
      | :const:`USEREVENT` | `code`, `data1`, `data2` |
      +--------------------+--------------------------+
    </desc>
    <attr name="name"><desc>Gets the name of the Event.</desc></attr>
    <attr name="type"><desc>Gets type id of the Event.</desc></attr>
  </class>

  <func name="clear">
    <call>clear ([events]) -> None</call>
    <desc>
      Clears the event queue from certain event types.

      Clears the event queue from certain event types. If no argument is
      passed, all current events are removed from the queue. Otherwise
      the argument can be a sequence or a bitmask combination of event
      types to clear. 
    </desc>
  </func>
  <func name="get">
    <call>get ([events]) -> list</call>
    <desc>
      Gets events from the event queue.

      Gets the current events from the event queue. If no argument is
      passed, all currently available events are received from the event
      queue and returned as list. Otherwise, the argument can be a
      sequence or a bitmask combination of event types to receive from
      the queue.

      If no matching events are found on the queue, None will be
      returned.
    </desc>
  </func>
  <func name="get_app_state">
    <call>get_app_state () -> int</call>
    <desc>
      Gets the current application state.

      Gets the current application state. This will be a bitmask
      combination of the :const:`APPMOUSEFOCUS`, :const:`APPINPUTFOCUS` or
      :const:`APPACTIVE` masks, indicating whether the application currently is
      active and has the mouse and keyboard input focus.
    </desc>
  </func>
  <func name="get_blocked">
    <call>get_blocked () -> list</call>
    <desc>
      Gets a list of currently blocked event types.
      
      Gets a list of currently blocked event types. Events having the
      matching type will not be processed by the event queue.
    </desc>
  </func>
  <func name="get_filter">
    <call>get_filter () -> object</call>
    <desc>
      Gets the currently set filter hook method.

      Gets the filter hook method set previously by set_filter().
    </desc>
  </func>
  <func name="peek">
    <call>peek ([events]) -> bool</call>
    <desc>
      Checks, whether certain event types are currently on the queue.
      
      Checks, whether certain event types are currently on the queue. If
      no argument is passed, this method simply checks, if there is any
      event on the event queue. Otherwise, the argument can be a
      sequence or a bitmask combination of event types to check for.  In
      case one event is found, which corresponds to the requested
      type(s), True is returned.
    </desc>
  </func>
  <func name="peep">
    <call>peep (num, action, mask[, events]) -> int or list</call>
    <desc>
      Checks the event queue for events and optionally returns them.

      peep() is an advanced event queue querying and manipulation
      method. It allows to inspect the event queue, to receive events
      from it or to add events.

      TODO
    </desc>
  </func>
  <func name="poll">
    <call>poll () -> Event</call>
    <desc>
      Gets a single event from the event queue.

      Returns a single event from the queue. If the event queue is
      empty, None will be returned. If an event is available and
      returned, it will be removed from the queue.
    </desc>
  </func>
  <func name="pump">
    <call>pump () -> None</call>
    <desc>
      Pumps the event queue, forcing it to gather pending events from
      devices.

      pump() gathers all pending events and input information from
      devices and places them on the event queue.

      It only has to be called, if you use peep() or a filter hook
      without using another event function or no other event function at
      all.
    </desc>
  </func>
  <func name="push">
    <call>push (Event) -> None</call>
    <desc>
      Places a new event at the end of the event queue.

      This is usually used for placing user defined events on the event
      queue. You also can push user created device events on the queue,
      but this will not change the state of the device itself.
    </desc>
  </func>
  <func name="set_blocked">
    <call>set_blocked (type) -> None</call>
    <desc>
      Blocks a single or multiple event types.

      This will block a single or multiple event types from being
      processed by the event system and thus will exactly behave like
      state(type, :const:`IGNORE`).

      In case other event types are already blocked, the block for them
      will be reset.

      To remove the block for all events, call set_blocked(None).
    </desc>
  </func>
  <func name="set_filter">
    <call>set_filter (filterhook) -> None</call>
    <desc>
      Sets up a filter hook for events.

      This sets up a filter to process all events before they are posted
      to the event queue. In order to process events correctly, the
      filterhook must return True or False, indicating whether the event
      processd by it, is allowed to be placed on the event queue or not.
      It has to take a single argument, which will be the event to process. ::

        def example_filter_hook (event):
            if event.type == ... and ...:
                # The event matches a certain scheme, do not allow it.
                return False
            # Any other event may pass.
            return True
      
      In case the :const:`QUITEVENT` is processed by the event filter, returning
      True will cause the SDL window to be closed, otherwise, the window
      will remain open, if possible.

      Note: events pushed onto the event queue using push() or peep() do
      not get passed through the filter.
    </desc>
  </func>
  <func name="state">
    <call>state (type, state) -> int</call>
    <desc>
      Sets the processing state of an event type.

      This allows you to set the processing state of an event type.
      If the state is set to :const:`IGNORE`, events matching the type will be
      automatically dropped from the event queue and will not be
      filtered. This will behave similar to set_blocked().
      If the state is set to :const:`ENABLE`, events matching the type will be
      processed normally.
      If the state iset set to :const:`QUERY`, state() will return the current
      processing state of the specified event type (:const:`ENABLE` or
      :const:`IGNORE`).
    </desc>
  </func>
  <func name="wait">
    <call>wait () -> Event</call>
    <desc>
      Waits indefinitely for the next available event.

      wait() is a blocking method, that only returns, if an event occurs
      on the event queue. Once an even occurs, it will be returned to
      the caller and removed from the queue. While the program is
      waiting it will sleep in an idle state.
    </desc>
  </func>
</module>