The gobject_gen! macro defines an extension to the Rust language so
that one can create GObject implementations, or define
GTypeInterfaces, using only safe code. All the boilerplate needed
to register the GObject type, its signals and properties, etc., is
automatically generated.

GObject classes defined through this macro can have instance-private data
declared as struct fields inside the class.

Declaration: Declare struct fields inside class Foo { ... }

Initialization: Implement the Default trait for your
struct members, either with #[derive(Default)] or with an impl Default
if its missing. Note that you have to do this for each type used across
fields. When the generated code needs to initialize the instance-private
data, it will do so by calling the Default::default() method and assign it
to the internally private structure generated by the macro.

Drop: When the GObject instance gets finalized, your private
data will be drop()ed. You can provide impl Drop for any fields
that need explicit resource management.

The Application Binary Interface (ABI) of a GObject class is
defined by its virtual method table (vtable), which includes both virtual
methods and signals. In gnome-class, this means that the order of
method or signal items inside an impl MyClass is significant:
adding, removing, or reordering the methods and signals will
change the ABI, since C code will see a MyClass struct with
fields to function pointers in a different order.

Conventionally, GObject classes can reserve a number of empty
vtable slots for future expansion. In gnome-class, you can use
the reserve_slots keyword:

With gnome-class still under development, you may need to examine
the code that gets generated from the procedural macro. First,
create a directory called generated under your crate's toplevel
directory. Then, put a generate attribute for your class, like
this:

Correspondingly, add this to Cargo.toml to declare the test-generated feature:

[features]
# If this feature is enabled, it executes the tests with
# the rust files generated during an earlier run.
test-generated = []

If you just cargo build your code, then it will output the file
generated/foo-gen.rs which you can examine. You can then edit
that file and rebuild with cargo build -- --features test-generated - this will cause
the foo-gen.rs to get included, instead of using "fresh" generated code.

Remember that changes to the generated code will be overwritten
the next time the procedural macro runs! Don't forget to report
a bug if gnome-class is generating incorrect code for you!