README.txt

   1
   2
   3                    Native bindings for D.
   4
   5
   6
   7       BINDINGS
   8
   9 The D modules in this package give access to:
  10
  11  GLib, GModule, GObject, Gio, GdkPixbuf, Pango, PangoCairo, PangoFT,
  12  Gdk, Atk, Gtk+
  13  Json-glib
  14  Clutter, ClutterX11
  15  Cogl, CoglPango
  16  Mx
  17
  18 There are also some minimal stubs, which are missing most functionality,
  19 but allow the other modules to build:
  20
  21  Cairo, Fontconfig, Freetype, GL
  22
  23
  24
  25       FEATURES
  26
  27 - The C API is used directly. No class wrappers and no function wrappers.
  28 - OO interface, giving a native D look and feel.
  29   There are basically three parts:
  30   1) data type definitions - ie structs, aliases (types) and enums (constants)
  31   2) C prototypes; these, plus (1) above, let's you use the C API directly
  32   3) "methods", which are actually disguised GTK functions.
  33
  34 - The code generated when using these bindings is identical to the equivalent
  35   C version. Bit-for-bit, there is zero overhead.
  36
  37 - As much as possible of the API is exposed. This includes things that are
  38   marked as unintrospectable.  Not everything will be directly usable from D,
  39   but there are no artificial limitations. (There are a few things that could
  40   be exposed, but so far aren't - simply because I had no need for them yet)
  41
  42 - The C API, ie all the function signatures and data types, is also available.
  43   It is possible to use the raw C API directly, ignoring all the D extras.
  44
  45 - The applications are linked with the dynamic GTK libs directly.
  46   No dlopen() games at applications startup. If a program was successfully
  47   built, it won't fail or print scary messages at startup because some library
  48   is missing or the versions does not exatcly match. (static linking might
  49   even work, but is untested)
  50
  51
  52
  53       DOCS
  54
  55 The C API is exposed more or less directly, so using the original
  56 documentation works.
  57
  58 GTK+:    http://developer.gnome.org/
  59 Cogl:    http://docs.clutter-project.org/docs/cogl/unstable/
  60 Clutter: http://docs.clutter-project.org/docs/clutter/unstable/
  61 MX:      http://docs.clutter-project.org/docs/mx/unstable/
  62
  63 The generated gtk*/*.d modules have a lot of doc comments - they are not
  64 always 100% complete, but often good enough.
  65
  66
  67 The bundled examples should be enough to get you started:
  68
  69 example_gtk1.d -- Basic Hello World app, using just the std GTK API.
  70 example_gtk2.d -- Same as above, but using a few extra features specific
  71                   to these bindings (try: "diff -u example_gtk[12].d")
  72 example_gtk3.d -- A trivial GTK calculator application. Not to be trusted
  73                   to get the math right. :) Just a example showing how to
  74                   create custom GTK widgets and handling certain common
  75                   issues.
  76 example_clutter1.d -- Trivial example, ported from tutorial.
  77 example_clutter2.d -- As above, just with two actors.
  78 example_mx3.d  -- The GTK calculator example ported to MX.
  79
  80
  81
  82       FAQ
  83
  84 - How is this different from existing D bindings?
  85
  86 A struct like <gdk.Rectangle>, which containing just four ints is not
  87 wrapped in a D class with only one visible field - a pointer to the real
  88 struct. It's not a D class which needs to be allocated every time a new
  89 Rectangle is used, even if it comes embedded in another structure (eg. an
  90 Event) and does not need to be accessed using class methods that also add
  91 overhead by doing extra null pointer checks etc.
  92
  93 A <gdk.Rectangle> is just the raw GDK structure. It has "methods", but
  94 using them results in calls to the real <gdk_rectangle_*()> library
  95 functions with appropriate arguments. No classes, no allocations, no
  96 vtables, no overhead.
  97
  98 - GTK3?
  99
 100 Coming soon, now that GTK2 is mostly done.
 101
 102 - No PascalCasing/camelCasing?
 103
 104 The method names are not manipulated in any way - the name chosen by the
 105 libraries are used directly.
 106 When a symbol conflicts with a language reserved word a '_' suffix is
 107 used, eg "o.new()" can be accessed as "o.new_()".
 108
 109 - The string/(char*) casts?
 110
 111 Unfortunately D immutable strings don't mix well with non-D APIs,
 112 especially, like in this case, when practically all const annotations
 113 are lost in translation (the GIR files are already missing them).
 114 You have to make sure all strings passed to the C libraries are zero-
 115 terminated; D string literal can be cast to (char*) directly, anything
 116 else likely requires std.string.toStringz().
 117
 118
 119
 120       D GTK EXTRAS ADDED BY THESE BINDINGS:
 121
 122 - Constructors.
 123    'v = gtk.VBox(0, 0)' can be used instead of 'v = gtk.VBox.new_(0, 0)'.
 124    If there are several constructors and the compiler is unable to figure
 125    out which one to call based on the argument types, use the full name
 126    (eg. new_with_label).
 127    The 'new' keyword should NOT be used, ie 'v = new gtk.VBox(0, 0)' does
 128    not work (this is because that would require overriding both the struct
 129    allocation and initialization; the pseudo-constructors are implemented
 130    as opCall's).
 131 - Magic upcasts.
 132    A "container.add(Widget* w)" function can be called with any derived
 133    widget, using the "container.add(&mywidget.widget);" idiom. This <widget>
 134    can be embedded in the <mywidget> struct (like in the case of builtin GTK
 135    widgets), but does not need to - it can be a pointer to such an object,
 136    the pointed-to widget will then be automatically used instead.
 137
 138    For this to work any "derived" struct must contain a lower-cased symbol
 139    of the right type - this convention is used internally (it's mostly
 140    already present in GTK, and every other place is taken care of while
 141    generating the bindings).
 142    This symbol can be present anywhere in the object hierarchy, ie any of
 143    the parent objects can contain it.
 144    See the <Keypad> and <AppWin> widgets in "example_gtk3.d" for examples.
 145
 146 - signal_connect!(string signal_name)(T callback) templates.
 147    Convenience templates, wrapping <signal_connect_data()> and ensuring the
 148    callback's signature is correct.
 149    Note: some callback declarations in the GIR data are wrong; you'll have
 150    to add casts for these cases. The common ones *do* work; using the
 151    "generic" callback type would need a cast anyway.
 152    (adding the correct overloads with <mixin/*.d> should be possible)
 153
 154 - _dumpobj(object* o).
 155    Will print the contents of any structure/union <o> to stdout. For debugging.
 156    See the examples, where it's used to dump the Events in the callbacks.
 157
 158
 159
 160       BUGS AND LIMITATIONS:
 161
 162 - Variadic methods are not available - use the C API directly.
 163   (this is because D mangles the names of <extern "C"> functions declared
 164   inside a struct, so the "alias" solution can't be used; it's fixable by
 165   either handling varargs or aliasing the D name to the unmangled C one.)
 166
 167 - Some array function parameter types are wrong (missing a '*').
 168   eg. glib:g_key_file_set_locale_string_list(...char **list...)
 169   The issue is: the <parameter><array> c:type's are inconsistent; mostly
 170   they are complete, but sometimes they're missing the last '*'. Which
 171   wouldn't be a problem if this was always the case, but - as it is -
 172   figuring out when the type refers to the *element* seems impossible.
 173
 174 - Some methods are wrongly documented (in the GIR XML) as functions.
 175   Eg. GObject:g_object_*(). Use the C prototypes, the methods are mostly
 176   <introspectable="0"> anyway.
 177
 178
 179
 180       USING THE D MODULES:
 181
 182 - Working pregenerated D modules should be available in the "gtk2"
 183   branch of the git repo;
 184   http://repo.or.cz/w/girtod.git/tree/refs/heads/gtk2:/gtk2
 185   Using them is as simple as placing them in a gtk2 subdirectory of your
 186   project; to install them globally, move that directory somewhere where
 187   your D compiler is looking for imports.
 188
 189
 190
 191       GENERATING THE D MODULES:
 192
 193 - The makefile should be functional enough to rebuild the gtk2/*.d
 194   modules, with a few local tweaks. Which can then be moved and used in
 195   your application directly, as above. The "configure" machinery still
 196   needs to be done.
 197
 198 - See the ./buildem script for how to build the bindings.
 199
 200
 201
 202       TODO
 203
 204 - Android support. For Cogl.
 205 - Windows support, using eg http://www.gtk.org/download/win32.php
 206   Won't do this myself, but if anyone gets it working, please document
 207   how, and send me any required patches.
 208
 209
 210
 211       LICENSE
 212
 213 The generated D bindings almost entirely consist of machine translations
 214 of the data types, function signatures and constants provided by the GIR
 215 files (</usr/share/gir-*/*.gir>, see http://live.gnome.org/GObjectIntrospection/
 216 for more info on GObject introspection).
 217 All extra mixins (from <mixin/*.d>) and fixups (done by <girtod.d>) added by
 218 this package to the gtk*/*.d files do not add any additional restrictions.
 219
 220 Any API documentation comments present in the generated modules come from
 221 the introspection data; the D compiler will ignore them. They are provided
 222 only for quick reference, see the upstream projects for licensing details.
 223 The comments can be removed from the modules without any loss of functionality.
 224
 225
 226 The girtod.d converter license is:
 227
 228 //          Copyright Artur Skawina 2012.
 229 // Distributed under the Boost Software License, Version 1.0.
 230 //    (See accompanying file LICENSE_1_0.txt or copy at
 231 //          http://www.boost.org/LICENSE_1_0.txt)
 232