PlanetsCentral

 With Listbox(title:Str, Optional current:Int, width:Int, height:Int, help:Str) Do
   AddItem id:Int, text:Str
   Run
 EndWith

This command sequence creates a standard list box. It consists of three parts:

• the With Listbox() part creates a blank, still invisible list box template;
• the AddItem part adds items to the list box. You can use any number of these. Items are identified by their id value which is an integer between 0 and 2^31-1 (PCC 1.1.6 and below accept only values up to 32767);
• the Run part finally displays the list box and lets the user choose from it. You can repeat Run as often as you wish.

The parameters are as follows:

• title: a string that is displayed in the title bar of the list box. This is the only mandatory parameter for Listbox();
• current: the id value of the entry which will be selected by default when the list box opens. When there's no item with that identifier, the first one will be selected;
• width: the width of the list box in pixels. Must be between 200 and 1000, default is 320;
• height: the height of the list box in lines. Must be between 3 and 100, default is number of items in list box. Pass -1 here to choose that default;
• help: the help page associated with this list box. See UI.Help.

The Run command actually displays the list box and lets the user choose from it. It sets the UI.Result variable to the identifier (id) of the item chosen by the user, or to EMPTY if she canceled.

Example: this is a simplified version of the "Set Primary Enemy" command:

   Local i, UI.Result
   With Listbox("Primary Enemy", Enemy$, 260, 12, 10026) Do
     AddItem 0, "0 - none"
     For i:=1 To 11 Do AddItem i, Player(i).Race.Short
     Run
     SetEnemy UI.Result
   EndWith

Note: scripts can not suspend while a With Listbox block is active.

Since: PCC 1.1.1, PCC2 1.99.25