UI Lua Scripting How to

Lua UI binding.

fastbird-engine supports ui scripts from 2014-Oct version. It is recommended to read UI-How-to before you read this document.

Define a script for the UI.

To see how to define a script for a UI, see the listing 1.

<UI name="FleetUI" script="data/ui/FleetUI.lua">
<component name="FleetUIMain" type="Window" pos="130, 180" size="600, 540" TITLEBAR="Fleet Information" USE_WND_FRAME="true" NO_BACKGROUND="false" BACK_COLOR="0, 0, 0, 0.7">
	<Events>
		<OnVisible>FleetUI:OnVisible()</OnVisible>
	</Events>
	<component name="ShipImage" type="ImageBox" pos="0, 0" nsize="1.0, 0.4" BACK_COLOR="1, 1, 1, 1"/>
	<component name="" type="StaticText" pos="0,0" nsize="1.0, 0.05" TEXT="Click and Drag to rotate the rtt camera"/>
	.
	.
	.
	(ommitted)

Listing 1. Defining a script.

script attribute is used to define the script for the ui. Events tag also added to link user input events to Lua functions. In the above example, when the UI 'FleetUI' is going to visible, the function FleetUI:OnVisible() will be called.

Events

Currently the engine is supporting the following ui events.(UI/IEventHandler.h)

• OnVisible
• OnHide
• OnMouseIn
• OnMouseHover
• OnMouseOut
• OnMouseLClick
• OnMouseLDClick
• OnMouseRClick
• OnMouseDown
• OnMouseDrag
• OnEnter
• OnFileSelectorSelected
• OnFileSelectorOk
• OnFileSelectorCancel
• OnNumericUp
• OnNumericDown
• OnDropDownSelected

Lua C Functions

To support UI lua scripting, the following C functions are registered to lua global environment.

• LUA_SETCFUNCTION(mL, SetVisibleLuaUI);
  Control Visibility.
  Example) SetVisibleLuaUI("FleetUI", true)

• LUA_SETCFUNCTION(mL, GetVisibleLuaUI);
  Query UI visibility.

• LUA_SETCFUNCTION(mL, SetVisibleComponent);
  Control Visibility of individual components.
  Example)SetVisibleComponent("FleetUI", "ButtonOK", false);

• LUA_SETCFUNCTION(mL, LoadLuaUI);
  Load .ui file. This function need to be called before you can SetvisibleLuaUI().
  Example) LoadLuaUI("data/ui/FleetUI.ui");

• LUA_SETCFUNCTION(mL, ClearListBox);
  Clear the listbox.
  Example) ClearListBox("FleetUI", "CrewList");

• LUA_SETCFUNCTION(mL, SetStaticText);
  Set static text.
  Example) SetStaticText("FleetUI", "Title", "Fleet - Pegasus");

• LUA_SETCFUNCTION(mL, RemoveAllChildrenOf);
  Remove all components in the parent.
  Example) RemoveAllChildrenOf("FleetUI", "BottonWindow");

• LUA_SETCFUNCTION(mL, AddComponent);
  Add a component.
  Example) AddComponent("FleetUI", "ParentComponent", {type_="Button" TEXT="Close" npos="0.5, 1.0" size="150, 30" ALIGNH="center" ALIGNV="bottom"})

• LUA_SETCFUNCTION(mL, BlinkButton);
  Start or end blinking of progress bar resides in a Button.
  Example) BlinkButton("FleetUI", "Research1Btn", true);

• LUA_SETCFUNCTION(mL, UpdateButtonProgressBar);
  Set the completion rate of the progress bar resides in a Button.
  Example) UpdateButtonProgressBar("FleetUI", "Research1Btn", 0.5);

• LUA_SETCFUNCTION(mL, StartButtonProgressBar);
  Create progress bar and set visibility.
  Example) StartButtonProgressBar("FleetUI", "Research1Btn");

• LUA_SETCFUNCTION(mL, EndButtonProgressBar);
  Hide progress bar on a Button.
  Example) EndButtonProgressBar("FleetUI", "Research1Btn");

• LUA_SETCFUNCTION(mL, SetTextBoxText);
  Set a text to a TextBox component. You can use SetUIProperty function with "TEXT" property also.
  Example) SetTextBoxText("FleetUI", "DescriptionBox", "Description goes here.");

• LUA_SETCFUNCTION(mL, SetUIBackground);
  Set 'BACKGROUND_IMAGE_NOATLAS' property. Create background image.
  Example) SetUIBackground("FleetUI", "MainWnd", "data/texture/FleetUIBackground.dds");

• LUA_SETCFUNCTION(mL, SetUIProperty);
  Set property of a component. You can find supported property list in the UI/UIProperty.h file.
  Example) SetUIProperty("FleetUI", "MainWnd", "BACKGROUND_IMAGE_NOATLAS", "data/texture/FleetUIBackground.dds") -- this does the exactly same work with the previous example.

• LUA_SETCFUNCTION(mL, RemoveUIEventhandler);
  Unbind event handler.
  Example) RemoveUIEventhandler("FleetUI", "RepairBtn", "OnMouseLClick");

• LUA_SETCFUNCTION(mL, GetMousePos);
  Get mouse position.
  Example) x, y = GetMousePos();