Window
======
.. module:: sfml.window
.. contents:: :local:
   :depth: 1


Style
^^^^^

.. class:: Style

   This class defines the following constants:

   +------------+--------------------------------------------------------------------------+
   | Style      | Description                                                              |
   +============+==========================================================================+
   | NONE       | No border / title bar (this flag and all others are mutually exclusive). |
   +------------+--------------------------------------------------------------------------+
   | TITLEBAR   | Title bar + fixed border.                                                |
   +------------+--------------------------------------------------------------------------+
   | RESIZE     | Titlebar + close button.                                                 |
   +------------+--------------------------------------------------------------------------+
   | CLOSE      | Request a page's header only.                                            |
   +------------+--------------------------------------------------------------------------+
   | FULLSCREEN | Fullscreen mode (this flag and all others are mutually exclusive)        |
   +------------+--------------------------------------------------------------------------+
   | DEFAULT    | Default window style.                                                    |
   +------------+--------------------------------------------------------------------------+

Event
^^^^^

.. contents:: :local:

.. class:: Event

   Defines a system event and its parameters.

   :class:`Event` holds all the information about a system
   event that just happened.

   Events are retrieved using the :meth:`Window.poll_event` and
   :meth:`Window.wait_event` functions. You can also retrieve
   a generator that iterates over the pending events the property
   :attr:`Window.events`.

   An :class:`Event` instance contains the data of the event.

   Usage example::

      for event in window.events:
         # request for closing the window
         if type(event) is sf.CloseEvent:
            window.close()

         # the escape key was pressed
         if type(event) is sf.KeyEvent and event.code is sf.Keyboard.ESCAPE:
            window.close()

         # the window was resized
         if type(event) is sf.ResizeEvent:
            do_something_with_the_new_size(event.size)

         # ...

CloseEvent
----------
.. class:: CloseEvent(Event)

   The window requested to be closed.

ResizeEvent
-----------
.. class:: ResizeEvent(Event)

   The window was resized.

   .. attribute:: size

      Tell you the new window size.

      :rtype: :class:`sfml.system.Vector2`

FocusEvent
----------
.. class:: FocusEvent(Event)

   The window gained or lost the focus, :attr:`gained` and :attr:`lost`
   return boolean.

   .. attribute:: gained
   .. attribute:: lost

MouseEvent
----------
.. class:: MouseEvent

   The mouse cursor entered or left the area of the window,
   :attr:`entered` and :attr:`left` return boolean.

   .. attribute:: entered
   .. attribute:: left

TextEvent
---------
.. class:: TextEvent(Event)

   A character was entered. :attr:`unicode` return the ASCII code (integer).

   .. attribute:: unicode

KeyEvent
--------
.. class:: KeyEvent(Event)

   A key was pressed or released. :attr:`pressed` and :attr:`released`
   return boolean.

   .. attribute:: pressed

      Tell whether the key has been pressed.

   .. attribute:: released

      Tell whether the key has been released.

   .. attribute:: code

      Tell you the code of the key that has been pressed.
      You'll find the list in :class:`Keyboard`.

   .. attribute:: alt

      Tell you if the **Alt** key was pressed.

   .. attribute:: control

      Tell you if the **Control** key was pressed.

   .. attribute:: shift

      Tell you if the **Shift** key was pressed.

   .. attribute:: system

      Tell you if the **System** key was pressed.

MouseWheelEvent
---------------
.. class:: MouseWheelEvent

   The mouse wheel was scrolled.

   .. attribute:: delta

      Number of ticks the wheel has moved (positive is up, negative is down)

      :rtype: integer

   .. attribute:: position

      Position of the mouse pointer, relative to the left of the owner window.

      :rtype: :class:`sfml.system.Vector2`

MouseButtonEvent
----------------
.. class:: MouseButtonEvent

   A mouse button was pressed or released.

   .. attribute:: pressed

      Tell whether the button has been pressed.

   .. attribute:: released

      Tell whether the button has been released.

   .. attribute:: button

      Code of the button that has been pressed or released. You'll
      find the list in :class:`Mouse`.

   .. attribute:: position

      Position of the mouse pointer, relative to the left of the owner window.

      :rtype: :class:`sfml.system.Vector2`

MouseMoveEvent
--------------
.. class:: MouseMoveEvent

   The mouse cursor moved. To know the offset, you must take care of
   saving the previous value and compare with the next one.

   .. attribute:: position

      Position of the mouse pointer, relative to the left of the owner window.

      :rtype: :class:`sfml.system.Vector2`

JoystickMoveEvent
-----------------
.. class:: JoystickMoveEvent

   The joystick moved along an axis.

	.. attribute:: joystick_id
	.. attribute:: axis
	.. attribute:: position

JoystickButtonEvent
-------------------
.. class:: JoystickButtonEvent

   A joystick button was pressed or released.

	.. attribute:: pressed
	.. attribute:: released
	.. attribute:: joystick_id
	.. attribute:: button

JoystickConnectEvent
--------------------
.. class:: JoystickConnectEvent

   A joystick was connected or disconnected.

	.. attribute:: connected
	.. attribute:: disconnected
	.. attribute:: joystick_id

TouchEvent
----------
.. class:: TouchEvent

   A touch event either began or ended.

	.. attribute:: state
	.. attribute:: finger
	.. attribute:: position

TouchMoveEvent
--------------
.. class:: TouchMoveEvent

   A finger moved while touching the screen.

	.. attribute:: finger
	.. attribute:: position

SensorEvent
-----------
.. class:: SensorEvent

   A sensor value changed

	.. attribute:: type
	.. attribute:: data

VideoMode
^^^^^^^^^
.. class:: VideoMode

	:class:`VideoMode` defines a video mode (width, height, bpp)

	A video mode is defined by a width and a height (in pixels) and a depth
	(in bits per pixel).

	Video modes are used to setup windows (sfml.graphics.Window) at creation time.

	The main usage of video modes is for fullscreen mode: indeed you must
	use one of the valid video modes allowed by the OS (which are defined
	by what the monitor and the graphics card support), otherwise your
	window creation will just fail.

	:class:`VideoMode` provides a class method for retrieving the list
	of all the video modes supported by the system:
	:func:`get_fullscreen_modes()`.

	A custom video mode can also be checked directly for fullscreen
	compatibility with its :func:`is_valid()` function.

	Additionally, :class:`VideoMode` provides a class method to get the
	mode currently used by the desktop: :func:`get_desktop_mode()`. This
	allows to build windows with the same size or pixel depth as the
	current resolution.

	Usage example::

		# display the list of all the video modes available for fullscreen
		i = 0
		modes = sf.VideoMode.get_fullscreen_modes()
		for mode in modes:
			print("Mode #{0}: {1}".format(i, mode))
			i += 1

		# create a window with the same pixel depth as the desktop
		desktop = sf.VideoMode.get_desktop_mode()
		width, bpp = desktop
		window = sf.Window(sf.VideoMode(1024, 768, bpp), "pySFML Window")


   .. py:method:: VideoMode(width, height[, bits_per_pixel=32])

      Construct the video mode with its attributes.

      :param integer width: Width in pixels
      :param integer height: Height in pixels
      :param integer bits_per_pixel: Pixel depths in bits per pixel

   .. py:attribute:: size

		Video mode size, in pixels.

		:type: :class:`sfml.system.Vector2`

   .. py:attribute:: width

		Video mode width, in pixels.

		:type: integer

   .. py:attribute:: height

		Video mode height, in pixels.

		:type: integer

   .. py:attribute:: bpp

		Video mode pixel depth, in bits per pixels.

		:type: integer

   .. py:classmethod:: get_desktop_mode()

		Get the current desktop video mode.

		:type: :class:`sfml.window.VideoMode`

   .. py:classmethod:: get_fullscreen_modes()

		Retrieve all the video modes supported in fullscreen mode.

		When creating a fullscreen window, the video mode is restricted
		to be compatible with what the graphics driver and monitor
		support. This function returns the complete list of all video
		modes that can be used in fullscreen mode. The returned array
		is sorted from best to worst, so that the first element will
		always give the best mode (higher width, height and
		bits-per-pixel).

		:rtype: list of :class:`sfml.window.VideoMode`

   .. py:method:: is_valid()

      Tell whether or not the video mode is valid.

      The validity of video modes is only relevant when using
      fullscreen windows; otherwise any video mode can be used with no
      restriction.

      :rtype: bool


ContextSettings
^^^^^^^^^^^^^^^

.. class:: ContextSettings(int depth=0, int stencil=0, int antialiasing=0, int major=2, int minor=0)

   Structure defining the settings of the OpenGL context attached to a window.

   ContextSettings allows to define several advanced settings of the OpenGL context attached to a window.

   All these settings have no impact on the regular SFML rendering (graphics module) -- except the anti-aliasing level, so you may need to use this structure only if you're using SFML as a windowing system for custom OpenGL rendering.

   The depth_bits and stencil_bits properties define the number of bits per pixel requested for the (respectively) depth and stencil buffers.

   antialiasing_level represents the requested number of multisampling levels for anti-aliasing.

   major_version and minor_version define the version of the OpenGL context that you want. Only versions greater or equal to 3.0 are relevant; versions lesser than 3.0 are all handled the same way (i.e. you can use any version < 3.0 if you don't want an OpenGL 3 context).

   Please note that these values are only a hint. No failure will be reported if one or more of these values are not supported by the system; instead, SFML will try to find the closest valid match. You can then retrieve the settings that the window actually used to create its context, with sfml.graphics.Window.settings.


   .. attribute:: depth_bits

      Bits of the depth buffer.

   .. attribute:: stencil_bits

      Bits of the stencil buffer.

   .. attribute:: antialiasing_level

      Level of antialiasing.

   .. attribute:: major_version

      Major number of the context version to create.

   .. attribute:: minor_version

      Minor number of the context version to create.


Pixels
^^^^^^

.. py:class:: Pixels

	Utility class to manipulate pixels, more precisely, an array of
	unsigned char that represents an image.

	This could have been handled with the built-in type "bytes" for
	python3 or a simple string coded on 8-bits for python2 but as an
	image has two dimensions, it has to tell its width (and its height)
	too.

	Usage examples::

		image = sf.Image.from_file("icon.png")
		window = sf.Window(sf.VideoMode(640, 480), "pySFML")

		window.icon = image.pixels

		x, y, w, h = 86, 217, image.size
		pixels = image.pixels

		assert pixels[w*y+x+0] == image[x, y].r
		assert pixels[w*y+x+1] == image[x, y].g
		assert pixels[w*y+x+2] == image[x, y].b
		assert pixels[w*y+x+3] == image[x, y].a

	.. py:attribute:: width

		Get its width.

	.. py:attribute:: height

		Get its height.

	.. py:attribute:: data

		Return a copy of the data inside.

		:rtype: bytes or string


Window
^^^^^^

.. class:: Window

	Window that serves as a target for OpenGL rendering.

	:class:`Window` is the main class of the Window module.

	It defines an OS window that is able to receive an OpenGL rendering.

	A :class:`Window` can create its own new window, or be embedded into
	an already existing control using the create(handle) function. This can
	be useful for embedding an OpenGL rendering area into a view which is
	part of a bigger GUI with existing windows, controls, etc. It can also
	serve as embedding an OpenGL rendering area into a window created by
	another (probably richer) GUI library like Qt or wxWidgets.

	The :class:`Window` class provides a simple interface for
	manipulating the window: :meth:`move`, :meth:`resize`, :func:`show`/:func:`hide`, control mouse cursor,
	etc. It also provides event handling through its :func:`poll_event` and
	:func:`wait_event` functions.

	Note that OpenGL experts can pass their own parameters (antialiasing
	level, bits for the depth and stencil buffers, etc.) to the OpenGL
	context attached to the window, with the :class:`ContextSettings`
	structure which is passed as an optional argument when creating the
	window.

	Usage example::

		# declare and create a new window
		window = sf.Window(sf.VideoMode(800, 600), "pySFML Window")

		# limit the framerate to 60 frames per second (this step is optional)
		window.framerate_limit = 60

		# the main loop - ends as soon as the window is closed
		while window.is_open:
			# event processing
			for event in window.events:
				# request for closing the window
				if type(event) is sf.CloseEvent:
					window.close()

				# activate the window for OpenGL rendering
				window.active = True

				# openGL drawing commands go here...

				# end the current frame and display its contents on screen
				window.display()

   .. method:: Window(mode, title[, style[, settings]])

      Construct a new window.

      This creates the window with the size and pixel depth defined in
      mode. An optional style can be passed to customize the look and
      behaviour of the window (borders, title bar, resizable, closable,
      ...). If style contains :const:`sfml.window.Style.FULLSCREEN`, then mode
      must be a valid video mode.

      The fourth parameter is an optional structure specifying advanced
      OpenGL context settings such as antialiasing, depth-buffer bits,
      etc.

      :param sfml.window.VideoMode mode: Video mode to use (defines the width, height and depth of the rendering area of the window)
      :param str title: Title of the window
      :param sfml.window.Style style: Window style
      :param sfml.window.ContextSettings settings: Additional settings for the underlying OpenGL context

   .. method:: recreate(mode, title[, style[, settings]])

      Recreate the window.

      :param sfml.window.VideoMode mode: Video mode to use (defines the width, height and depth of the rendering area of the window)
      :param str title: Title of the window
      :param sfml.window.Style style: Window style
      :param sfml.window.ContextSettings settings: Additional settings for the underlying OpenGL context

   .. method:: close()

      Close the window and destroy all the attached resources.

      After calling this function, the :class:`Window` instance
      remains valid and you can call :func:`recreate` to recreate the
      window. All other functions such as :func:`poll_event` or
      :func:`display` will still work (i.e. you don't have to test
      :attr:`is_open` every time), and will have no effect on closed
      windows.

   .. attribute:: is_open

      Tell whether or not the window is open.

      This attribute returns whether or not the window exists. Note
      that a hidden window (:func:`hide`) is open (therefore this
      property would return **True**).

      :type: bool

   .. attribute:: opened

      .. deprecated :: 1.2

      See and use :meth:`is_open` instead. This method is kept for
      backward compatibilities.

   .. attribute:: settings

      Get the settings of the OpenGL context of the window.

      Note that these settings may be different from what was passed to
      the constructor or the :func:`recreate` function, if one or more
      settings were not supported. In this case, SFML chose the closest
      match.

      :type: :class:`sfml.window.ContextSettings`

   .. attribute:: events

      Return a generator that iterates over new events.

      :type: generator

   .. method:: poll_event()

      Pop the event on top of events stack, if any, and return it.

      This function is not blocking: if there's no pending event then
      it will return false and leave event unmodified. Note that more
      than one event may be present in the events stack, thus you
      should always call this function in a loop to make sure that you
      process every pending event.

      :return: Returns an event if any otherwise None
      :rtype: :class:`sfml.window.Event` or None

   .. method:: wait_event()

      Wait for an event and return it.

      This function is blocking: if there's no pending event then it
      will wait until an event is received. After this function returns
      (and no error occurred), the event object is always valid. This
      function is typically used when you have a thread that is
      dedicated to events handling: you want to make this thread sleep
      as long as no new event is received.

      :return: Returns an event or None if an error occurred.
      :rtype: :class:`sfml.window.Event`

   .. attribute:: position

      Return or change the position of the window on screen.

      This function only works for top-level windows (i.e. it will be
      ignored for windows created from the handle of a
      child window/control).

      :type: :class:`sfml.system.Vector2`

   .. attribute:: size

      Return or change the size of the rendering region of the window.

      :type: :class:`sfml.system.Vector2`

   .. attribute:: icon

      Allow to change the window's icon.

      The OS default icon is used by default.

      :type: :class:`sfml.window.Pixels`

   .. attribute:: visible

      Set or get the window's visibility status. You shouldn't rely on the getter.

      The window is shown by default.

      :type: bool

   .. method:: show()

      Show the window.

      It has no effect if the window was already shown.

   .. method:: hide()

      Hide the window.

      It has no effect if the window was already hidden.

   .. attribute:: vertical_synchronization

      Get or set the vertical synchronization.

      Activating vertical synchronization will limit the number of
      frames displayed to the refresh rate of the monitor. This can
      avoid some visual artifacts, and limit the framerate to a good
      value (but not constant across different computers).. You
      shouldn't rely on the getter.

      Vertical synchronization is disabled by default

      :type: bool

   .. attribute:: mouse_cursor_visible

      Show or hide the mouse cursor.

      The mouse cursor is visible by default

      :type: bool

   .. attribute:: key_repeat_enabled

      Enable or disable automatic key-repeat.

      If key repeat is enabled, you will receive repeated
      :class:`KeyPressed` events while keeping a key pressed. If it is
      disabled, you will only get a single event when the key is
      pressed.

      Key repeat is enabled by default.

      :type: bool

   .. attribute:: framerate_limit

      Limit the framerate to a maximum fixed frequency.

      If a limit is set, the window will use a small delay after each
      call to :func:`display` to ensure that the current frame lasted
      long enough to match the framerate limit. pySFML will try to
      match the given limit as much as it can, but since it internally
      uses :func:`.sleep`, whose precision depends on the underlying
      OS, the results may be a little imprecise as well (for example,
      you can get 65 FPS when requesting 60).

      :type: integer

   .. attribute:: joystick_threshold

      Change the joystick threshold.

      The joystick threshold is the value below which no
      :class:`JoystickMoveEvent` will be generated.

      The threshold value is 0.1 by default.

      :type: float

   .. attribute:: active

      Activate or deactivate the window as the current target for
      OpenGL rendering.

      A window is active only on the current thread, if you want to
      make it active on another thread you have to deactivate it on the
      previous thread first if it was active. Only one window can be
      active on a thread at a time, thus the window previously active
      (if any) automatically gets deactivated. This is not to be confused with
      :meth:`request_focus`.

   .. method:: request_focus()

      Request the current window to be made the active foreground window.

      At any given time, only one window may have the input focus to receive
      input events such as keystrokes or mouse events. If a window requests
      focus, it only hints to the operating system, that it would like to be
      focused. The operating system is free to deny the request. This is not to
      be confused with :attr:`active`.

   .. method:: has_focus()

      Check whether the window has the input focus.

      At any given time, only one window may have the input focus to receive
      input events such as keystrokes or most mouse events.

      :return: True if window has focus, false otherwise
      :rtype: bool

   .. method:: display()

      Display on screen what has been rendered to the window so far.

      This function is typically called after all OpenGL rendering has
      been done for the current frame, in order to show it on screen.

   .. attribute:: system_handle

      Get the OS-specific handle of the window.

      The type of the returned handle is :class`sfml.graphics.WindowHandle`, which
      is a typedef to the handle type defined by the OS. You shouldn't need to
      use this function, unless you have very specific stuff to implement that
      SFML doesn't support, or implement a temporary workaround until a bug is
      fixed.

   .. method:: on_create

      Function called after the window has been created.

      This function is called so that derived classes can perform their
      own specific initialization as soon as the window is created.

      Usage examples::

         class MyWindow(sf.Window):
            def __init__(self):
               sf.Window.__init__(self, sf.VideoMode(640, 480), "pySFML")

            def on_create(self):
               print("Window created or recreated...")
               do_something()

      Reimplemented in :class:`sfml.graphics.RenderWindow`

   .. method:: on_resize

      Function called after the window has been resized.

      This function is called so that derived classes can perform
      custom actions when the size of the window changes.

      Usage examples::

         class MyWindow(sf.Window):
            def __init__(self):
               sf.Window.__init__(self, sf.VideoMode(640, 480), "pySFML")

            def on_resize(self):
               print("Window size changed")
               do_something()

      Reimplemented in :class:`sf.RenderWindow`


Keyboard
^^^^^^^^

.. class:: Keyboard

   Give access to the real-time state of the keyboard.

   :class:`Keyboard` provides an interface to the state of the
   keyboard.

   It only contains class methods (a single keyboard is assumed), so
   it's not meant to be instantiated.

   This class allows users to query the keyboard state at any time and
   directly, without having to deal with a window and its events.
   Compared to :class:`MouseButtonEvent`
   events, :class:`Keyboard` can retrieve the state of a key at any
   time (you don't need to store and update a boolean on your side in
   order to know if a key is pressed or released), and you always get
   the real state of the keyboard, even if keys are pressed or released
   when your window is out of focus and no event is triggered.

   Usage example::

      if sf.Keyboard.is_key_pressed(sf.Keyboard.LEFT)
         # move left...
      elif sf.Keyboard.is_key_pressed(sf.Keyboard.RIGHT):
         # move right...
      elif sf.Keyboard.is_key_pressed(sf.Keyboard.ESCAPE):
         # quit...

   +------------+-----------------------------------------------------------------------------+
   | Key        | Description                                                                 |
   +============+=============================================================================+
   | A          | The A key.                                                                  |
   +------------+-----------------------------------------------------------------------------+
   | B          | The B key.                                                                  |
   +------------+-----------------------------------------------------------------------------+
   | C          | The C key.                                                                  |
   +------------+-----------------------------------------------------------------------------+
   | D          | The D key.                                                                  |
   +------------+-----------------------------------------------------------------------------+
   | E          | The E key.                                                                  |
   +------------+-----------------------------------------------------------------------------+
   | F          | The F key.                                                                  |
   +------------+-----------------------------------------------------------------------------+
   | G          | The G key.                                                                  |
   +------------+-----------------------------------------------------------------------------+
   | H          | The H key.                                                                  |
   +------------+-----------------------------------------------------------------------------+
   | I          | The I key.                                                                  |
   +------------+-----------------------------------------------------------------------------+
   | J          | The J key.                                                                  |
   +------------+-----------------------------------------------------------------------------+
   | K          | The K key.                                                                  |
   +------------+-----------------------------------------------------------------------------+
   | L          | The L key.                                                                  |
   +------------+-----------------------------------------------------------------------------+
   | M          | The M key.                                                                  |
   +------------+-----------------------------------------------------------------------------+
   | N          | The N key.                                                                  |
   +------------+-----------------------------------------------------------------------------+
   | O          | The O key.                                                                  |
   +------------+-----------------------------------------------------------------------------+
   | P          | The P key.                                                                  |
   +------------+-----------------------------------------------------------------------------+
   | Q          | The Q key.                                                                  |
   +------------+-----------------------------------------------------------------------------+
   | R          | The R key.                                                                  |
   +------------+-----------------------------------------------------------------------------+
   | S          | The S key.                                                                  |
   +------------+-----------------------------------------------------------------------------+
   | T          | The T key.                                                                  |
   +------------+-----------------------------------------------------------------------------+
   | U          | The U key.                                                                  |
   +------------+-----------------------------------------------------------------------------+
   | V          | The V key.                                                                  |
   +------------+-----------------------------------------------------------------------------+
   | W          | The W key.                                                                  |
   +------------+-----------------------------------------------------------------------------+
   | X          | The X key.                                                                  |
   +------------+-----------------------------------------------------------------------------+
   | Y          | The Y key.                                                                  |
   +------------+-----------------------------------------------------------------------------+
   | Z          | The Z key.                                                                  |
   +------------+-----------------------------------------------------------------------------+
   | NUM0       | The 0 key.                                                                  |
   +------------+-----------------------------------------------------------------------------+
   | NUM1       | The 1 key.                                                                  |
   +------------+-----------------------------------------------------------------------------+
   | NUM2       | The 2 key.                                                                  |
   +------------+-----------------------------------------------------------------------------+
   | NUM3       | The 3 key.                                                                  |
   +------------+-----------------------------------------------------------------------------+
   | NUM4       | The 4 key.                                                                  |
   +------------+-----------------------------------------------------------------------------+
   | NUM5       | The 5 key.                                                                  |
   +------------+-----------------------------------------------------------------------------+
   | NUM6       | The 6 key.                                                                  |
   +------------+-----------------------------------------------------------------------------+
   | NUM7       | The 7 key.                                                                  |
   +------------+-----------------------------------------------------------------------------+
   | NUM8       | The 8 key.                                                                  |
   +------------+-----------------------------------------------------------------------------+
   | NUM9       | The 9 key.                                                                  |
   +------------+-----------------------------------------------------------------------------+
   | ESCAPE     | The Escape key.                                                             |
   +------------+-----------------------------------------------------------------------------+
   | L_CONTROL  | The left Control key.                                                       |
   +------------+-----------------------------------------------------------------------------+
   | L_SHIFT    | The left Shift key.                                                         |
   +------------+-----------------------------------------------------------------------------+
   | L_ALT      | The left Alt key.                                                           |
   +------------+-----------------------------------------------------------------------------+
   | L_SYSTEM   | The left OS specific key: window (Windows and Linux), apple (MacOS X), ...  |
   +------------+-----------------------------------------------------------------------------+
   | R_CONTROL  | The right Control key.                                                      |
   +------------+-----------------------------------------------------------------------------+
   | R_SHIFT    | The right Shift key.                                                        |
   +------------+-----------------------------------------------------------------------------+
   | R_ALT      | The right Alt key.                                                          |
   +------------+-----------------------------------------------------------------------------+
   | R_SYSTEM   | The right OS specific key: window (Windows and Linux), apple (MacOS X), ... |
   +------------+-----------------------------------------------------------------------------+
   | MENU       | The Menu key.                                                               |
   +------------+-----------------------------------------------------------------------------+
   | L_BRACKET  | The [ key.                                                                  |
   +------------+-----------------------------------------------------------------------------+
   | R_BRACKET  | The ] key.                                                                  |
   +------------+-----------------------------------------------------------------------------+
   | SEMI_COLON | The ; key.                                                                  |
   +------------+-----------------------------------------------------------------------------+
   | COMMA      | The , key.                                                                  |
   +------------+-----------------------------------------------------------------------------+
   | PERIOD     | The . key.                                                                  |
   +------------+-----------------------------------------------------------------------------+
   | QUOTE      | The ' key.                                                                  |
   +------------+-----------------------------------------------------------------------------+
   | SLASH      | The / key.                                                                  |
   +------------+-----------------------------------------------------------------------------+
   | BACK_SLASH | The \ key.                                                                  |
   +------------+-----------------------------------------------------------------------------+
   | TILDE      | The ~ key.                                                                  |
   +------------+-----------------------------------------------------------------------------+
   | EQUAL      | The = key.                                                                  |
   +------------+-----------------------------------------------------------------------------+
   | DASH       | The - key.                                                                  |
   +------------+-----------------------------------------------------------------------------+
   | SPACE      | The Space key.                                                              |
   +------------+-----------------------------------------------------------------------------+
   | RETURN     | The Return key.                                                             |
   +------------+-----------------------------------------------------------------------------+
   | BACK_SPACE | The Backspace key.                                                          |
   +------------+-----------------------------------------------------------------------------+
   | TAB        | The Tabulation key.                                                         |
   +------------+-----------------------------------------------------------------------------+
   | PAGE_UP    | The Page up key.                                                            |
   +------------+-----------------------------------------------------------------------------+
   | PAGE_DOWN  | The Page down key.                                                          |
   +------------+-----------------------------------------------------------------------------+
   | END        | The End key.                                                                |
   +------------+-----------------------------------------------------------------------------+
   | HOME       | The Home key.                                                               |
   +------------+-----------------------------------------------------------------------------+
   | INSERT     | The Insert key.                                                             |
   +------------+-----------------------------------------------------------------------------+
   | DELETE     | The Delete key.                                                             |
   +------------+-----------------------------------------------------------------------------+
   | ADD        | \+                                                                          |
   +------------+-----------------------------------------------------------------------------+
   | SUBTRACT   | \-                                                                          |
   +------------+-----------------------------------------------------------------------------+
   | MULTIPLY   | \*                                                                          |
   +------------+-----------------------------------------------------------------------------+
   | DIVIDE     | /                                                                           |
   +------------+-----------------------------------------------------------------------------+
   | LEFT       | Left arrow.                                                                 |
   +------------+-----------------------------------------------------------------------------+
   | RIGHT      | Right arrow.                                                                |
   +------------+-----------------------------------------------------------------------------+
   | UP         | Up arrow.                                                                   |
   +------------+-----------------------------------------------------------------------------+
   | DOWN       | Down arrow.                                                                 |
   +------------+-----------------------------------------------------------------------------+
   | NUMPAD0    | The numpad 0 key.                                                           |
   +------------+-----------------------------------------------------------------------------+
   | NUMPAD1    | The numpad 1 key.                                                           |
   +------------+-----------------------------------------------------------------------------+
   | NUMPAD2    | The numpad 2 key.                                                           |
   +------------+-----------------------------------------------------------------------------+
   | NUMPAD3    | The numpad 3 key.                                                           |
   +------------+-----------------------------------------------------------------------------+
   | NUMPAD4    | The numpad 4 key.                                                           |
   +------------+-----------------------------------------------------------------------------+
   | NUMPAD5    | The numpad 5 key.                                                           |
   +------------+-----------------------------------------------------------------------------+
   | NUMPAD6    | The numpad 6 key.                                                           |
   +------------+-----------------------------------------------------------------------------+
   | NUMPAD7    | The numpad 7 key.                                                           |
   +------------+-----------------------------------------------------------------------------+
   | NUMPAD8    | The numpad 8 key.                                                           |
   +------------+-----------------------------------------------------------------------------+
   | NUMPAD9    | The numpad 9 key.                                                           |
   +------------+-----------------------------------------------------------------------------+
   | F1         | The F1 key.                                                                 |
   +------------+-----------------------------------------------------------------------------+
   | F2         | The F2 key.                                                                 |
   +------------+-----------------------------------------------------------------------------+
   | F3         | The F3 key.                                                                 |
   +------------+-----------------------------------------------------------------------------+
   | F4         | The F4 key.                                                                 |
   +------------+-----------------------------------------------------------------------------+
   | F5         | The F5 key.                                                                 |
   +------------+-----------------------------------------------------------------------------+
   | F6         | The F6 key.                                                                 |
   +------------+-----------------------------------------------------------------------------+
   | F7         | The F7 key.                                                                 |
   +------------+-----------------------------------------------------------------------------+
   | F8         | The F8 key.                                                                 |
   +------------+-----------------------------------------------------------------------------+
   | F9         | The F9 key.                                                                 |
   +------------+-----------------------------------------------------------------------------+
   | F10        | The F10 key.                                                                |
   +------------+-----------------------------------------------------------------------------+
   | F11        | The F11 key.                                                                |
   +------------+-----------------------------------------------------------------------------+
   | F12        | The F12 key.                                                                |
   +------------+-----------------------------------------------------------------------------+
   | F13        | The F13 key.                                                                |
   +------------+-----------------------------------------------------------------------------+
   | F14        | The F14 key.                                                                |
   +------------+-----------------------------------------------------------------------------+
   | F15        | The F15 key.                                                                |
   +------------+-----------------------------------------------------------------------------+
   | PAUSE      | The Pause key.                                                              |
   +------------+-----------------------------------------------------------------------------+
   | KEY_COUNT  | The total number of keyboard keys                                           |
   +------------+-----------------------------------------------------------------------------+

   .. classmethod:: is_key_pressed(key)

      Check if a key is pressed.

      :param key: Key to check
      :type key: :class:`sfml.window.Keyboard`'s constant

   .. classmethod:: set_virtual_keyboard_visible(visible)

      Warning: the virtual keyboard is not supported on all systems. It will
      typically be implemented on mobile OSes (Android, iOS) but not on desktop
      OSes (Windows, Linux, ...).

      If the virtual keyboard is not available, this function does nothing.

      :param visible: True to show, false to hide
      :type visible: boolean


Joystick
^^^^^^^^

.. class:: Joystick

   Give access to the real-time state of the joysticks.

   :class:`Joystick` provides an interface to the state of the
   joysticks.

   It only contains class methods, so it's not meant to be instantiated.
   Instead, each joystick is identified by an index that is passed to
   the functions of this class.

   This class allows users to query the state of joysticks at any time
   and directly, without having to deal with a window and its events.
   Compared to the :class:`JoystickButtonEvent` and
   :class:`JoystickMoveEvent` events, :class:`Joystick` can
   retrieve the state of axes and buttons of joysticks at any time (you
   don't need to store and update a boolean on your side in order to
   know if a button is pressed or released), and you always get the
   real state of joysticks, even if they are moved, pressed or released
   when your window is out of focus and no event is triggered.

   SFML supports:

       * 8 joysticks (:const:`Joystick.COUNT`)
       * 32 buttons per joystick (:const:`Joystick.BUTTON_COUNT`)
       * 8 axes per joystick (:const:`Joystick.AXIS_COUNT`)

   Unlike the keyboard or mouse, the state of joysticks is sometimes
   not directly available (depending on the OS), therefore an
   :func:`update` function must be called in order to update the
   current state of joysticks. When you have a window with event
   handling, this is done automatically, you don't need to call
   anything. But if you have no window, or if you want to check
   joysticks state before creating one, you must call
   :func:`Joystick.update` explicitly.

   Usage example::

      # is joystick #0 connected ?
      connected = sf.Joystick.is_connected(0)

      # how many button does joystick #0 support ?
      buttons = sf.Joystick.get_button_count(0)

      # does joystick # define a X axis ?
      has_X = sf.Joystick.has_axis(0, sf.Joystick.X)

      # is button #2 pressed on joystick #0 ?
      pressed = sf.Joystick.is_button_pressed(0, 2)

      # what's the current position of the Y axis on joystick #0?
      position = sf.Joystick.get_axis_position(0, sf.Joystick.Y)

   +-------+--------------------------------------+
   | Axis  | Description                          |
   +=======+======================================+
   | X     | The X axis.                          |
   +-------+--------------------------------------+
   | Y     | The X axis.                          |
   +-------+--------------------------------------+
   | Z     | The X axis.                          |
   +-------+--------------------------------------+
   | R     | The X axis.                          |
   +-------+--------------------------------------+
   | U     | The X axis.                          |
   +-------+--------------------------------------+
   | V     | The X axis.                          |
   +-------+--------------------------------------+
   | POV_X | The X axis of the point-of-view hat. |
   +-------+--------------------------------------+
   | POV_Y | The Y axis of the point-of-view hat. |
   +-------+--------------------------------------+

   .. data:: COUNT

         Maximum number of supported joysticks.
   .. data:: BUTTON_COUNT

         Maximum number of supported buttons.
   .. data:: AXIS_COUNT

         Maximum number of supported axes.

   .. classmethod:: is_connected(joystick)

      Check if a joystick is connected.

      If the joystick is not connected, this function returns false.

      :param integer joystick: Index of the joystick to check
      :rtype: boolean

   .. classmethod:: get_button_count(joystick)

      Return the number of buttons supported by a joystick.

      If the joystick is not connected, this function returns 0.

      :param integer joystick: Index of the joystick
      :rtype: integer

   .. classmethod:: has_axis(joystick, axis)

      Check if a joystick supports a given axis.

      If the joystick is not connected, this function returns false.

      :param integer joystick: Index of the joystick
      :param integer axis: Axis to check
      :rtype: boolean

   .. classmethod:: is_button_pressed(joystick, button)

      Check if a joystick button is pressed.

      If the joystick is not connected, this function returns false.

      :param integer joystick: Index of the joystick
      :param integer axis: Button to check
      :rtype: boolean

   .. classmethod:: get_axis_position(joystick, axis)

      Get the current position of a joystick axis.

      If the joystick is not connected, this function returns 0.

      :param integer joystick: Index of the joystick
      :param integer axis: Axis to check
      :rtype: boolean

   .. classmethod:: get_identification(joystick)

      Get the joystick information

      :param integer joystick: Index of the joystick
      :return: A tuple containing the name of the joystick, the manufacturer and product identifier
      :rtype: tuple

   .. classmethod:: update()

      Update the states of all joysticks.

      This function is used internally by SFML, so you normally don't
      have to call it explicitly. However, you may need to call it if
      you have no window yet (or no window at all): in this case the
      joysticks states are not updated automatically.


Mouse
^^^^^

.. class:: Mouse

   Give access to the real-time state of the mouse.

   :class:`Mouse` provides an interface to the state of the mouse.

   It only contains class methods (a single mouse is assumed), so it's
   not meant to be instantiated.

   This class allows users to query the mouse state at any time and
   directly, without having to deal with a window and its events.
   Compared to the :class:`MouseMoveEvent`, :class:`MouseButtonEvent`
   events, :class:`Mouse` can retrieve
   the state of the cursor and the buttons at any time (you don't need
   to store and update a boolean on your side in order to know if a
   button is pressed or released), and you always get the real state of
   the mouse, even if it is moved, pressed or released when your window
   is out of focus and no event is triggered.

   The :func:`set_position` and :func:`get_position` functions can be
   used to change or retrieve the current position of the mouse
   pointer. There are two versions: one that operates in global
   coordinates (relative to the desktop) and one that operates in
   window coordinates (relative to a specific window).

   Usage example::

      if sf.Mouse.is_button_pressed(sf.Mouse.LEFT):
         # left click...

      # get global mouse position
      position = sf.Mouse.position
      # or: position = sf.Mouse.get_position()

      # set mouse position relative to a window
      sf.Mouse.set_position(sf.Vector2(100, 200), window)

   +--------------+------------------------------------+
   | Button       | Description                        |
   +==============+====================================+
   | LEFT         | The left mouse button.             |
   +--------------+------------------------------------+
   | RIGHT        | The right mouse button.            |
   +--------------+------------------------------------+
   | MIDDLE       | The middle (wheel) mouse button.   |
   +--------------+------------------------------------+
   | X_BUTTON1    | The first extra mouse button.      |
   +--------------+------------------------------------+
   | X_BUTTON2    | The second extra mouse button.     |
   +--------------+------------------------------------+
   | BUTTON_COUNT | The total number of mouse buttons. |
   +--------------+------------------------------------+

   .. classmethod:: is_button_pressed(button)

      Check if a mouse button is pressed.

      :param integer button: Button to check
      :type button: integer (an :class:`sfml.window.Mouse`'s constant)
      :rtype: bool


   .. classmethod:: get_position([relative_to])

      Get the current position of the mouse in window coordinates.

      This function returns the current position of the mouse cursor,
      relative to the given window.

      :param sfml.window.Window relative_to: Reference window
      :rtype: bool

   .. classmethod:: set_position(position[, relative_to])

      Set the current position of the mouse in window coordinates.

      This function sets the current position of the mouse cursor,
      relative to the given window.

      :param sfml.system.Vector2 position: New position of the mouse
      :param sfml.window.Window relative_to: Reference window


Touch
^^^^^

.. class:: Touch

   :class:`Touch` provides an interface to the state of the touches. It only
   contains static functions, so it's not meant to be instantiated.

   This class allows users to query the touches state at any time and directly,
   without having to deal with a window and its events. Compared to the
   :class:`TouchEvent` and :class:`TouchMoveEvent`, :class:`Touch` can retrieve
   the state of the touches at any time (you don't need to store and update a
   boolean on your side in order to know if a touch is down), and you always
   get the real state of the touches, even if they happen when your window is
   out of focus and no event is triggered.

   The :meth:`get_position` function can be used to retrieve the current
   position of a touch. There are two versions: one that operates in global
   coordinates (relative to the desktop) and one that operates in window
   coordinates (relative to a specific window).

   Touches are identified by an index (the "finger"), so that in multi-touch
   events, individual touches can be tracked correctly. As long as a finger
   touches the screen, it will keep the same index even if other fingers start
   or stop touching the screen in the meantime. As a consequence, active touch
   indices may not always be sequential (i.e. touch number 0 may be released
   while touch number 1 is still down).

   Usage example::

      if sf.Touch.is_down(0):
         # touch 0 is down

      # get global position of touch 1
      global_pos = sf.Touch.get_position(1)

      # get position of touch 1 relative to a window
      relative_pos = sf.Touch.get_position(1, window)

   .. classmethod:: is_down(finger)

      Check if a touch event is currently down.

      :param int finger: Finger index
      :return: True if finger is currently touching the screen, false otherwise
      :rtype: boolean

   .. classmethod:: get_position(finger[, window])

      Get the current position of a touch in desktop coordinates.

      This function returns the current touch position in global (desktop)
      coordinates.

      :param int finger: Finger index
      :param sfml.window.Window window: Reference window
      :return: Current position of finger, or undefined if it's not down
      :rtype: :class:`Vector2`

Sensor
^^^^^^

.. class:: Sensor

   :class:`Sensor` provides an interface to the state of the various sensors
   that a device provides. It only contains static functions, so it's not meant
   to be instantiated.

   This class allows users to query the sensors values at any time and directly,
   without having to deal with a window and its events. Compared to the
   :class:`SensorEvent`, :class:`Sensor` can retrieve the state of a sensor at
   any time (you don't need to store and update its current value on your side).

   Depending on the OS and hardware of the device (phone, tablet, ...), some
   sensor types may not be available. You should always check the availability
   of a sensor before trying to read it, with the :meth:`is_available` function.

   You may wonder why some sensor types look so similar, for example
   :attr:`ACCELEROMETER` and :attr:`GRAVITY` / :attr:`USER_ACCELERATION`. The
   first one is the raw measurement of the acceleration, and takes in account
   both the earth gravity and the user movement. The others are more precise:
   they provide these components separately, which is usually more useful. In
   fact they are not direct sensors, they are computed internally based on the
   raw acceleration and other sensors. This is exactly the same for
   :attr:`GYROSCOPE` vs :attr:`ORIENTATION`.

   Because sensors consume a non-negligible amount of current, they are all
   disabled by default. You must call :meth:`set_enabled` for each sensor in
   which you are interested.

   Usage example::

      if sf.Sensor.is_available(sf.Sensor.GRAVITY):
         # gravity sensor is available

      # enable the gravity sensor
      sf.Sensor.set_enabled(sf.Sensor.GRAVITY)

      # get the current value of gravity
      gravity = sf.Sensor.get_value(sf.Sensor.GRAVITY)

   +-------------------+------------------------------------------------------------------------------------------------+
   | Sensor            | Description                                                                                    |
   +===================+================================================================================================+
   | ACCELEROMETER     | Measures the raw acceleration (m/s²)                                                           |
   +-------------------+------------------------------------------------------------------------------------------------+
   | GYROSCOPE         | Measures the raw rotation rates (degrees/s)                                                    |
   +-------------------+------------------------------------------------------------------------------------------------+
   | MAGNETOMETER      | Measures the ambient magnetic field (micro-teslas)                                             |
   +-------------------+------------------------------------------------------------------------------------------------+
   | GRAVITY           | Measures the direction and intensity of gravity, independent of device acceleration (m/s²)     |
   +-------------------+------------------------------------------------------------------------------------------------+
   | USER_ACCELERATION | Measures the direction and intensity of device acceleration, independent of the gravity (m/s²) |
   +-------------------+------------------------------------------------------------------------------------------------+
   | ORIENTATION       | Measures the absolute 3D orientation (degrees)                                                 |
   +-------------------+------------------------------------------------------------------------------------------------+
   | SENSOR_COUNT      | The total number of sensor                                                                     |
   +-------------------+------------------------------------------------------------------------------------------------+

   .. classmethod:: is_available(sensor)

      Check if a sensor is available on the underlying platform

      :param bool sensor: Sensor to check
      :return: True if the sensor is available, false otherwise
      :rtype: boolean

   .. classmethod:: set_enabled(sensor, enabled)

      Enable or disable a sensor.

      All sensors are disabled by default, to avoid consuming too much battery
      power. Once a sensor is enabled, it starts sending events of the
      corresponding type.

      This function does nothing if the sensor is unavailable.

      :param int sensor: Sensor to enable
      :param bool enabled: True to enable, false to disable

   .. classmethod:: get_value(sensor)

      Get the current sensor value.

      :param int sensor: Sensor to read
      :return: The current sensor value
      :rtype: :class:`sfml.system.Vector3`

Context
^^^^^^^

.. class:: Context

   Class holding a valid drawing context.

   If you need to make OpenGL calls without having an active window
   (like in a thread), you can use an instance of this class to get a
   valid context.

   Having a valid context is necessary for *every* OpenGL call.

   Note that a context is only active in its current thread, if you
   create a new thread it will have no valid context by default.

   To use an :class:`Context` instance, just construct it and let it
   live as long as you need a valid context. No explicit activation is
   needed, all it has to do is to exist. Its destructor will take care
   of deactivating and freeing all the attached resources.

   Usage example::

      def thread_function():
         context = sf.Context()
         # from now on, you have a valid context

         # you can make OpenGL calls
         glClear(GL_DEPTH_BUFFER_BIT)

      # the context is automatically deactivated and destroyed by the
      # sf.Context destructor