GI Crystal is a binding generator used to generate Crystal bindings for GObject based libraries using GObject Introspection.
If you are looking for GTK4 bindings for Crystal, go to GTK4
I wrote this while studying GObject Introspection to contribute with crystal-gobject but at some point I decided to take a different approach on how to generate the bindings, so I started this.
Besides the binding generator this shard provides bindings for GLib, GObject and Gio libraries.
You are probably looking for the GTK4 shard, not this one, since this shard is only useful if you are creating a binding for a GObject based library.
-
Add the dependency to your
shard.yml:developer_dependencies: gtk: github: hugopl/gi-crystal
-
Run
shards install -
Run
./bin/gi-crystalto generate the bindings.
Bindings are specified in binding.yml files. When you run the generator it will scan all binding.yml
files under the project directory and generate the bindings at lib/gi-crystal/src/auto/.
The generator is compiled in a post-install task and can be found at bin/gi-crystal after you run shards install.
See https://github.com/hugopl/gtk4.cr for an example of how to use it.
If you want to use just GLib, GObject or Gio bindings do:
require "gi-crystal/glib" # Just GLib bindings
require "gi-crystal/gobject" # GLib and GObject bindings
require "gi-crystal/gio" # GLib, GObject and Gio bindingsCrystal is a garbage collected language, you create objects and have faith that the GC will free them at some point in time, while on the other hand GLib uses reference count, the clash of these two approaches of how to deal with memory management can't end up in something beautiful without corner cases, etc... but we try our best to reduce the mess.
The basic rules are:
- All objects (except enums, flags and unions) are created in the heap (including non GObject C Structs).
- Boxed structs (except GValue) are always allocated by GLib but owned by Crystal wrappers.
- If the struct is passed from C to Crystal with "transfer none", the struct is copied anyway to ensure that every Crystal object wrapper always points to valid memory. On "transfer full" no copy is needed.
- All Crystal GObject wrappers have just a pointer to the C object (always allocated by GLib) and always hold a reference during their lifetime.
If you don't know what means Transfer full, Transfer none and few other terms about GOBject introspection, is worth to
read the docs.
To help debug memory issues you can compile your code with -Ddebugmemory, this will print the object address and reference
counter to STDOUT when any wrapper object finalize method is called.
Despite of being written in a language that doesn't have object oriented features, GObject is an object oriented library by design so many things maps easily to OO languages. However each language has its way of doing things and some adaptation is always needed to have a better blending and let the bindings feels more native to the language.
Class names do not have the module prefix, i.e. GFile from GLib module is mapped to GLib::File, GtkLabel is be mapped to Gtk::Label,
where GLib and Gtk are modules.
GObject interfaces are mapped to Crystal modules + a dummy class that only implements this module, used when there's some function returning the interface.
If the object was created by Crystal code you can cast it like you do with any Crystal object instance, using .as? and .as.
If the object was created by C code, e.g. Gtk::Builder where you get everything as a GObject::Object instance, Crystal type system doesn't knows the exact type of the object in GObject type system so you need to cast it using ClassName.cast(instance) or ClassName.cast?(instance). .cast throws a TypeCastError if the cast can't be made while .cast? just returns nil.
builder = Gtk::Builder.new_from_string("...") # Returns a Gtk::Object
label = Gtk::Label.cast(builder["label"])Suppose you want to connect the Gtk::Widget focus signal, the C signature is:
gboolean
user_function (GtkWidget *widget,
GtkDirectionType direction,
gpointer user_data)The user_data parameter is used internally by bindings to pass closure data, so forget about it.
All signals are translated to a method named #{signal_name}_signal, that returns the signal object, the _signal suffix
exists to solve name conflicts like Gtk::Window destroy method and destroy signal.
So there are 3 ways to connect this signal to a callback:
def slot_with_sender(widget, direction)
# ...
end
# Connect to a slot with all arguments
widget.focus_signal.connect(->slot_with_sender(Gtk::Widget, Gtk::Direction)
def slot_without_sender(direction)
# ...
end
# Connect to a slot without the sender
widget.focus_signal.connect(->slot_without_sender(Gtk::Direction)
# Connect to a block (always without sender parameter)
widget.focus_signal.connect do |direction|
# ...
endIf the signal requires a slot that returns nothing, a slot that returns nothing (Nil) must be used, this is a limitation of the current implementation that will probably change in the future to just ignore the return value on those slots.
Use the after keyword argument:
# Connect to a slot without the sender
widget.focus_signal.connect(->slot_without_sender(Gtk::Direction), after: true)
# Connect to a block (always without sender parameter)
widget.focus_signal.connect(after: true) do |direction|
# ...
end# To connect the equivalent in C to "notify::my_property" do
widget.notify_signal["my_property"].connect do
# ...
end
When you connect a signal it returns a GObject::SignalConnection object, call the disconnect method on it and it's done.
When returned by methods or as signal parameters they are represented by GObject::Value class, however if a method accepts a
GValue as parameter you can pass any supported value. I.e. you can pass e.g. a plain Int32 to a method that in C expects a GValue.
You can inherit GObjects, when you do so a new type is registered in GObject type system. Crystal objects that inherit GObjects must always have a reference in Crystal world, otherwise they will be collected by the GC.
Trying to cast a GObject that was already collected by Crystal GC will result in a GICrystal::ObjectCollectedError exception.
Crystal objects that inherit GObject returns the same object reference on casts, i.e. no memory allocation is done.
For more examples see the inheritance tests.
You can declare signals in your GObject::Object derived class using the signal macro, e.g.:
class Foo < GObject::Object
signal my_signal_without_args
signal my_signal(number : Int32, some_float : Float32)
end
# Using the signal
foo = Foo.new
foo.my_signal_without_args_signal.connect { puts "Got signal!" }
foo.my_signal_signal.connect { |a, b| puts "Got signal with #{a} and #{b}!" }
# emitting signals
foo.my_signal_without_args_signal.emit
foo.my_signal_signal.emit(42, 3.14)Also note that String parameters will be copied for each signal receiver, this is because the String goes to C, then back to
Crystal as a const char* pointer. This may change in the future.
GObject Properties are declared using the GObject::Property annotation on the instance variable.
Virtual methods must have the GObject::Virtual annotation, currently only virtual methods from interfaces are supported.
class Widget0 < Gtk::Widget
# GObject virtual method name is guessed from Crystal method name, that can start with `do_`.
@[GObject::Virtual]
def do_snapshot(snapshot : Gtk::Snapshot)
end
emd
class Widget1 < Gtk::Widget
# If the `do_` prefix annoyes you, just use the same GObject virtual method name.
@[GObject::Virtual]
def snapshot(snapshot : Gtk::Snapshot)
end
end
class Widget2 < Gtk::Widget
# Or you can use whatever name and inform the GObject virtual method name in the annotation.
@[GObject::Virtual(name: "snapshot")]
def heyho(snapshot : Gtk::Snapshot)
end
endIf for some reason (peformance or GICrystal bugs 🙊️) you don't want wrappers, you can create an unsafe virtual method:
class Widget3 < Gtk::Widget
@[GObject::Virtual(unsafe: true)]
def snapshot(snapshot : Pointer(Void))
# User is responsible for memory management here, like in C.
end
endGI-Crystal translates all GLib errors to different exceptions.
Example: G_FILE_ERROR_EXIST is a GLib error from domain FILE_ERROR with the code name EXIST, GICrystal translates this
in these the following exception classes:
module GLib
class GLibError < RuntimeError
end
class FileError < GLibError
class Exist < FileError
def code : Int32
# ...
end
end
# ...
end
endSo if you want to rescue from this specific error you must rescue e : GLib::FileError::Exist, if you want to rescue from any
error in this domain you must rescue e : GLib::FileError, and finally if you want to rescue from any GLib errors you do
rescue e : GLib::GLibError.
At binding.yml file you can define the strategy used to bind the structs, if set to autoit will behave
like lsited bellow:
- If the struct have no pointer attributes it's mapped to a Crystal struct with the same memory layout of the C struct
(
stack_structbinding strategy). - If the struct have pointer attributes it's mapped to a Crystal class with the same memory layout of the C struct, so a
finalizemethod can be implemented to free the resources. Not that no setters are generated to pointer attributes, since we can't guess how this memory must be handled (heap_structbinding strategy). - If the struct is a opaque pointer it's mapped to a Crystal class with a pointer to the C object, it's assumed that the
object is a GObject Box, so the
g_boxed_*family of functions are used to handle the memory (heap_wrapper_structbinding strategy).
See HACKING.md for details about how the generator works.
- Fork it (https://github.com/hugopl/gi-crystal/fork)
- Create your feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -am 'Add some feature') - Push to the branch (
git push origin my-new-feature) - Create a new Pull Request
- Hugo Parente Lima - creator and maintainer
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent