Second draft (was Re: defs files)
- From: Havoc Pennington <hp redhat com>
- To: gtk-devel-list redhat com
- Subject: Second draft (was Re: defs files)
- Date: 19 Jan 2000 19:16:06 -0500
George <jirka@5z.com> writes:
> why call function arguments "arguments" why not "parameters"
>
OK that helps too.
ChangeLog:
- argument becomes "object-argument" or "parameter"
- use the named-attributes thing for arguments and fields; this makes
the format extensible as long as language bindings ignore unknown
attribute names. i.e. avoid the positional stuff more pervasively
- varargs attribute for functions/methods/etc
- added "inoutness" to types; but I don't like this, I think
maybe we want instead must-free must-not-free must-initialize
and other such less-abstract stuff. "inoutness" assumes an
API that's more consistent than it is
- added by-value-ok attribute to boxed
- added "access" attribute to struct/object fields
===
(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)
===
(type
(alias some-unique-identifier)
(in-module module-name) ;; optional, gchar* is not in a module
(c-name name-of-symbol-in-C)
(inoutness in-or-out-or-inout)) ;; if not specified, can deduce from
;; the C type
Ex: (type
(alias broken-in-string)
(c-name gchar*)
(inoutness in))
(type
(alias GtkWidget**)
(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.
If the C type has spaces they are converted to hyphens:
(type
(alias const-gchar*
(c-name const-gchar*)))
So hyphens have to go back to spaces for binding generators that
output C code.
===
(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 declaration:
(type
(alias pointer-to-c-name)
(c-name pointer-to-c-name))
Ex: (type (alias GtkWidget*) (c-name GtkWidget*))
Of course many language binding generators can just ignore this
implicit declaration.
===
(function function-name
(in-module module-name-list)
(c-name function-name)
(return-type return-value-type) ;; defaults to void
(parameter (type-and-name parameter-type-alias parameter-name)) ;; as many of these as you want
(varargs #t) ;; has varargs at the end
)
Ex:
(function init
(in-module (Gdk Rgb)
(c-name gdk_rgb_init)))
Ex:
(function cmap_new
(in-module (Gdk Rgb))
(c-name gdk_rgb_cmap_new)
(return-type GdkRgbCmap*)
(parameter (type-and-name guint32* colors))
(parameter (type-and-name gint n_colors)))
===
(method method-name
(is-constructor boolean-is-a-constructor) ;; omit for default of #f
(of-object object-name module-name)
;; retval/arg attributes as for (function), but with first parameter omitted
)
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 argument-type) ;; not sure what to put for type
;; flags all default to #f
(readable bool-value)
(writeable bool-value)
(run-action bool-value)
(construct-only bool-value))
Ex:
(object-argument label
(of-object Label (Gtk))
(type gchar*) ;; ????
(readable #t)
(writeable #t))
===
(signal signal-name
(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))
;; return type defaults to void
(parameter (type-and-name gint row))
(parameter (type-and-name gint column))
(parameter (type-and-name GdkEvent* event)))
===
(enum enum-name
(of-object objname module) ;; in-module and of-object are mutually exclusive
(in-module modname)
(c-name name-in-c)
(value (name value-name-noprefixes-hyphen-lowercase) (c-name value-c-name)))
Ex:
(enum DirectionType
(in-module Gtk)
(c-name GtkDirectionType)
(value (name tab-forward) (c-name GTK_DIR_TAB_FORWARD))
(value (name tab-backward) (c-name GTK_DIR_TAB_BACKWARD))
(value (name up) (c-name GTK_DIR_UP))
(value (name down) (c-name GTK_DIR_DOWN))
(value (name left) (c-name GTK_DIR_LEFT))
(value (name right) (c-name GTK_DIR_RIGHT)))
(enum Pos
(of-object CTree (Gtk))
(value (name c-name) (c-name GtkCTreePos))
(value (name before) (c-name GTK_CTREE_POS_BEFORE))
(value (name as-child) (c-name GTK_CTREE_POS_AS_CHILD))
(value (name 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)
(by-value-ok boolean-can-just-memcpy)
(ref-func func-to-increase-refcount)
(unref-func func-to-decrease-refcount)
(copy-func func-to-copy)
(destroy-func func-to-destroy)
(field (type-and-name type-alias-of-struct-field name-of-struct-field)))
Ex:
(boxed Pixmap
(in-module (Gdk))
(c-name GdkPixmap)
(ref-func pixmap_ref)
(unref-func pixmap_unref))
This implies the type alias GdkPixmap* to the C type GdkPixmap*
(boxed Rectangle
(in-module (Gdk))
(c-name GdkRectangle)
(by-value-ok #t)
(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.
===
(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 (type-and-name gpointer func_data))
(parameter (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))
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]