mirror of
https://gitlab.gnome.org/GNOME/gtk.git
synced 2024-11-14 04:31:09 +00:00
339 lines
9.4 KiB
Plaintext
339 lines
9.4 KiB
Plaintext
|
|
The overall syntax is:
|
|
|
|
(type-of-thing-being-defined name-used-to-refer-to-this-thing
|
|
(attribute-name attribute-value-depending-on-the-attribute)
|
|
(attribute-name attribute-value-depending-on-the-attribute)
|
|
(attribute-name attribute-value-depending-on-the-attribute))
|
|
|
|
Some definitions can have a c-declaration field that gives the C code
|
|
we parsed to arrive at the definition. The c-declaration is a quoted
|
|
string because it can contain parentheses and such.
|
|
|
|
Defined types and their attributes:
|
|
|
|
===
|
|
(module module-name
|
|
(submodule-of module-name)) ;; submodule is optional
|
|
|
|
Ex: (module Gtk)
|
|
Ex: (module Rgb
|
|
(submodule-of Gdk))
|
|
|
|
modules are later referred to with a list of module names, like
|
|
(Gdk Rgb) or (Gtk)
|
|
|
|
Object and boxed type definitions automatically create a submodule.
|
|
For example, GtkCList creates the module (module CList (submodule-of
|
|
(Gtk))) which is referred to as module (Gtk CList).
|
|
|
|
===
|
|
|
|
(type
|
|
(alias some-unique-identifier)
|
|
(in-module module-name) ;; optional, gchar* is not in a module
|
|
(gtk-type-id gtk-type-system-id) ;; optional, absent if this is not
|
|
;; in the type system
|
|
(is-parametric boolean) ;; optional default to #f
|
|
(in-c-name name-of-symbol-in-C)
|
|
(out-c-name name-of-symbol-in-C)
|
|
(inout-c-name name-of-symbol-in-C))
|
|
|
|
Ex: (type
|
|
(alias string)
|
|
(gtk-type-id GTK_TYPE_STRING)
|
|
(in-c-name "const gchar*")
|
|
(out-c-name "gchar**") ;; actually I'm not sure how strings work out/inout
|
|
(inout-c-name "gchar*"))
|
|
|
|
(type
|
|
(alias list)
|
|
(gtk-type-id GTK_TYPE_POINTER)
|
|
(is-parametric #t)
|
|
(in-c-name "GList*")
|
|
(out-c-name "GList**")
|
|
(inout-c-name "GList**"))
|
|
|
|
|
|
;; This one would be implied by the (object) def for GtkWidget I
|
|
;; think - (type) is only required for types that are not implied
|
|
;; by other definitions, such as int/boolean/etc.
|
|
|
|
(type
|
|
(alias GtkWidget)
|
|
(in-module (Gtk))
|
|
(gtk-type-id GTK_TYPE_WIDGET)
|
|
(in-c-name "GtkWidget*")
|
|
(inout-c-name "GtkWidget*")
|
|
(out-c-name "GtkWidget**"))
|
|
|
|
"Type" bindings are automatically assumed for objects, boxed types,
|
|
etc. as defined below.
|
|
|
|
The alias field is used to refer to the type later on.
|
|
|
|
Whenever a type alias can be used, it is also possible to use the
|
|
keyword "native", which implies that the type in question is too
|
|
C-specific to represent. Then a c-declaration will typically be
|
|
available for use.
|
|
|
|
C types containing [] or () are function pointers or arrays. For
|
|
arrays that don't specify a size, we just treat them as pointers. For
|
|
function pointers, we need special (type) syntax/attributes of some
|
|
kind, but since there basically aren't any of these right now in the
|
|
libs we care about we can just ignore them. For arrays that specify a
|
|
size ditto, you would handle them by adding an (array-size) attribute
|
|
or something or using the "native" keyword and skipping the (type)
|
|
stuff.
|
|
|
|
===
|
|
(object object-name
|
|
(in-module module-name-list)
|
|
(parent object-name optional-module-name-if-different)
|
|
(abstract boolean-is-abstract-class) ;; omit for default of #f
|
|
(c-name name-of-the-object-in-C)
|
|
(field (type-and-name type-alias-of-struct-field name-of-struct-field)
|
|
(access read-or-write-or-readwrite)))
|
|
|
|
|
|
Ex: (object Widget
|
|
(in-module (Gtk))
|
|
(parent Object) ;; could say (parent Object (Gtk))
|
|
(abstract #t)
|
|
(c-name GtkWidget)
|
|
(field (type-and-name GdkWindow* window) (access read)))
|
|
|
|
An "object" declaration automatically implies the type definition:
|
|
|
|
(type
|
|
(alias concat-module-elements-and-object-name)
|
|
(in-c-name pointer-to-c-name)
|
|
(out-c-name pointer-to-pointer-to-c-name)
|
|
(inout-c-name pointer-to-c-name))
|
|
|
|
Ex:
|
|
(type (alias GtkWidget)
|
|
(in-c-name GtkWidget*)
|
|
(out-c-name GtkWidget**)
|
|
(inout-c-name GtkWidget*))
|
|
|
|
It also implies a module that is the name broken into parts:
|
|
(module CTree
|
|
(submodule-of Gtk))
|
|
|
|
===
|
|
|
|
(function function-name
|
|
(in-module module-name-list) ;; "static methods" go in their
|
|
;; object's module
|
|
(is-constructor-of object-type-alias) ;; optional, marks a constructor
|
|
(c-name function-name)
|
|
(return-type return-value-type) ;; defaults to void
|
|
(caller-owns-return boolean-value) ;; defaults to #f
|
|
(can-return-null boolean-value) ;; defaults to #t
|
|
(parameter in-or-out-or-inout
|
|
(type-and-name parameter-type-alias parameter-name)
|
|
(type-parameter name-of-contained-type) ;; optional, requires parametric type
|
|
(c-declaration "c-type-and-name")) ;; c-declaration only required
|
|
;; if the type alias is "native"
|
|
(varargs #t) ;; has varargs at the end
|
|
)
|
|
|
|
Ex:
|
|
(function init
|
|
(in-module (Gdk Rgb)
|
|
(c-name gdk_rgb_init)))
|
|
|
|
Ex:
|
|
(function new
|
|
(in-module (Gdk Rgb Cmap))
|
|
(is-constructor-of GdkRgbCmap)
|
|
(c-name gdk_rgb_cmap_new)
|
|
(return-type GdkRgbCmap)
|
|
(caller-owns-return #t) ;; perhaps this could be implied by is-constructor-of
|
|
(parameter in (type-and-name array-of-guint32 colors))
|
|
(parameter in (type-and-name gint n_colors)))
|
|
|
|
Ex:
|
|
(function config_set_set_handler
|
|
(in-module (Gnome))
|
|
(c-name gnome_config_set_set_handler)
|
|
(parameter in (type-and-name native func)
|
|
(c-declaration "void (*func)(void*)"))
|
|
(parameter in (type-and-name gpointer data)))
|
|
|
|
===
|
|
(method method-name
|
|
(of-object object-name module-name)
|
|
;; retval/arg attributes as for (function), but with first parameter
|
|
;; omitted for non-constructors
|
|
)
|
|
|
|
Ex:
|
|
(method set_text
|
|
(of-object Label (Gtk))
|
|
(parameter (type-and-name const-gchar* str)))
|
|
|
|
===
|
|
(object-argument arg-name
|
|
(of-object object-we-are-an-argument-of optional-objects-module)
|
|
(type-id argument-type) ;; GTK_TYPE_OBJECT etc.
|
|
;; flags all default to #f
|
|
(readable bool-value)
|
|
(writeable bool-value)
|
|
(construct-only bool-value))
|
|
|
|
Ex:
|
|
(object-argument label
|
|
(of-object Label (Gtk))
|
|
(type GTK_TYPE_STRING)
|
|
(readable #t)
|
|
(writeable #t))
|
|
|
|
===
|
|
(signal signal-name
|
|
(run-action bool-value)
|
|
(run-first bool-value)
|
|
(run-last bool-value)
|
|
(of-object object-we-are-a-signal-of optional-objects-module)
|
|
;; return value and parameters as for a function, omitting the object
|
|
;; and user data parameters
|
|
|
|
;; what other properties matter for a signal?
|
|
)
|
|
|
|
Ex:
|
|
(signal select_row
|
|
(of-object CList (Gtk))
|
|
(run-first #t)
|
|
;; return type defaults to void
|
|
(parameter in (type-and-name gint row))
|
|
(parameter in (type-and-name gint column))
|
|
(parameter in (type-and-name GdkEvent* event)))
|
|
|
|
===
|
|
(enum enum-name
|
|
(in-module modname)
|
|
(c-name name-in-c)
|
|
(value (nick value-name-noprefixes-hyphen-lowercase) (c-name value-c-name)))
|
|
|
|
Ex:
|
|
|
|
(enum DirectionType
|
|
(in-module Gtk)
|
|
(c-name GtkDirectionType)
|
|
(value (nick tab-forward) (c-name GTK_DIR_TAB_FORWARD))
|
|
(value (nick tab-backward) (c-name GTK_DIR_TAB_BACKWARD))
|
|
(value (nick up) (c-name GTK_DIR_UP))
|
|
(value (nick down) (c-name GTK_DIR_DOWN))
|
|
(value (nick left) (c-name GTK_DIR_LEFT))
|
|
(value (nick right) (c-name GTK_DIR_RIGHT)))
|
|
|
|
(enum Pos
|
|
(in-module (Gtk CTree))
|
|
(c-name GtkCTreePos)
|
|
(value (nick before) (c-name GTK_CTREE_POS_BEFORE))
|
|
(value (nick as-child) (c-name GTK_CTREE_POS_AS_CHILD))
|
|
(value (nick after) (c-name GTK_CTREE_POS_AFTER)))
|
|
|
|
===
|
|
(flags) is just like enum, but some bindings may wrap enums and flags differently.
|
|
|
|
===
|
|
|
|
(boxed boxed-name
|
|
(in-module modname)
|
|
(c-name c-name)
|
|
(ref-func func-to-increase-refcount)
|
|
(copy-func func-to-copy)
|
|
(release-func func-to-destroy-or-decrement-refcount)
|
|
(field (type-and-name type-alias-of-struct-field name-of-struct-field) (access access-rule)))
|
|
|
|
It is never OK to use memcpy() to copy a boxed type, or use
|
|
malloc()/free() to alloc/free one.
|
|
|
|
Ex:
|
|
|
|
(boxed Pixmap
|
|
(in-module (Gdk))
|
|
(c-name GdkPixmap)
|
|
(ref-func pixmap_ref)
|
|
(release-func pixmap_unref))
|
|
|
|
An "object" declaration automatically implies the type definition:
|
|
|
|
(type
|
|
(alias concat-module-elements-and-boxed-name)
|
|
(in-c-name pointer-to-c-name)
|
|
(out-c-name pointer-to-pointer-to-c-name)
|
|
(inout-c-name pointer-to-c-name))
|
|
|
|
Ex:
|
|
(type (alias GdkPixmap)
|
|
(in-c-name GdkPixmap*)
|
|
(out-c-name GdkPixmap**)
|
|
(inout-c-name GdkPixmap*))
|
|
|
|
|
|
===
|
|
|
|
(struct struct-name
|
|
(in-module modname)
|
|
(c-name c-name)
|
|
(field (type-and-name type-alias-of-struct-field name-of-struct-field) (access access-rule)))
|
|
|
|
Unlike a boxed type, a struct type can be copied with memcpy() and
|
|
allocated on the stack or with g_malloc().
|
|
|
|
Ex:
|
|
(struct Rectangle
|
|
(in-module (Gdk))
|
|
(c-name GdkRectangle)
|
|
(field (type-and-name gint16 x) (access readwrite))
|
|
(field (type-and-name gint16 y) (access readwrite))
|
|
(field (type-and-name guint16 width) (access readwrite))
|
|
(field (type-and-name guint16 height) (access readwrite)))
|
|
|
|
Implies GdkRectangle type alias:
|
|
|
|
(type (alias GdkRectangle)
|
|
(in-c-name GdkRectangle*)
|
|
(out-c-name GdkRectangle*) ;; note - not the same as boxed types
|
|
(inout-c-name GdkRectangle*))
|
|
|
|
===
|
|
|
|
(user-function name
|
|
(in-module module)
|
|
(c-name c-typedef-name)
|
|
;; return-type and parameters as for (function)
|
|
)
|
|
|
|
Ex:
|
|
|
|
(user-function PrintFunc
|
|
(in-module (Gtk))
|
|
(parameter in (type-and-name gpointer func_data))
|
|
(parameter in (type-and-name gchar* str)))
|
|
|
|
===
|
|
|
|
(typedef new-name
|
|
(in-module module)
|
|
(c-name c-full-name)
|
|
(orig-type alias-of-orig-type))
|
|
|
|
Ex:
|
|
|
|
(typedef Type
|
|
(in-module (Gtk))
|
|
(c-name GtkType)
|
|
(orig-type guint))
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|