Module src/gnome/types.c

vim:sw=4:sts=4 Library to use the Gtk2 object library from Lua 5.1 Copyright (C) 2007 Wolfgang Oertl Handle type conversion from Lua to and from C (or Gtk). Exported symbols: lg_empty_table ffi_type_lua2ffi ffi_type_ffi2lua ffi_type_lua2struct ffi_type_struct2lua ffi_type_map core_ffi_type_names

Functions

BITS_PER_INT (int) Given a pointer, a bit offset and a bit length, retrieve the value.
local _determine_flags (ar) Refcounting for GObject derived objects that are not Gtk objects is tricky.
local _guess_type_idx (L, p, ts) An object of type "ts" should be accessed; it might be a subclass of the given type.
local _lua2ffi_vararg_table (ar) A table is given as an argument for a vararg.
local _lua2ffi_vararg_table_strings (ar) A vararg is a table and should be converted to an array of string pointers.
local _ptr_ptr_helper (ar, type) A "struct**" is most likely an output parameter, but may be out/in.
local _push_untyped (L, p) A void* pointer will be pushed onto the stack as a userdata with a metatable that contains the function "cast".
local _store_int (L, p, conv_idx, index) Store an integer of a given ffi_type at *p.
local ffi2lua_char_ptr (ar) A char* only is an output value if it is the actual function return value.
local ffi2lua_char_ptr_ptr (ar) A char** argument was filled with a pointer to a newly allocated string.
local ffi2lua_enum_ptr_ptr (ar) Handle enum** plus int* as output parameters.
local ffi2lua_int_ptr (ar) A int* type parameter can be an output parameter.
local ffi2lua_struct_ptr (ar) Convert a structure pointer to a Lua value.
local ffi2lua_struct_ptr_ptr (ar) A Gtk function filled in a SomeStruct **p pointer.
local ffi2lua_void (ar) ------- FFI2LUA FUNCTIONS ----- These functions take a ffi value and push it onto the Lua stack.
get_bits_long (ar, dest) Retrieve an arbitrarily long memory block, which must be byte aligned and the length must be a multiple of 8 bits.
lg_empty_table (L, index) Remove all entries of the given table.
local lua2ffi_bool (ar) These functions retrieve a value from the Lua stack and store it into the provided target.
local lua2ffi_double_ptr (ar) Array of doubles - as input
local lua2ffi_enum (ar) ENUMs can be represented by simple numbers, or by a userdata that additionally contains the ENUM type, which can be used for type checking.
local lua2ffi_enum_ptr (ar) Array of ENUMs - as input
local lua2ffi_func_ptr (ar) A func* should be passed to a Gtk function.
local lua2ffi_int_ptr (ar) Pointer to an integer - can be input or output.
local lua2ffi_ptr (ar) Generic pointer - only NIL can be transported XXX This function should eventually be replaced by specialized functions for each pointer type, like "short*" etc.
local lua2ffi_struct_ptr (ar) Handle pointers to structures/unions/objects/GValues.
local lua2ffi_uchar (ar) An unsigned char can be given as number (ASCII code), a boolean (0/1) or as a string (first character is used).
local lua2ffi_vararg (ar) Handle a vararg argument.
local lua2struct_char_ptr (ar) Write to a char* field in a structure.
local lua2struct_func_ptr (ar) Set a function pointer, most likely in an Iface structure.
local lua2struct_long (ar) Write a number into a structure element
local set_bits (ptr, bitofs, bitlen, val) Write a numerical field within a structure.
local struct2lua_func_ptr (ar) Handle reads of function pointers: return a closure for this function.
local untyped_cast (p, type) A void* pointer was returned by a Gtk function; cast it to the desired type.


Functions

BITS_PER_INT (int)
Given a pointer, a bit offset and a bit length, retrieve the value. This is used for non 8 bit things, like single bits. The destination is a long. Tested on 32 and 64 bit architectures.

Parameters

  • int:
In file: src/gnome/types.c line 44
local _determine_flags (ar)
Refcounting for GObject derived objects that are not Gtk objects is tricky. These are returned by the creating function with a refcount of 1 but not with a floating reference. Therefore, g_object_ref_sink must not be called. On the other hand, when an existing GObject derived object is returned by a function, the refcount must be increased, because a new reference to it is held and the refcount will be decreased upon GC of the Lua proxy object. It seems that functions that match the pattern gtk_*_get_ return existing objects. This is just a guess, I haven't verified them all, and maybe there are others that also return existing objects but don't match this naming pattern. Currently 174 functions match this: grep -c '^Gtk.*gtk_.*_get_' funclist-gtk Note that computing the flags in this way is only relevant when the Lua proxy object doesn't exist yet, but that is determined later. OTOH lg_get_object doesn't know about the name of the function that returns the object, so...

Parameters

  • ar:
In file: src/gnome/types.c line 977
local _guess_type_idx (L, p, ts)
An object of type "ts" should be accessed; it might be a subclass of the given type. If the requested type is derived from GObject, the actual type can be determined from the object. In this case, set type_idx to 0, which lets lg_get_object figure out the actual type of the object.

Parameters

  • L:
  • p: Pointer to the object
  • ts: The type this object is supposed to have.

Return value:

If the object's supposed type is derived from GObject, and the actual type is known to lua-gtk, returns ts.type_idx=0, else it is returned unchanged. In file: src/gnome/types.c line 1033
local _lua2ffi_vararg_table (ar)
A table is given as an argument for a vararg. An optional "_type" field tells what type the items should be; default is strings. Problem: somtimes the resulting array must be ended with a NULL pointer; when you specify nil as the last item in a table it is simply discarded. Use gtk.NIL instead of nil in this situation.

Parameters

  • ar:
In file: src/gnome/types.c line 578
local _lua2ffi_vararg_table_strings (ar)
A vararg is a table and should be converted to an array of string pointers.

Parameters

  • ar:
In file: src/gnome/types.c line 527
local _ptr_ptr_helper (ar, type)
A "struct**" is most likely an output parameter, but may be out/in. Allocate memory for a pointer, and set it to the given value, which may be nil. When collecting results, the output value will be used.

Parameters

  • ar: Array with a description of the argument to convert
  • type: 0 for char**, 1 for struct**
In file: src/gnome/types.c line 449
local _push_untyped (L, p)
A void* pointer will be pushed onto the stack as a userdata with a metatable that contains the function "cast". This is similar to the void wrappers, but simpler and does just enough to be usable.

Parameters

  • L:
  • p:
In file: src/gnome/types.c line 1487
local _store_int (L, p, conv_idx, index)
Store an integer of a given ffi_type at *p. XXX might be an ENUM etc. XXX the error message in case of type mismatch has a wrong argument number.

Parameters

  • L: Lua State
  • p: Pointer to the destination; can be 4 or 8 bytes long
  • conv_idx: CONV_*INT_PTR to specify the type at *p
  • index: Where the number is on the Lua stack
In file: src/gnome/types.c line 689
local ffi2lua_char_ptr (ar)
A char* only is an output value if it is the actual function return value. The string returned from the library function is freed unless it is a "const char*".

Parameters

  • ar:
In file: src/gnome/types.c line 953
local ffi2lua_char_ptr_ptr (ar)
A char** argument was filled with a pointer to a newly allocated string. Copy that to the Lua stack, then free the original string.

Parameters

  • ar:
In file: src/gnome/types.c line 1329
local ffi2lua_enum_ptr_ptr (ar)
Handle enum** plus int* as output parameters. This currently occurs only in three API functions: gdk_query_visual_types gtk_icon_set_get_sizes pango_tab_array_get_tabs -- requires an override, not handled here. The table given to the function call is filled with the result.

Parameters

  • ar:
In file: src/gnome/types.c line 1179
local ffi2lua_int_ptr (ar)
A int* type parameter can be an output parameter. If so, push the returned value onto the stack. Note: the arg_flags for this parameter is set by lua2ffi_int_ptr if a single integer was passed.

Parameters

  • ar:
In file: src/gnome/types.c line 1255
local ffi2lua_struct_ptr (ar)
Convert a structure pointer to a Lua value.

Parameters

  • ar:
In file: src/gnome/types.c line 1113
local ffi2lua_struct_ptr_ptr (ar)
A Gtk function filled in a SomeStruct **p pointer. Assume that this is a regular object. XXX Some functions return an existing object, others create a new one, and even others allocate a memory block and return that. It seems that there's no way to automatically figure out the right way. Returns an existing object: GtkTreeModel** (gtk_tree_selection_get_selected) Returns a new object: Returns a newly allocate memory block that must be freed: GError**, GdkRectangle**, PangoAttrList** Returns an existing memory block that must not be freed:

Parameters

  • ar:
In file: src/gnome/types.c line 1295
local ffi2lua_void (ar)
------- FFI2LUA FUNCTIONS ----- These functions take a ffi value and push it onto the Lua stack. They are required to convert return values from library calls back to Lua values. Note that some "output arguments", like pointers to integers, are handled, too. All of these functions return the number of arguments used; usually one, but sometimes two.

Parameters

  • ar:
In file: src/gnome/types.c line 902
get_bits_long (ar, dest)
Retrieve an arbitrarily long memory block, which must be byte aligned and the length must be a multiple of 8 bits. Note that if "bitlen" is less than the variable "dest" points to, the additional bytes won't be initialized. Therefore, set them to zero before calling this function. If "bitlen" is not a multiple of 8, then get_bits_unaligned will be called, which assumes that "dest" is an unsigned long integer.

Parameters

  • ar:
  • dest:
In file: src/gnome/types.c line 71
lg_empty_table (L, index)
Remove all entries of the given table. Generally it would be easier to just create a new table, but for tables given as arguments it is required to write into them.

Parameters

  • L:
  • index:
In file: src/gnome/types.c line 1162
local lua2ffi_bool (ar)
These functions retrieve a value from the Lua stack and store it into the provided target. They are used to convert the arguments to C functions called from Lua, but also to convert the return values of callbacks.

Parameters

  • ar:
In file: src/gnome/types.c line 144
local lua2ffi_double_ptr (ar)
Array of doubles - as input

Parameters

  • ar:
In file: src/gnome/types.c line 780
local lua2ffi_enum (ar)
ENUMs can be represented by simple numbers, or by a userdata that additionally contains the ENUM type, which can be used for type checking.

Parameters

  • ar:
In file: src/gnome/types.c line 206
local lua2ffi_enum_ptr (ar)
Array of ENUMs - as input

Parameters

  • ar:
In file: src/gnome/types.c line 836
local lua2ffi_func_ptr (ar)
A func* should be passed to a Gtk function. Either a preallocated closure (obtained by gnome.closure) or a regular Lua function can be used. For callbacks, the func* argument is often followed by a void* argument which is passed to the callback. This is already handled properly by the void* wrapper, see voidptr.c.

Parameters

  • ar:
In file: src/gnome/types.c line 407
local lua2ffi_int_ptr (ar)
Pointer to an integer - can be input or output. This works for int, unsigned int, long int, unsigned long int. Input, e.g. for gdk_pango_layout_get_clip_region. Use as such when an array (of numbers) is given. Output in other cases. Initialize with whatever the user passed as parameter.

Parameters

  • ar:
In file: src/gnome/types.c line 726
local lua2ffi_ptr (ar)
Generic pointer - only NIL can be transported XXX This function should eventually be replaced by specialized functions for each pointer type, like "short*" etc. If required, various other Lua types could be converted: LUA_TUSERDATA, LUA_TLIGHTUSERDATA, LUA_TSTRING, or even LUA_TFUNCTION?

Parameters

  • ar:
In file: src/gnome/types.c line 274
local lua2ffi_struct_ptr (ar)
Handle pointers to structures/unions/objects/GValues.

Parameters

  • ar:
In file: src/gnome/types.c line 300
local lua2ffi_uchar (ar)
An unsigned char can be given as number (ASCII code), a boolean (0/1) or as a string (first character is used).

Parameters

  • ar:
In file: src/gnome/types.c line 174
local lua2ffi_vararg (ar)
Handle a vararg argument. This must be the last argument for the function, and collects all remaining given parameters (zero or more). This function must handle all Lua types and find an appropriate FFI type for each of them. The ci->argtypes must be set, too, for each argument.

Parameters

  • ar:
In file: src/gnome/types.c line 613
local lua2struct_char_ptr (ar)
Write to a char* field in a structure.

Parameters

  • ar:
In file: src/gnome/types.c line 1600
local lua2struct_func_ptr (ar)
Set a function pointer, most likely in an Iface structure. At the given index, a closure must be found (or NIL). Note that on-the-fly generation of closures doesn't make sense; it could be garbage collected anytime.

Parameters

  • ar:
In file: src/gnome/types.c line 1623
local lua2struct_long (ar)
Write a number into a structure element

Parameters

  • ar:
In file: src/gnome/types.c line 1571
local set_bits (ptr, bitofs, bitlen, val)
Write a numerical field within a structure. Note. Writing to fields spanning more than one "unsigned long int" is not supported - but this shouldn't happen anyway.

Parameters

  • ptr: Pointer to the start of the structure
  • bitofs: Offset of the field within the structure
  • bitlen: Length of the field
  • val: value to write into the field.
In file: src/gnome/types.c line 93
local struct2lua_func_ptr (ar)
Handle reads of function pointers: return a closure for this function.

Parameters

  • ar:
In file: src/gnome/types.c line 1528
local untyped_cast (p, type)
A void* pointer was returned by a Gtk function; cast it to the desired type.

Parameters

  • p: The void wrapper
  • type: A string with the desired type's name

Return values:

  1. The requested object.
In file: src/gnome/types.c line 1453

Valid XHTML 1.0!