| Latest revision |
Your text |
| Line 1: |
Line 1: |
| | 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. | | 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. | + | UI elements are created by accessing the <code>UI</code> global. For example, mods can call UI.CreateButton(...) to create a button. |
| | | | |
| | 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. | | 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. |
| Line 53: |
Line 53: |
| | '''Button''': A button that players can click on to do something. | | '''Button''': A button that players can click on to do something. |
| | * '''Text''' ''string'': The text to display on the button. | | * '''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''' ''string'': The color of the button. Pass this as a string in #RRGGBB format. |
| − | {{Color2|BABABC}} {{Color2|6C73D1}} {{Color2|FF00ED}} {{Color2|FFC200}} {{Color2|00A0FF}} {{Color2|00B5FF}} {{Color2|F3FFAE}} {{Color2|43C731}} {{Color2|43C631}} {{Color2|1274A4}} {{Color2|1274A5}} {{Color2|B03B3B}} {{Color2|0021FF}} {{Color2|359029}} {{Color2|00E9FF}} {{Color2|00FF21}} {{Color2|FFF700}} {{Color2|AA3A3A}} {{Color2|43C732}} {{Color2|00D4FF}} {{Color2|B03C3C}} {{Color2|00F4FF}} {{Color2|00BFFF}} {{Color2|4EC4FF}} {{Color2|615DDF}} {{Color2|100C08}} {{Color2|0000FF}} {{Color2|4EFFFF}} {{Color2|59009D}} {{Color2|008000}} {{Color2|FF7D00}} {{Color2|FF0000}} {{Color2|606060}} {{Color2|00FF05}} {{Color2|FF697A}} {{Color2|94652E}} {{Color2|00FF8C}} {{Color2|FF4700}} {{Color2|009B9D}} {{Color2|23A0FF}} {{Color2|AC0059}} {{Color2|FF87FF}} {{Color2|FFFF00}} {{Color2|943E3E}} {{Color2|FEFF9B}} {{Color2|AD7E7E}} {{Color2|B70AFF}} {{Color2|FFAF56}} {{Color2|FF00B1}} {{Color2|8EBE57}} {{Color2|DAA520}} {{Color2|990024}} {{Color2|00FFFF}} {{Color2|8F9779}} {{Color2|880085}} {{Color2|00755E}} {{Color2|FFE5B4}} {{Color2|4169E1}} {{Color2|FF43A4}} {{Color2|8DB600}} {{Color2|40826D}} {{Color2|C04000}} {{Color2|FFDDF4}} {{Color2|CD7F32}} {{Color2|C19A6B}} {{Color2|C09999}} {{Color2|B0BF1A}} {{Color2|3B7A57}} {{Color2|4B5320}} {{Color2|664C28}} {{Color2|893F45}} {{Color2|D2691E}} {{Color2|36454F}} {{Color2|FF00FF}} {{Color2|76FF7A}}
| + | * '''TextColor''' ''string'': The color of the text on teh button. Pass this as a string in #RRGGBB format. |
| − | * '''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. | | * '''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.
| |
| | | | |
| | | | |
| Line 64: |
Line 62: |
| | * '''Text''' ''string'': The label displayed to the right of the check box. | | * '''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. | | * '''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.
| |
| | | | |
| | | | |
| Line 70: |
Line 67: |
| | * '''Text''' ''string'': The string that appears in the box, or that players typed. | | * '''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..." | | * '''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.
| |
| | | | |
| | | | |
| Line 81: |
Line 76: |
| | * '''BoxPreferredWidth''' ''number'': Allows setting the preferred width of just the box. See '''Common Properties''' above. | | * '''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. | | * '''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. If you want to cancel the intercept request, you can return WL.CancelClickIntercept from the callback which will make the client behave as if you never called intercept. Return nil, or leave off the return statement entirely, for normal operation.
| |
| − |
| |
| − |
| |
| − | '''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. If you want to cancel the intercept request, you can return WL.CancelClickIntercept from the callback which will make the client behave as if you never called intercept. Return nil, or leave off the return statement entirely, for normal operation.
| |
| − |
| |
| − | [[Category:Mod API Reference]]
| |