Pileus Git - ~andy/gtk/blob - docs/defsformat.txt

   1
   2 The overall syntax is:
   3
   4      (type-of-thing-being-defined  name-used-to-refer-to-this-thing
   5        (attribute-name  attribute-value-depending-on-the-attribute)
   6        (attribute-name  attribute-value-depending-on-the-attribute)
   7        (attribute-name  attribute-value-depending-on-the-attribute))
   8
   9 Some definitions can have a c-declaration field that gives the C code
  10 we parsed to arrive at the definition. The c-declaration is a quoted
  11 string because it can contain parentheses and such.
  12
  13 Defined types and their attributes:
  14
  15 ===
  16 (module module-name
  17   (submodule-of module-name)) ;; submodule is optional
  18
  19 Ex: (module Gtk)
  20 Ex: (module Rgb
  21       (submodule-of Gdk))
  22
  23 modules are later referred to with a list of module names, like
  24 (Gdk Rgb) or (Gtk)
  25
  26 Object and boxed type definitions automatically create a submodule.
  27 For example, GtkCList creates the module (module CList (submodule-of
  28 (Gtk))) which is referred to as module (Gtk CList).
  29
  30 ===
  31
  32 (type
  33  (alias some-unique-identifier)
  34  (in-module module-name)   ;; optional, gchar* is not in a module
  35  (gtk-type-id gtk-type-system-id) ;; optional, absent if this is not
  36                                   ;; in the type system
  37  (is-parametric boolean)          ;; optional default to #f
  38  (in-c-name name-of-symbol-in-C)
  39  (out-c-name name-of-symbol-in-C)
  40  (inout-c-name name-of-symbol-in-C))
  41
  42 Ex: (type
  43      (alias string)
  44      (gtk-type-id GTK_TYPE_STRING)
  45      (in-c-name "const gchar*")
  46      (out-c-name "gchar**")      ;; actually I'm not sure how strings work out/inout
  47      (inout-c-name "gchar*"))
  48
  49  (type
  50      (alias list)
  51      (gtk-type-id GTK_TYPE_POINTER)
  52      (is-parametric #t)
  53      (in-c-name "GList*")
  54      (out-c-name "GList**")
  55      (inout-c-name "GList**"))
  56
  57
  58  ;; This one would be implied by the (object) def for GtkWidget I
  59  ;; think - (type) is only required for types that are not implied
  60  ;; by other definitions, such as int/boolean/etc.
  61
  62     (type
  63      (alias GtkWidget)
  64      (in-module (Gtk))
  65      (gtk-type-id GTK_TYPE_WIDGET)
  66      (in-c-name "GtkWidget*")
  67      (inout-c-name "GtkWidget*")
  68      (out-c-name "GtkWidget**"))
  69
  70 "Type" bindings are automatically assumed for objects, boxed types,
  71 etc. as defined below.
  72
  73 The alias field is used to refer to the type later on.
  74
  75 Whenever a type alias can be used, it is also possible to use the
  76 keyword "native", which implies that the type in question is too
  77 C-specific to represent. Then a c-declaration will typically be
  78 available for use.
  79
  80 C types containing [] or () are function pointers or arrays. For
  81 arrays that don't specify a size, we just treat them as pointers. For
  82 function pointers, we need special (type) syntax/attributes of some
  83 kind, but since there basically aren't any of these right now in the
  84 libs we care about we can just ignore them. For arrays that specify a
  85 size ditto, you would handle them by adding an (array-size) attribute
  86 or something or using the "native" keyword and skipping the (type)
  87 stuff.
  88
  89 ===
  90 (object object-name
  91    (in-module module-name-list)
  92    (parent object-name optional-module-name-if-different)
  93    (abstract boolean-is-abstract-class) ;; omit for default of #f
  94    (c-name name-of-the-object-in-C)
  95    (field (type-and-name type-alias-of-struct-field name-of-struct-field)
  96           (access read-or-write-or-readwrite)))
  97
  98
  99 Ex: (object Widget
 100       (in-module (Gtk))
 101       (parent Object)      ;; could say (parent Object (Gtk))
 102       (abstract #t)
 103       (c-name GtkWidget)
 104       (field (type-and-name GdkWindow* window) (access read)))
 105
 106 An "object" declaration automatically implies the type definition:
 107
 108 (type
 109   (alias concat-module-elements-and-object-name)
 110   (in-c-name pointer-to-c-name)
 111   (out-c-name pointer-to-pointer-to-c-name)
 112   (inout-c-name pointer-to-c-name))
 113
 114 Ex:
 115  (type (alias GtkWidget)
 116        (in-c-name GtkWidget*)
 117        (out-c-name GtkWidget**)
 118        (inout-c-name GtkWidget*))
 119
 120 It also implies a module that is the name broken into parts:
 121  (module CTree
 122    (submodule-of Gtk))
 123
 124 ===
 125
 126 (function function-name
 127   (in-module module-name-list) ;; "static methods" go in their
 128                                ;;  object's module
 129   (is-constructor-of object-type-alias) ;; optional, marks a constructor
 130   (c-name function-name)
 131   (return-type return-value-type) ;; defaults to void
 132   (caller-owns-return boolean-value) ;; defaults to #f
 133   (can-return-null boolean-value) ;; defaults to #t
 134   (parameter in-or-out-or-inout
 135       (type-and-name parameter-type-alias parameter-name)
 136       (type-parameter name-of-contained-type) ;; optional, requires parametric type
 137       (c-declaration "c-type-and-name")) ;; c-declaration only required
 138                                          ;; if the type alias is "native"
 139   (varargs #t) ;; has varargs at the end
 140 )
 141
 142 Ex:
 143   (function init
 144     (in-module (Gdk Rgb)
 145     (c-name gdk_rgb_init)))
 146
 147 Ex:
 148   (function new
 149     (in-module (Gdk Rgb Cmap))
 150     (is-constructor-of GdkRgbCmap)
 151     (c-name gdk_rgb_cmap_new)
 152     (return-type GdkRgbCmap)
 153     (caller-owns-return #t)   ;; perhaps this could be implied by is-constructor-of
 154     (parameter in (type-and-name array-of-guint32 colors))
 155     (parameter in (type-and-name gint n_colors)))
 156
 157 Ex:
 158   (function config_set_set_handler
 159    (in-module (Gnome))
 160    (c-name gnome_config_set_set_handler)
 161    (parameter in (type-and-name native func)
 162                  (c-declaration "void (*func)(void*)"))
 163    (parameter in (type-and-name gpointer data)))
 164
 165 ===
 166 (method method-name
 167   (of-object object-name module-name)
 168   ;; retval/arg attributes as for (function), but with first parameter
 169   ;; omitted for non-constructors
 170    )
 171
 172 Ex:
 173   (method set_text
 174      (of-object Label (Gtk))
 175      (parameter (type-and-name const-gchar* str)))
 176
 177 ===
 178 (object-argument arg-name
 179    (of-object object-we-are-an-argument-of optional-objects-module)
 180    (type-id argument-type)       ;; GTK_TYPE_OBJECT etc.
 181    ;; flags all default to #f
 182    (readable bool-value)
 183    (writeable bool-value)
 184    (construct-only bool-value))
 185
 186 Ex:
 187   (object-argument label
 188      (of-object Label (Gtk))
 189      (type GTK_TYPE_STRING)
 190      (readable #t)
 191      (writeable #t))
 192
 193 ===
 194 (signal signal-name
 195   (run-action bool-value)
 196   (run-first bool-value)
 197   (run-last bool-value)
 198   (of-object object-we-are-a-signal-of optional-objects-module)
 199   ;; return value and parameters as for a function, omitting the object
 200   ;; and user data parameters
 201
 202   ;; what other properties matter for a signal?
 203 )
 204
 205 Ex:
 206   (signal select_row
 207      (of-object CList (Gtk))
 208      (run-first #t)
 209      ;; return type defaults to void
 210      (parameter in (type-and-name gint row))
 211      (parameter in (type-and-name gint column))
 212      (parameter in (type-and-name GdkEvent* event)))
 213
 214 ===
 215 (enum enum-name
 216   (in-module modname)
 217   (c-name name-in-c)
 218   (value (nick value-name-noprefixes-hyphen-lowercase) (c-name value-c-name)))
 219
 220 Ex:
 221
 222   (enum DirectionType
 223     (in-module Gtk)
 224     (c-name GtkDirectionType)
 225     (value (nick tab-forward) (c-name GTK_DIR_TAB_FORWARD))
 226     (value (nick tab-backward) (c-name GTK_DIR_TAB_BACKWARD))
 227     (value (nick up) (c-name GTK_DIR_UP))
 228     (value (nick down) (c-name GTK_DIR_DOWN))
 229     (value (nick left) (c-name GTK_DIR_LEFT))
 230     (value (nick right) (c-name GTK_DIR_RIGHT)))
 231
 232   (enum Pos
 233     (in-module (Gtk CTree))
 234     (c-name GtkCTreePos)
 235     (value (nick before) (c-name GTK_CTREE_POS_BEFORE))
 236     (value (nick as-child) (c-name GTK_CTREE_POS_AS_CHILD))
 237     (value (nick after) (c-name GTK_CTREE_POS_AFTER)))
 238
 239 ===
 240 (flags) is just like enum, but some bindings may wrap enums and flags differently.
 241
 242 ===
 243
 244 (boxed boxed-name
 245   (in-module modname)
 246   (c-name c-name)
 247   (ref-func func-to-increase-refcount)
 248   (copy-func func-to-copy)
 249   (release-func func-to-destroy-or-decrement-refcount)
 250   (field (type-and-name type-alias-of-struct-field name-of-struct-field) (access access-rule)))
 251
 252 It is never OK to use memcpy() to copy a boxed type, or use
 253 malloc()/free() to alloc/free one.
 254
 255 Ex:
 256
 257  (boxed Pixmap
 258    (in-module (Gdk))
 259    (c-name GdkPixmap)
 260    (ref-func pixmap_ref)
 261    (release-func pixmap_unref))
 262
 263 An "object" declaration automatically implies the type definition:
 264
 265 (type
 266   (alias concat-module-elements-and-boxed-name)
 267   (in-c-name pointer-to-c-name)
 268   (out-c-name pointer-to-pointer-to-c-name)
 269   (inout-c-name pointer-to-c-name))
 270
 271 Ex:
 272  (type (alias GdkPixmap)
 273        (in-c-name GdkPixmap*)
 274        (out-c-name GdkPixmap**)
 275        (inout-c-name GdkPixmap*))
 276
 277
 278 ===
 279
 280 (struct struct-name
 281   (in-module modname)
 282   (c-name c-name)
 283   (field (type-and-name type-alias-of-struct-field name-of-struct-field) (access access-rule)))
 284
 285 Unlike a boxed type, a struct type can be copied with memcpy() and
 286 allocated on the stack or with g_malloc().
 287
 288 Ex:
 289  (struct Rectangle
 290    (in-module (Gdk))
 291    (c-name GdkRectangle)
 292    (field (type-and-name gint16 x) (access readwrite))
 293    (field (type-and-name gint16 y) (access readwrite))
 294    (field (type-and-name guint16 width) (access readwrite))
 295    (field (type-and-name guint16 height) (access readwrite)))
 296
 297 Implies GdkRectangle type alias:
 298
 299  (type (alias GdkRectangle)
 300        (in-c-name GdkRectangle*)
 301        (out-c-name GdkRectangle*)    ;; note - not the same as boxed types
 302        (inout-c-name GdkRectangle*))
 303
 304 ===
 305
 306 (user-function name
 307   (in-module module)
 308   (c-name c-typedef-name)
 309   ;; return-type and parameters as for (function)
 310 )
 311
 312 Ex:
 313
 314  (user-function PrintFunc
 315     (in-module (Gtk))
 316     (parameter in (type-and-name gpointer func_data))
 317     (parameter in (type-and-name gchar* str)))
 318
 319 ===
 320
 321 (typedef new-name
 322   (in-module module)
 323   (c-name c-full-name)
 324   (orig-type alias-of-orig-type))
 325
 326 Ex:
 327
 328  (typedef Type
 329    (in-module (Gtk))
 330    (c-name GtkType)
 331    (orig-type guint))
 332
 333
 334
 335
 336
 337
 338