## Selection control

Control Module - Selection - Controls players who have a selection planner, mostly event handlers

### Dependencies

utils.event
utils.global

### Events

on_player_selection_start | When a player enters selection mode
on_player_selection_end | When a player leaves selection mode

### Functions

start(player, selection_name[, single_use=false]) | Let a player select an area by providing a selection planner
stop(player) | Stop a player selection by removing the selection planner
get_arguments(player) | Get the selection arguments for a player
is_selecting(player[, selection_name]) | Test if a player is selecting something
on_selection(selection_name, handler) | Filter on_player_selected_area to this custom selection, appends the selection arguments
on_alt_selection(string, function) | Filter on_player_alt_selected_area to this custom selection, appends the selection arguments

### Dependencies

# utils.event
# utils.global

### Events

# on_player_selection_start

  When a player enters selection mode

  Event Parameters:
  - player_index : (number) the player index of the player who entered selection mode
  - selection : (string) the name of the selection being made
# on_player_selection_end

  When a player leaves selection mode

  Event Parameters:
  - player_index : (number) the player index of the player who left selection mode
  - selection : (string) the name of the selection which ended

### Functions

# start(player, selection_name[, single_use=false])

  Let a player select an area by providing a selection planner

  Parameters:
  - player : (LuaPlayer) The player to place into selection mode
  - selection_name : (string) The name of the selection to start, used with on_selection
  - single_use : (boolean) When true the selection will stop after first use (default: false)
# stop(player)

  Stop a player selection by removing the selection planner

  Parameters:
  - player : (LuaPlayer) The player to exit out of selection mode
# get_arguments(player)

  Get the selection arguments for a player

  Parameters:
  - player : (LuaPlayer) The player to get the selection arguments for
# is_selecting(player[, selection_name])

  Test if a player is selecting something

  Parameters:
  - player : (LuaPlayer) The player to test
  - selection_name : (string) If given will only return true if the selection is this selection (optional)
# on_selection(selection_name, handler)

  Filter on_player_selected_area to this custom selection, appends the selection arguments

  Parameters:
  - selection_name : (string) The name of the selection to listen for
  - handler : (function) The event handler
# on_alt_selection(string, function)

  Filter on_player_alt_selected_area to this custom selection, appends the selection arguments

  Parameters:
  - string : selection_name The name of the selection to listen for
  - function : handler The event handler