Editing Mod API Reference:UI

Mods can put UI (user interface) onto the screen when called from one of the Client '''Present''' [[Mod Hooks|hooks]].  This page describes how to create and update UI elements.

UI elements are created by accessing the <code>UI</code> global.  For example, mods can call UI.CreateButton(...) to create a button.  Any UI element listed below can be created in a similar manner.

Behind the scenes, these objects are implemented using Unity's UI and layout system. Being familiar with Unity's UI system will make understanding how to build UI easier, but it's not a requirement.

== Parents ==
All UI constructors take a single <code>parent</code> argument.  This allows you to construct hierarchies.  For example, mods can create a vertical stack of three buttons like this:

  local vert = UI.CreateVerticalLayoutGroup(rootParent);
  local btn1 = UI.CreateButton(vert);
  local btn2 = UI.CreateButton(vert);
  local btn3 = UI.CreateButton(vert);

When a mod is called to present UI, it will be passed a root UI element (rootParent).  Your mod should pass the rootParent to a UI element that will be the root of all other elements you need.  This element is most often a VerticalLayoutGroup, as shown in the example above.  

You can never make more than one element a child of the rootParent.  If you need more than one, simply make your own container to house them.
  
== Properties ==

UI elements have properties that can be read or set.  For example, Buttons have a Text property that allows you to set the text that appears on the button.

To read or write a UI element's property, you must use getter/setter functions named GetX() and SetX().  For example, to set the text of a button you can write <code>btn1.SetText('Click me!')</code> and can retrieve it using <code>btn1.GetText()</code>.

All getter and setter functions return the UI element, which means you can chain them together to easily set lots of properties. For example:

  UI.CreateButton(vert)
    .SetText('Click me!')
    .SetColor('#00FF00')
    .SetOnClick(someFunction);

== Common Properties ==

All UI elements have the following properties:
* '''PreferredWidth''' ''number'': How wide the element prefers to be.  It may not be this wide if there is not enough space, and it may be wider if FlexibleWidth is greater than 0.  Defaults to -1, which is a special value meaning the object will meansure its own size based on its contents.
* '''PreferredHeight''' ''number'': How tall the element prefers to be.  It may not be this tall if there is not enough space, and it may be taller if FlexibleHeight is greater than 0.  Defaults to -1, which is a special value meaning the object will meansure its own size based on its contents.
* '''FlexibleWidth''' ''number'': A number from 0 to 1 indicating how much of the remaining space this element wishes to take up.  Defaults to 0, which means the element will be no wider than PreferredWidth.  Set it to 1 to indicate the object should grow to encompass all remaining horizontal space it can.
* '''FlexibleHeight''' ''number'': A number from 0 to 1 indicating how much of the remaining space this element wishes to take up.  Defaults to 0, which means the element will be no taller than PreferredHeight.  Set it to 1 to indicate the object should grow to encompass all remaining vertical space it can.

== UI Elements ==

'''Empty''': A simple UI element that displays nothing.  This can be used as a container or to create space.

'''VerticalLayoutGroup''': A container that stacks its children vertically.

'''HorizontalLayoutGroup''': A container that stacks its children horizontally.

'''Label''': A way to display text on the screen.
* '''Text''' ''string'': The text to display.
* '''Color''' ''string'': The color of the text.  Pass this as a string in #RRGGBB format.


'''Button''': A button that players can click on to do something.
* '''Text''' ''string'': The text to display on the button.
* '''Color''' ''string'': The color of the button.  Pass this as a string in #RRGGBB format.  Only the following colors are supported for buttons:
{{Color|BABABC}} {{Color|6C73D1}} {{Color|FF00ED}} {{Color|FFC200}} {{Color|00A0FF}} {{Color|00B5FF}} {{Color|F3FFAE}} {{Color|43C731}} {{Color|43C631}} {{Color|1274A4}} {{Color|1274A5}} {{Color|B03B3B}} {{Color|0021FF}} {{Color|359029}} {{Color|00E9FF}} {{Color|00FF21}} {{Color|FFF700}} {{Color|AA3A3A}} {{Color|43C732}} {{Color|00D4FF}} {{Color|B03C3C}} {{Color|00F4FF}} {{Color|00BFFF}} {{Color|4EC4FF}} {{Color|615DDF}} {{Color|100C08}} {{Color|0000FF}} {{Color|4EFFFF}} {{Color|59009D}} {{Color|008000}} {{Color|FF7D00}} {{Color|FF0000}} {{Color|606060}} {{Color|00FF05}} {{Color|FF697A}} {{Color|94652E}} {{Color|00FF8C}} {{Color|FF4700}} {{Color|009B9D}} {{Color|23A0FF}} {{Color|AC0059}} {{Color|FF87FF}} {{Color|FFFF00}} {{Color|943E3E}} {{Color|FEFF9B}} {{Color|AD7E7E}} {{Color|B70AFF}} {{Color|FFAF56}} {{Color|FF00B1}} {{Color|8EBE57}} {{Color|DAA520}} {{Color|990024}} {{Color|00FFFF}} {{Color|8F9779}} {{Color|880085}} {{Color|00755E}} {{Color|FFE5B4}} {{Color|4169E1}} {{Color|FF43A4}} {{Color|8DB600}} {{Color|40826D}} {{Color|C04000}} {{Color|FFDDF4}} {{Color|CD7F32}} {{Color|C19A6B}} {{Color|C09999}} {{Color|B0BF1A}} {{Color|3B7A57}} {{Color|4B5320}} {{Color|664C28}} {{Color|893F45}} {{Color|D2691E}} {{Color|36454F}} {{Color|FF00FF}} {{Color|76FF7A}}
* '''TextColor''' ''string'': The color of the text on the button.  Pass this as a string in #RRGGBB format.
* '''OnClick''' ''function'': Pass the name of a lua function to be called whenever the player clicks the button.
* '''Interactable''' ''bool'': If false, the control will be grayed out and unusable by the player.


'''CheckBox''': A toggleable check box that players can check and uncheck.
* '''IsChecked''' ''bool'': Whether the check box is checked or unchecked.
* '''Text''' ''string'': The label displayed to the right of the check box.
* '''OnValueChanged''' ''function'': Pass the name of a lua function to be called whenever the IsChecked property changes, either by your code or by the player clicking the check box.
* '''Interactable''' ''bool'': If false, the control will be grayed out and unusable by the player.


'''TextInputField''': A box where players can type a string.
* '''Text''' ''string'': The string that appears in the box, or that players typed.
* '''PlaceholderText''' ''string'': The text that appears in the box grayed out when it's empty.  For example, "Enter name here..."
* '''CharacterLimit''' ''integer'': The maximum number of characters that players can type into this text field.
* '''Interactable''' ''bool'': If false, the control will be grayed out and unusable by the player.


'''NumberInputField''': Allows players to input a number. Presents an input box and a slider that are linked, so players can either use the box to type a number or slide the slider.  This makes it friendly for mobile users who don't have a hardware keyboard, while also allowing any number to be entered if someone wants to exceed the range allowable by the slider.
* '''Value''' ''number'': The value to show in the box+slider, or the value entered by the player.
* '''WholeNumbers''' ''bool'': If true, only integers will be selectable by the player.  If false, partial numbers will be selectable. Defaults to true.
* '''SliderMinValue''' ''number'': The minimum value selectable by the slider.  Numbers below this can still be entered by typing them into the box, so ensure to always validate the number you retrieve.
* '''SliderMaxValue''' ''number'': The maxium value selectable by the slider.  Numbers above this can still be entered by typing them into the box, so ensure to always validate the number you retrieve.
* '''BoxPreferredWidth''' ''number'': Allows setting the preferred width of just the box.  See '''Common Properties''' above.
* '''SliderPreferredWidth''' ''number'': Allows setting the preferred width of just the slider.  See '''Common Properties''' above.
* '''Interactable''' ''bool'': If false, the control will be grayed out and unusable by the player.

== Helper Functions ==

'''UI.Destroy''': Destroys (removes) any UI that the mod previously created.  Simply pass a UI element created by one of the UI.CreateXXX functions to UI.Destroy and it will disappear forever.


'''UI.IsDestroyed''': Tests if any UI element has been destroyed.  Also returns true if passed nil.


'''UI.Alert''': Pops up a dialog with a message and an Okay button to close the message.  Call this as simply <code>UI.Alert(msg)</code>. Only one mod can use this at a time.


'''UI.PromptFromList''': Pops up a dialog with a series of buttons to choose from.    This takes two arguments:  
* '''Message''' ''string'': Text to appear at the top of the dialog.
* '''Options''' ''array'': A list of options, each of which will show up as a button.  Each entry in this array should be a table with two fields, '''text''' and '''selected'''.  '''text''' populates the text that will appear on that button, and '''selected''' is a zero-argument function that gets called if the player selects that option.


'''UI.InterceptNextTerritoryClick''': Added in [[Mod_API_Reference:IsVersionOrHigher|5.17.0]].  After calling this function, the next time the player clicks a territory on the map, your mod will be notified of the click. After calling this, you should also instruct the player to click a territory, and it's also a good idea to let them know they can move dialogs out of the way to see the map.   
* '''Callback''' ''function'': Pass a function that will be called on the next click.  This function will be passed a [[Mod_API_Reference:TerritoryDetails|TerritoryDetails]] object, which can be used to get the Territory ID or the name of the territory that was clicked.  This function can also be called with nil if the intercept request is cancelled, which can happen if another mod calls UI.InterceptNextTerritoryClick before a territory is clicked.


'''UI.InterceptNextBonusLinkClick''': Added in [[Mod_API_Reference:IsVersionOrHigher|5.17.0]].  After calling this function, the next time the player clicks a bonus link on the map, your mod will be notified of the click. After calling this, you should also instruct the player to click a bonus link, and it's also a good idea to let them know they can move dialogs out of the way to see the map.   
* '''Callback''' ''function'': Pass a function that will be called on the next click.  This function will be passed a [[Mod_API_Reference:BonusDetails|BonusDetails]] object, which can be used to get the bonus ID or the name of the bonus that was clicked.  This function can also be called with nil if the intercept request is cancelled, which can happen if another mod calls UI.InterceptNextBonusLinkClick before a bonus link is clicked.

[[Category:Mod API Reference]]