.. _ui.lua:

ui.lua
---------------

This script contains UI related functions like for moving the mouse or the
view or clicking on fields and UI elements.

.. Note::
   Do not use any of these functions for multiplayer scenarios or winconditions,
   because a game will likely desync then.

To make these functions available include this file at the beginning
of a script via:

.. code-block:: lua

   include "scripting/ui.lua"


.. function:: scroll_to_map_pixel(map_pixel[, return_immediate = false])

   .. versionchanged:: 1.2.1
      Added parameter ``return_immediate``.

   Make a nice moving transition to center on the 'map_pixel', which is a table
   that must contain 'x' and 'y' keys. The function will return as soon as
   the transition is completed. Usually this function is useful when
   scrolling back after using :meth:`scroll_to_field` or
   :meth:`wait_for_roadbuilding_and_scroll`. The return value of these
   functions can be passed to ``scroll_to_map_pixel`` to move back to the
   previous location.

   :arg map_pixel: pixels to focus on.
   :type map_pixel: :class:`table`
   :arg return_immediate: Whether to return from the function call immediately, even if the transition is still ongoing.
   :type return_immediate: :class:`boolean`

   Example:

   .. code-block:: lua

      include "scripting/ui.lua"
      include "scripting/messages.lua"

      local rocks_field = wl.Game().map:get_field(12, 34)

      -- scroll to 'rocks_field'; 'prior_location' will be the position from where we are scrolling from
      local prior_location = scroll_to_field(rocks_field)
      campaign_message_box({title= "New observation",
                            body = "We have found some rocks!",
                            position = "top"})
      -- after clicking 'OK' scroll back
      scroll_to_map_pixel(prior_location)


.. function:: scroll_to_field(field[, return_immediate = false])

   .. versionchanged:: 1.2.1
      Added parameter ``return_immediate``.

   Make a nice moving transition to center the 'field' on screen. The
   function will return as soon as the transition is completed.

   :arg field: Field to center the view on
   :type field: :class:`wl.map.Field`
   :arg return_immediate: Whether to return from the function call immediately, even if the transition is still ongoing.
   :type return_immediate: :class:`boolean`

   :returns: the prior center map pixel of the MapView as a table containing
      'x' and 'y' keys.


.. function:: mouse_to_pixel(x, y[, return_immediate = false])

   .. versionchanged:: 1.2.1
      Added parameter ``return_immediate``.

   Make a nice moving transition for the mouse to the given pixels relative
   to the top left corner of the screen. The function will return as soon as
   the transition is completed.

   :arg x: x position to move the mouse to
   :type x: :class:`integer`
   :arg y: y position to move the mouse to
   :type y: :class:`integer`
   :arg return_immediate: Whether to return from the function call immediately, even if the transition is still ongoing.
   :type return_immediate: :class:`boolean`


.. function:: mouse_to_field(field[, return_immediate = false])

   .. versionchanged:: 1.2.1
      Added parameter ``return_immediate``.

   Move the mouse on the given field. Makes sure that the field is inside
   the current view area by scrolling the view if necessary. The function
   will return as soon as the transition is completed.

   :arg field: Field to mouse to
   :type field: :class:`wl.map.Field`
   :arg return_immediate: Whether to return from the function call immediately, even if the transition is still ongoing.
   :type return_immediate: :class:`boolean`


.. function:: mouse_to_panel(panel[, return_immediate = false])

   .. versionchanged:: 1.2.1
      Added parameter ``return_immediate``.

   Move the mouse to the center of the given ui element. The function will
   return as soon as the transition is completed.

   :arg panel: Panel to mouse to
   :type panel: :class:`wl.ui.Panel`
   :arg return_immediate: Whether to return from the function call immediately, even if the transition is still ongoing.
   :type return_immediate: :class:`boolean`


.. function:: click_building(player, building_name)

   Click on the first building of type 'building_name' owned by 'player'.

   :arg player: Player to search building for.
   :type player: :class:`wl.game.Player`
   :arg building_name: Building name to look for.
   :type building_name: :class:`string`

   :returns: :const:`true` if a building was clicked


.. function:: click_button(name)

   Searches through all open windows for a button named 'name' and, if
   found, clicks it.

   This function is used only by the testsuite.

   :arg name: Name of the button to click.
   :type name: :class:`string`

   :returns: :const:`true` if a button was clicked


.. function:: close_windows()

   Closes all open windows.


.. function:: wait_for_roadbuilding()

   Sleeps while player is in roadbuilding mode.


.. function:: wait_for_roadbuilding_and_scroll(field)

   Sleeps while player is in roadbuilding mode, then calls
   :meth:`scroll_to_field(field) <scroll_to_field>`.

   :arg field: Field to scroll to
   :type field: :class:`wl.map.Field`

   :returns: The return value of `scroll_to_field`.