Difference between revisions of "Handling Events from Lua"

From CEGUI Wiki - Crazy Eddie's GUI System (Open Source)
Jump to: navigation, search
 
(3 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 +
{{VersionBadge|0.3}} {{VersionBadge|0.4}}
 +
 
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.
 
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.
  
Line 11: Line 13:
 
The two approaches are very alike, as the Lua version uses a direct binding to the same C++ function.
 
The two approaches are very alike, as the Lua version uses a direct binding to the same C++ function.
  
 +
<source lang="cpp">
 
  CEGUI::System::executeScriptFile(const CEGUI::String& filename, const CEGUI::String& resourceGroup = "");
 
  CEGUI::System::executeScriptFile(const CEGUI::String& filename, const CEGUI::String& resourceGroup = "");
 +
</source>
  
 
Obviously this function takes two parameters, a filename and the resource group.
 
Obviously this function takes two parameters, a filename and the resource group.
Line 21: Line 25:
 
So. From C++ you would do something like this:
 
So. From C++ you would do something like this:
  
 +
<source lang="cpp">
 
  CEGUI::System::getSingleton().executeScriptFile("../datafiles/scripts/guiscript.lua");
 
  CEGUI::System::getSingleton().executeScriptFile("../datafiles/scripts/guiscript.lua");
 +
</source>
  
 
If anything goes wrong an exception is thrown.
 
If anything goes wrong an exception is thrown.
  
 
From Lua you could use this code:
 
From Lua you could use this code:
−
 
+
<source lang="lua">
 
  CEGUI.System:getSingleton():executeScriptFile("../datafiles/scripts/guiscript.lua")
 
  CEGUI.System:getSingleton():executeScriptFile("../datafiles/scripts/guiscript.lua")
 +
</source>
  
 
any global code in these script files will also be executed so be sure to manage each execution if necessary (with a counter fx).
 
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 ==
 
== Registering Events to Lua Functions ==
Line 45: Line 51:
 
Here's a little snippet to bind a PushButton Clicked event to a Lua function:
 
Here's a little snippet to bind a PushButton Clicked event to a Lua function:
  
 +
<source lang="cpp">
 
  CEGUI::PushButton* pb = (CEGUI::PushButton*)CEGUI::WindowManager::getSingleton().createWindow("TaharezLook/Button","lua_powered_button");
 
  CEGUI::PushButton* pb = (CEGUI::PushButton*)CEGUI::WindowManager::getSingleton().createWindow("TaharezLook/Button","lua_powered_button");
 
  pb->setSize(CEGUI::Size(0.1f,0.1f));
 
  pb->setSize(CEGUI::Size(0.1f,0.1f));
Line 50: Line 57:
 
  pb->subscribeScriptedEvent("Clicked","luabtn_clicked");
 
  pb->subscribeScriptedEvent("Clicked","luabtn_clicked");
 
  CEGUI::System::getSingleton().getGUISheet()->addChildWindow(pb);
 
  CEGUI::System::getSingleton().getGUISheet()->addChildWindow(pb);
 +
</source>
  
 
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.
 
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.
Line 55: Line 63:
 
Now let's take a look at that Lua event handler:
 
Now let's take a look at that Lua event handler:
  
 +
<source lang="lua">
 
  function luabtn_clicked(e)
 
  function luabtn_clicked(e)
−
{
 
 
   local we = CEGUI.toWindowEventArgs(e)
 
   local we = CEGUI.toWindowEventArgs(e)
 
   we.window:setText("handled from Lua");
 
   we.window:setText("handled from Lua");
−
  }
+
  end
 +
</source>
  
 
Here we make sure the button text is ''handled from Lua'' when the button is clicked.
 
Here we make sure the button text is ''handled from Lua'' when the button is clicked.
 
We use a utility function:
 
We use a utility function:
  
 +
<source lang="lua">
 
  CEGUI.toWindowEventArgs(e)
 
  CEGUI.toWindowEventArgs(e)
 +
</source>
  
 
it's obvious what it does, and converters for the other EventArgs class are also available.
 
it's obvious what it does, and converters for the other EventArgs class are also available.
−
 
  
 
== Registering Lua Event Handlers from XML Layouts ==
 
== Registering Lua Event Handlers from XML Layouts ==
Line 74: Line 84:
 
Take a look a this example:
 
Take a look a this example:
  
 +
<source lang="xml">
 
  <?xml version="1.0"?>
 
  <?xml version="1.0"?>
 
  <GUILayout>
 
  <GUILayout>
Line 84: Line 95:
 
  </Window>
 
  </Window>
 
  </GUILayout>
 
  </GUILayout>
 +
</source>
  
 
This simple layout create the same button as described above and even bind the scripted event handler to it.
 
This simple layout create the same button as described above and even bind the scripted event handler to it.
Line 90: Line 102:
 
now you know how to do stuff with your GUI without writing C++ code.
 
now you know how to do stuff with your GUI without writing C++ code.
  
−
--[[User:Lindquist|Lindquist]] 17:10, 6 May 2005 (BST)
+
--[[User:Lindquist]] 17:10, 6 May 2005 (BST)
 +
 
 +
[[Category:Tutorials]]

Latest revision as of 17:35, 4 March 2011

Written for CEGUI 0.3

Works with versions 0.3.x (obsolete)

Written for CEGUI 0.4

Works with versions 0.4.x (obsolete)

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 17:10, 6 May 2005 (BST)

Retrieved from "http://cegui.org.uk/wiki/index.php?title=Handling_Events_from_Lua&oldid=4278"