UI.ListShips x:Int, y:Int, [flags:Any, ok:Str,
  heading:Str]

List ships (visual scanner).

Lists all ships at position x,y using the Visual Scan window. The last three parameters are optional and modify behaviour details.

The flags parameter contains a list of flag letters:

  • "f": allow the user to choose foreign ships. If this is not specified, the "OK" button will be disabled for foreign ships. This flag implies "A".
  • "a": list all ships at the specified location. By default, only your ships are listed.
  • "e": when there is only one matching ship, return it and do not display the dialog at all.
  • "s": only show ships that we "safely" see, i.e. no guessed ships.
  • a ship Id to exclude. That ship will not be listed.

The ok string specifies the name of the "OK" button, it defaults to "OK". Likewise, the heading specifies the window title, it defaults to "List Ships".

The chosen ship Id (or EMPTY if the user canceled) is returned in UI.Result. If no ship matches, a dialog is displayed and EMPTY is returned. This command can't be used in text mode.

For example, this command sequence sets a "Tow" mission:

 UI.ListShips Loc.X, Loc.Y, "fae" & Id, "Choose", "Tow Ship"
 If UI.Result Then SetMission 7, 0, UI.Result

This command is equivalent to the CtrlF1 key command (switch to ship):

 UI.ListShips UI.X, UI.Y, "e" & Id
 If UI.Result Then UI.GotoScreen 1, UI.Result

Since: PCC 1.1.1, PCC2 1.99.10

See also: UI.ChooseObject, UI.ListShipPrediction