UserData class reference
[Base module]

Declaration  

#include <QtLua/UserData>

namespace QtLua {
class UserData;
};

This class is a member of the QtLua namespace.

Description  

This class is the base class for C++ objects which may be exposed to lua script as a lua userdata value.

All lua meta operations on userdata values are mapped to virtual functions in this class which may be reimplemented in derived classes. Lua errors can be raised from these functions by throwing a String type exception. See Error handling and exceptions.

Objects derived from this class are subject to lua garbage collection and must be handled by the Ref smart pointer class in C++ code.

UserData base class declaration example:

// code from examples/cpp/userdata/ref.cc:26

class MyObject : public QtLua::UserData
{
public:
QTLUA_REFTYPE(MyObject);

MyObject(int a)
: a_(a) {}

private:
int a_;
};

UserData objects allocation examples:

// code from examples/cpp/userdata/ref.cc:48

QtLua::UserData::ptr ud = QTLUA_REFNEW(QtLua::UserData, );
MyObject::ptr my = QTLUA_REFNEW(MyObject, 42);

Members  

Inherited members  

Types  

Functions  

Protected functions  

Static functions  

Members detail  

virtual ~UserData()  

No documentation available

virtual void completion_patch(String &path, String &entry, int &offset)  

This member access is protected.

This function may be reimplemented to further modify completion result on console line when completed to a UserData value. This is usefull to append a dot or a pair of brackets access operator to the userdata value name for instance.

Parameters list:

  • path: Completion result tables path to userdata value.
  • entry: Completion result userdata name. May append to this string directly.
  • offset: Cursor offset. May be decreased to place cursor between inserted brackets for instance.

typedef Ref<const UserData, UserData> const_ptr  

Shortcut for Ref smart pointer class to UserData type provided for convenience

virtual String get_type_name() const  

This function returns an object type name. The default implementation returns the C++ object type name. This is used for error messages and pretty printing.

The return value is Pretty print object type.

virtual String get_value_str() const  

This function returns an string value describing object value or content. The default implementation returns an hexadecimal object pointer. This is used for mainly for pretty printing.

virtual ValueBase::List meta_call(State *ls, const ValueBase::List &args)  

This function is called when a function invokation operation is performed on a userdata object. The default implementation throws an error message. The UserData::support function must be reimplemented along with this function to report ValueBase::OpCall as supported.

Parameters list:

  • args: List of passed arguments.

The return value is List of returned values.

static void meta_call_check_args(const ValueBase::List &args, int min_count, int max_count, ...)  

This helper function can be used to check arguments types passed to the UserData::meta_call functions. This function throw an error message if checking fails.

More advanced arguments checking and conversion features are available in the Function base class which may be more appropriate when a userdata object is to be used as a function.

Parameters list:

  • args: list of passed arguments.
  • min_count: Minimum expected arguments count.
  • max_count: Maximum expected arguments count or 0 if no limit.
  • ...: List of ValueBase::ValueType matching expected arguments type. At least max(min_count, abs(max_count)) types must be passed. ValueBase::TNone may be used as wildcard. A negative value can be used for max_count to indicate a unlimited number of lua arguments with a type list longer than min_count. Last specified type is expected for all arguments above max(min_count, -max_count).

virtual bool meta_contains(State *ls, const Value &key)  

This function returns true if either the ValueBase::OpIndex operation or the ValueBase::OpNewindex operation is supported and an entry is associated to the given key.

The default implementation returns !meta_index(ls, key).is_nil() or false if UserData::meta_index throws.

virtual Value meta_index(State *ls, const Value &key)  

This function is called when a table read access operation is attempted on a userdata object. The default implementation throws an error message. The UserData::support function must be reimplemented along with this function to report ValueBase::OpIndex as supported.

Parameters list:

  • key: Value used as table index.

The return value is Table access result value.

virtual void meta_newindex(State *ls, const Value &key, const Value &value)  

This function is called when a table write access operation is attempted on a userdata object. The default implementation throws an error message. The UserData::support function must be reimplemented along with this function to report ValueBase::OpNewindex as supported.

Parameters list:

  • key: Value used as table index.
  • value: Value to put in table.

virtual Value meta_operation(State *ls, ValueBase::Operation op, const Value &a, const Value &b)  

This function is called when a lua operator is used with a UserData object. The default implementation throws an error message. The UserData::support function must be reimplemented along with this function.

Parameters list:

  • op: Specify invoked lua operator (see ValueBase::Operation).
  • a: First value involved in operation.
  • b: Second value involved in operation for binary operators.

The return value is Operation result value.

virtual Ref<Iterator> new_iterator(State *ls)  

This function may return an Iterator object used to iterate over an userdata object. The default implementation throws an error message. The UserData::support function must be reimplemented along with this function to report ValueBase::OpIterate as supported.

The return value is an Iterator based iterator object.

virtual bool operator<(const UserData &ud)  

Userdata compare less than, default implementation compares the this pointers

virtual bool operator==(const UserData &ud)  

Userdata compare for equality, default implementation compares the this pointers

typedef Ref<UserData, UserData> ptr  

Shortcut for Ref smart pointer class to UserData type provided for convenience

virtual bool support(ValueBase::Operation c) const  

Check given operation support.

See also ValueBase::support function.

static template <typename X> String type_name()  

Get a bare C++ typename from type

Value yield(State *ls) const  

This member access is protected.

When this function is invoked from the UserData::meta_call function, QtLua will request lua to yield when the UserData::meta_call function returns.

The current lua thread value is returned. The Value::call family of functions can be used on a lua thread value to resume the coroutine from C++ code. The nil value is returned if not currently running inside a coroutine.

When the State::lua_version function returns a value less than 501, this function is not able to return the current thread value if it has not been created using the Value::new_thread function. If the current thread has been created by any other mean (like call to the coroutine.create lua 5.0 function) a boolean true value is returned instead of the thread value.

Valid XHTML 1.0 StrictGenerated by diaxen on Sat Mar 30 15:29:55 2013 using MkDoc