Crazy Eddie's GUI System  0.8.7
CEGUI::LuaScriptModule Class Reference

Interface for the LuaScriptModule class. More...

+ Inheritance diagram for CEGUI::LuaScriptModule:
+ Collaboration diagram for CEGUI::LuaScriptModule:

Public Member Functions

void executeScriptFile (const String &filename, const String &resourceGroup)
 Execute a script file. More...
 
void executeScriptFile (const String &filename, const String &resourceGroup, const String &error_handler)
 Execute a script file. More...
 
void executeScriptFile (const String &filename, const String &resourceGroup, const int error_handler)
 Execute a script file. More...
 
int executeScriptGlobal (const String &function_name)
 Execute a scripted global function. The function should not take any parameters and should return an integer. More...
 
int executeScriptGlobal (const String &function_name, const String &error_handler)
 Execute a scripted global function. The function should not take any parameters and should return an integer. More...
 
int executeScriptGlobal (const String &function_name, const int error_handler)
 Execute a scripted global function. The function should not take any parameters and should return an integer. More...
 
bool executeScriptedEventHandler (const String &handler_name, const EventArgs &e)
 Execute a scripted global 'event handler' function by looking it up by name. More...
 
bool executeScriptedEventHandler (const String &handler_name, const EventArgs &e, const String &error_handler)
 Execute a scripted global 'event handler' function by looking it up by name. More...
 
bool executeScriptedEventHandler (const String &handler_name, const EventArgs &e, const int error_handler)
 Execute a scripted global 'event handler' function by looking it up by name. More...
 
void executeString (const String &str)
 Execute script code contained in the given CEGUI::String object. More...
 
void executeString (const String &str, const String &error_handler)
 Execute script code contained in the given CEGUI::String object. More...
 
void executeString (const String &str, const int error_handler)
 Execute script code contained in the given CEGUI::String object. More...
 
Event::Connection subscribeEvent (EventSet *target, const String &name, const String &subscriber_name)
 Subscribes the named Event to a scripted funtion. More...
 
Event::Connection subscribeEvent (EventSet *target, const String &name, const String &subscriber_name, const String &error_handler)
 Subscribes the named Event to a scripted funtion. More...
 
Event::Connection subscribeEvent (EventSet *target, const String &name, const String &subscriber_name, const int error_handler)
 Subscribes the named Event to a scripted funtion. More...
 
Event::Connection subscribeEvent (EventSet *target, const String &name, Event::Group group, const String &subscriber_name)
 Subscribes the specified group of the named Event to a scripted funtion. More...
 
Event::Connection subscribeEvent (EventSet *target, const String &name, Event::Group group, const String &subscriber_name, const String &error_handler)
 Subscribes the specified group of the named Event to a scripted funtion. More...
 
Event::Connection subscribeEvent (EventSet *target, const String &name, Event::Group group, const String &subscriber_name, const int error_handler)
 Subscribes the specified group of the named Event to a scripted funtion. More...
 
void createBindings (void)
 Method called during system initialisation, prior to running any scripts via the ScriptModule, to enable the ScriptModule to perform any operations required to complete initialisation or binding of the script language to the gui system objects. More...
 
void destroyBindings (void)
 Method called during system destruction, after all scripts have been run via the ScriptModule, to enable the ScriptModule to perform any operations required to cleanup bindings of the script language to the gui system objects, as set-up in the earlier createBindings call. More...
 
lua_State * getLuaState (void) const
 Method used to get a pointer to the lua_State that the script module is attached to. More...
 
void setDefaultPCallErrorHandler (const String &error_handler_function)
 Set the name of the lua function that will be passed as the error handler in calls to lua_pcall, unless an alternative is specified in some other function call. More...
 
void setDefaultPCallErrorHandler (int function_reference)
 Set the function that will be passed as the error handler in calls to lua_pcall, unless an alternative is specified in some other function call. More...
 
const StringgetActivePCallErrorHandlerString () const
 Return the function name string of the active error handler function. More...
 
int getActivePCallErrorHandlerReference () const
 return the lua registry index of the active error handler function. More...
 
- Public Member Functions inherited from CEGUI::ScriptModule
 ScriptModule (void)
 Constructor for ScriptModule base class.
 
virtual ~ScriptModule (void)
 Destructor for ScriptModule base class.
 
const StringgetIdentifierString () const
 Return identification string for the ScriptModule. If the internal id string has not been set by the ScriptModule creator, a generic string of "Unknown scripting module" will be returned. More...
 

Static Public Member Functions

static LuaScriptModulecreate (lua_State *state=0)
 Creates a LuaScriptModule object. More...
 
static void destroy (LuaScriptModule &mod)
 Destroys the given LuaScriptModule object.
 
- Static Public Member Functions inherited from CEGUI::ScriptModule
static void setDefaultResourceGroup (const String &resourceGroup)
 Sets the default resource group to be used when loading script files. More...
 
static const StringgetDefaultResourceGroup ()
 Returns the default resource group used when loading script files. More...
 

Additional Inherited Members

- Protected Attributes inherited from CEGUI::ScriptModule
String d_identifierString
 String that holds some id information about the module.
 
- Static Protected Attributes inherited from CEGUI::ScriptModule
static String d_defaultResourceGroup
 holds the default resource group ID for loading script files.
 

Detailed Description

Interface for the LuaScriptModule class.

Member Function Documentation

static LuaScriptModule& CEGUI::LuaScriptModule::create ( lua_State *  state = 0)
static

Creates a LuaScriptModule object.

Parameters
statePointer to the lua_State that the script module should attach to, if this is 0 a lua_State will be created.
void CEGUI::LuaScriptModule::createBindings ( void  )
virtual

Method called during system initialisation, prior to running any scripts via the ScriptModule, to enable the ScriptModule to perform any operations required to complete initialisation or binding of the script language to the gui system objects.

Returns
Nothing.

Reimplemented from CEGUI::ScriptModule.

void CEGUI::LuaScriptModule::destroyBindings ( void  )
virtual

Method called during system destruction, after all scripts have been run via the ScriptModule, to enable the ScriptModule to perform any operations required to cleanup bindings of the script language to the gui system objects, as set-up in the earlier createBindings call.

Returns
Nothing.

Reimplemented from CEGUI::ScriptModule.

bool CEGUI::LuaScriptModule::executeScriptedEventHandler ( const String handler_name,
const EventArgs e 
)
virtual

Execute a scripted global 'event handler' function by looking it up by name.

Parameters
handler_nameString object holding the name of the scripted handler function. If this string contains dots '.' it will be parsed as tables containing a function field. For example: 'mytable.subtable.func'
eEventArgs based object that should be passed, by any appropriate means, to the scripted function.
Returns
  • true if the event was handled.
  • false if the event was not handled.

Implements CEGUI::ScriptModule.

bool CEGUI::LuaScriptModule::executeScriptedEventHandler ( const String handler_name,
const EventArgs e,
const String error_handler 
)

Execute a scripted global 'event handler' function by looking it up by name.

Parameters
handler_nameString object holding the name of the scripted handler function. If this string contains dots '.' it will be parsed as tables containing a function field. For example: 'mytable.subtable.func'
eEventArgs based object that should be passed, by any appropriate means, to the scripted function.
error_handlerString containing the name of the script fuction that will be called if an error occurs while executing the handler function. NB: This is the function passed as the error handler to lua_pcall.
Returns
  • true if the event was handled.
  • false if the event was not handled.
bool CEGUI::LuaScriptModule::executeScriptedEventHandler ( const String handler_name,
const EventArgs e,
const int  error_handler 
)

Execute a scripted global 'event handler' function by looking it up by name.

Parameters
handler_nameString object holding the name of the scripted handler function. If this string contains dots '.' it will be parsed as tables containing a function field. For example: 'mytable.subtable.func'
eEventArgs based object that should be passed, by any appropriate means, to the scripted function.
error_handlerinteger value describing a lua registry reference to the function that will be called if an error occurs while executing the handler function. NB: This is the function passed as the error handler to lua_pcall.
Returns
  • true if the event was handled.
  • false if the event was not handled.
void CEGUI::LuaScriptModule::executeScriptFile ( const String filename,
const String resourceGroup 
)
virtual

Execute a script file.

Parameters
filenameString object holding the filename of the script file that is to be executed.
resourceGroupResource group idendifier to be passed to the ResourceProvider when loading the script file.

Implements CEGUI::ScriptModule.

void CEGUI::LuaScriptModule::executeScriptFile ( const String filename,
const String resourceGroup,
const String error_handler 
)

Execute a script file.

Parameters
filenameString object holding the filename of the script file that is to be executed.
resourceGroupResource group idendifier to be passed to the ResourceProvider when loading the script file.
error_handlerString containing the name of the script fuction that will be called if an error occurs while executing the handler function. NB: This is the function passed as the error handler to lua_pcall.
void CEGUI::LuaScriptModule::executeScriptFile ( const String filename,
const String resourceGroup,
const int  error_handler 
)

Execute a script file.

Parameters
filenameString object holding the filename of the script file that is to be executed.
resourceGroupResource group idendifier to be passed to the ResourceProvider when loading the script file.
error_handlerinteger value describing a lua registry reference to the function that will be called if an error occurs while executing the handler function. NB: This is the function passed as the error handler to lua_pcall.
int CEGUI::LuaScriptModule::executeScriptGlobal ( const String function_name)
virtual

Execute a scripted global function. The function should not take any parameters and should return an integer.

Parameters
function_nameString object holding the name of the function, in the global script environment, that is to be executed.
Returns
The integer value returned from the script function.

Implements CEGUI::ScriptModule.

int CEGUI::LuaScriptModule::executeScriptGlobal ( const String function_name,
const String error_handler 
)

Execute a scripted global function. The function should not take any parameters and should return an integer.

Parameters
function_nameString object holding the name of the function, in the global script environment, that is to be executed.
error_handlerString containing the name of the script fuction that will be called if an error occurs while executing the handler function. NB: This is the function passed as the error handler to lua_pcall.
Returns
The integer value returned from the script function.
int CEGUI::LuaScriptModule::executeScriptGlobal ( const String function_name,
const int  error_handler 
)

Execute a scripted global function. The function should not take any parameters and should return an integer.

Parameters
function_nameString object holding the name of the function, in the global script environment, that is to be executed.
error_handlerinteger value describing a lua registry reference to the function that will be called if an error occurs while executing the handler function. NB: This is the function passed as the error handler to lua_pcall.
Returns
The integer value returned from the script function.
void CEGUI::LuaScriptModule::executeString ( const String str)
virtual

Execute script code contained in the given CEGUI::String object.

Parameters
strString object holding the valid script code that should be executed.
Returns
Nothing.

Implements CEGUI::ScriptModule.

void CEGUI::LuaScriptModule::executeString ( const String str,
const String error_handler 
)

Execute script code contained in the given CEGUI::String object.

Parameters
strString object holding the valid script code that should be executed.
error_handlerString containing the name of the script fuction that will be called if an error occurs while executing the handler function. NB: This is the function passed as the error handler to lua_pcall.
Returns
Nothing.
void CEGUI::LuaScriptModule::executeString ( const String str,
const int  error_handler 
)

Execute script code contained in the given CEGUI::String object.

Parameters
strString object holding the valid script code that should be executed.
error_handlerinteger value describing a lua registry reference to the function that will be called if an error occurs while executing the handler function. NB: This is the function passed as the error handler to lua_pcall.
Returns
Nothing.
int CEGUI::LuaScriptModule::getActivePCallErrorHandlerReference ( ) const

return the lua registry index of the active error handler function.

The 'active' error handler for the LuaScriptModule is either the default as specified by calling setDefaultPCallErrorHandler, or whatever might have been set up by a call to the internal initErrorHandlerFunc function.

This may return a value previously set by the user, or the value as
bound internally by the script module for an error handler specified by function name.
Note
This function is really intended for use internally by other parts of the lua scripting support. Although it could be useful elsewhere for advanced uses, so long as you're careful!
Warning
You should never call luaL_unref on the value returned by this function unless you created tge reference in the first place, and even then only after having called setDefaultPCallErrorHandler passing LUA_NOREF.
const String& CEGUI::LuaScriptModule::getActivePCallErrorHandlerString ( ) const

Return the function name string of the active error handler function.

The 'active' error handler for the LuaScriptModule is either the default as specified by calling setDefaultPCallErrorHandler, or whatever might have been set up by a call to the internal initErrorHandlerFunc function.

Note
This function is really intended for use internally by other parts of the lua scripting support. Although it could be useful elsewhere for advanced uses, so long as you're careful!
lua_State* CEGUI::LuaScriptModule::getLuaState ( void  ) const
inline

Method used to get a pointer to the lua_State that the script module is attached to.

Returns
A pointer to the lua_State that the script module is attached to.
void CEGUI::LuaScriptModule::setDefaultPCallErrorHandler ( const String error_handler_function)

Set the name of the lua function that will be passed as the error handler in calls to lua_pcall, unless an alternative is specified in some other function call.

Parameters
error_handler_functionName of the lua function to be called. This is looked up / bound on first usage.
void CEGUI::LuaScriptModule::setDefaultPCallErrorHandler ( int  function_reference)

Set the function that will be passed as the error handler in calls to lua_pcall, unless an alternative is specified in some other function call.

Parameters
function_referenceLua function registry index of the function to be called.
Event::Connection CEGUI::LuaScriptModule::subscribeEvent ( EventSet target,
const String name,
const String subscriber_name 
)
virtual

Subscribes the named Event to a scripted funtion.

Parameters
targetThe target EventSet for the subscription.
nameString object containing the name of the Event to subscribe to.
subscriber_nameString object containing the name of the script funtion that is to be subscribed to the Event.
Returns
Connection object that can be used to check the status of the Event connection and to disconnect (unsubscribe) from the Event.

Implements CEGUI::ScriptModule.

Event::Connection CEGUI::LuaScriptModule::subscribeEvent ( EventSet target,
const String name,
const String subscriber_name,
const String error_handler 
)

Subscribes the named Event to a scripted funtion.

Parameters
targetThe target EventSet for the subscription.
nameString object containing the name of the Event to subscribe to.
subscriber_nameString object containing the name of the script funtion that is to be subscribed to the Event.
error_handlerString containing the name of the script fuction that will be called if an error occurs while executing the handler function. NB: This is the function passed as the error handler to lua_pcall.
Returns
Connection object that can be used to check the status of the Event connection and to disconnect (unsubscribe) from the Event.
Event::Connection CEGUI::LuaScriptModule::subscribeEvent ( EventSet target,
const String name,
const String subscriber_name,
const int  error_handler 
)

Subscribes the named Event to a scripted funtion.

Parameters
targetThe target EventSet for the subscription.
nameString object containing the name of the Event to subscribe to.
subscriber_nameString object containing the name of the script funtion that is to be subscribed to the Event.
error_handlerinteger value describing a lua registry reference to the function that will be called if an error occurs while executing the handler function. NB: This is the function passed as the error handler to lua_pcall.
Returns
Connection object that can be used to check the status of the Event connection and to disconnect (unsubscribe) from the Event.
Event::Connection CEGUI::LuaScriptModule::subscribeEvent ( EventSet target,
const String name,
Event::Group  group,
const String subscriber_name 
)
virtual

Subscribes the specified group of the named Event to a scripted funtion.

Parameters
targetThe target EventSet for the subscription.
nameString object containing the name of the Event to subscribe to.
groupGroup which is to be subscribed to. Subscription groups are called in ascending order.
subscriber_nameString object containing the name of the script funtion that is to be subscribed to the Event.
Returns
Connection object that can be used to check the status of the Event connection and to disconnect (unsubscribe) from the Event.

Implements CEGUI::ScriptModule.

Event::Connection CEGUI::LuaScriptModule::subscribeEvent ( EventSet target,
const String name,
Event::Group  group,
const String subscriber_name,
const String error_handler 
)

Subscribes the specified group of the named Event to a scripted funtion.

Parameters
targetThe target EventSet for the subscription.
nameString object containing the name of the Event to subscribe to.
groupGroup which is to be subscribed to. Subscription groups are called in ascending order.
subscriber_nameString object containing the name of the script funtion that is to be subscribed to the Event.
error_handlerString containing the name of the script fuction that will be called if an error occurs while executing the handler function. NB: This is the function passed as the error handler to lua_pcall.
Returns
Connection object that can be used to check the status of the Event connection and to disconnect (unsubscribe) from the Event.
Event::Connection CEGUI::LuaScriptModule::subscribeEvent ( EventSet target,
const String name,
Event::Group  group,
const String subscriber_name,
const int  error_handler 
)

Subscribes the specified group of the named Event to a scripted funtion.

Parameters
targetThe target EventSet for the subscription.
nameString object containing the name of the Event to subscribe to.
groupGroup which is to be subscribed to. Subscription groups are called in ascending order.
subscriber_nameString object containing the name of the script funtion that is to be subscribed to the Event.
error_handlerinteger value describing a lua registry reference to the function that will be called if an error occurs while executing the handler function. NB: This is the function passed as the error handler to lua_pcall.
Returns
Connection object that can be used to check the status of the Event connection and to disconnect (unsubscribe) from the Event.