Handling Events from Lua

2005-06-26T01:19:39Z

Sarev0k: /* Registering Events to Lua Functions */ Fixing lua function example

Moving the handling of GUI events outside of your project code, and into Lua scripts can add a great deal of flexibilty to your interface. Simple GUI related stuff can be easily prototyped, and modified during testing.

Event handlers in Lua are just regular Lua functions that take one parameter. An CEGUI::EventArgs struct.
The functions you register as event handlers must already be registered with the system, so unless you load them all from your init-script, you will need to load some script files before doing any Lua handled events.

Here we go...

== Loading the script files ==
There are two ways of loading your script files. You can use the C++ interface or you can do it from Lua in your init-script.
The two approaches are very alike, as the Lua version uses a direct binding to the same C++ function.

CEGUI::System::executeScriptFile(const CEGUI::String& filename, const CEGUI::String& resourceGroup = "");

Obviously this function takes two parameters, a filename and the resource group.
I think most people ignore the last parameter pretty much.

Calling this function with the Lua scripting module correctly attached to CEGUI, will execute the specified Lua script file.
This means that functions etc. declared within these files will be accessible to your program, except of course if they are declared ''local''.

So. From C++ you would do something like this:

CEGUI::System::getSingleton().executeScriptFile("../datafiles/scripts/guiscript.lua");

If anything goes wrong an exception is thrown.

From Lua you could use this code:

CEGUI.System:getSingleton():executeScriptFile("../datafiles/scripts/guiscript.lua")

any global code in these script files will also be executed so be sure to manage each execution if necessary (with a counter fx).

== Registering Events to Lua Functions ==
Now that we have our scripts loaded and all, we are ready to bind some events to our scripted handlers.

The function to use when binding scripted events is a little different from the regular C++ one.

Event::Connection subscribeScriptedEvent(const String& name, const String& subscriber_name);

''name'' is the name of the event you want to subscribe. As usual. ''subscriber_name'' is a string holding the name of the Lua function to bind to the event.

After this call the Lua function specified will be registered as the event handler. And works exactly like the C++ version (except being Lua of course)

Here's a little snippet to bind a PushButton Clicked event to a Lua function:

CEGUI::PushButton* pb = (CEGUI::PushButton*)CEGUI::WindowManager::getSingleton().createWindow("TaharezLook/Button","lua_powered_button");
pb->setSize(CEGUI::Size(0.1f,0.1f));
pb->setPosition(CEGUI::Point(0.1f,0.1f));
pb->subscribeScriptedEvent("Clicked","luabtn_clicked");
CEGUI::System::getSingleton().getGUISheet()->addChildWindow(pb);

This code would create a simple TaharezLook button, subscribe the Lua function ''luabtn_clicked'' to its ''Clicked'' event, and finally add it to the current GUI sheet.

Now let's take a look at that Lua event handler:

function luabtn_clicked(e)
local we = CEGUI.toWindowEventArgs(e)
we.window:setText("handled from Lua");
end

Here we make sure the button text is ''handled from Lua'' when the button is clicked.
We use a utility function:

CEGUI.toWindowEventArgs(e)

it's obvious what it does, and converters for the other EventArgs class are also available.

== Registering Lua Event Handlers from XML Layouts ==
It's very easy to bind scripted event handlers to the windows in your XML layouts.

Take a look a this example:

<?xml version="1.0"?>
<GUILayout>
<Window Type="TaharezLook/Button" Name="lua_powered_button">
<Property Name="Width" Value="0.1" />
<Property Name="Height" Value="0.1" />
<Property Name="XPosition" Value="0.1" />
<Property Name="YPosition" Value="0.1" />
<Event Name="Clicked" Function="luabtn_clicked" />
</Window>
</GUILayout>

This simple layout create the same button as described above and even bind the scripted event handler to it.

now you know how to do stuff with your GUI without writing C++ code.

--[[User:Lindquist|Lindquist]] 17:10, 6 May 2005 (BST)

Writing CEGUI scripts

2005-06-26T01:08:32Z

Sarev0k: /* Load a layout */ Changed loadLayout() to loadWindowLayout()

All code on this page is Lua script using the CEGUILua bindings available on CVS HEAD.
The code snippets might not be specifically useful, but they should show off some of the posibilities with CEGUI and Lua used together. And give an idea of how to write these scripts.

Off we go :)

--[[User:Lindquist|Lindquist]] 20:56, 9 Jun 2005 (BST)

== Change logging level ==
local logger = CEGUI.Logger:getSingleton() -- get the logger
local lvl = logger:getLoggingLevel() -- get logging level

if lvl < CEGUI.Insane then -- if logging level is less than insane
logger:setLoggingLevel(lvl+1) -- then increase it
end
Bumps up the logging level a notch unless we're already at Insane.

== Load a scheme ==
CEGUI.SchemeManager:getSingleton():loadScheme("../datafiles/schemes/TaharezLook.scheme")
Loads the TaharezLook scheme.

== Simple Interface ==
-- create the GUI sheet
local sheet = CEGUI.WindowManager:getSingleton():createWindow("DefaultGUISheet","root");
CEGUI.System:getSingleton():setGUISheet(sheet) -- and attach it to the system

-- create a FrameWindow
local fw = CEGUI.WindowManager:getSingleton():createWindow("TaharezLook/FrameWindow","framewnd");
-- add it to the sheet
sheet:addChildWindow(fw)

-- set its size and position
local sz = CEGUI.Size:new_local(0.5,0.5)
local pos = CEGUI.Point:new_local(0.2,0.1)
fw:setSize(sz)
fw:setPosition(pos)
-- disable user sizing
fw:setProperty("SizingEnabled","False")

-- make the close button work
fw:subscribeEvent("CloseClicked","fwCloseClicked")

-- the CloseClicked event handler
function fwCloseClicked(eventArgs)
local we = CEGUI.toWindowEventArgs(eventArgs)
CEGUI.WindowManager:getSingleton():destroyWindow(we.window) -- destroy the frame window
end
Creates a GUISheet and attaches it to the System. Then creates a FrameWindow, sets its size and position. Disables the sizing feature and subscribes a scripted event handler to destroy the window when the close button is clicked.

== Load a layout ==
local w = CEGUI.WindowManager:getSingleton():loadWindowLayout("../datafiles/layouts/test.layout")
CEGUI.System:getSingleton():getGUISheet():addChildWindow(w)
Loads a XML layout and adds the returned window to the active GUISheet.

CEGUI Wiki - Crazy Eddie's GUI System (Open Source) - User contributions [en]

Handling Events from Lua

Writing CEGUI scripts