that I don’t think is documented anywhere. So I’m writing a blog post about it. I hope readers from Planet GNOME can help figure out where it needs to be documented.

For an object (let’s call it FooLabel) that’s part of the public API of a library (let’s call it libfoo), creating the object via its foo_label_new() constructor function should be equivalent to creating it via g_object_new().

If foo_label_new() takes no arguments then it should literally be only this:

If it does take arguments, then they should correspond to construct properties, and they should get set in the g_object_new() call. (It’s customary to at least put all construct-only properties as arguments to the constructor function.) For example:

The reason for that is because callers of your library will expect to be able to create FooLabels using g_object_new() in many situations. This is done when creating a FooLabel in JS and Python, but also when creating one from a Glade file, and also in plain old C when you need to set construct properties. In all those situations, the private field some_variable will not get initialized to 5!

Instead, put the code in foo_label_init(). That way, it will be executed regardless of how the object is constructed. And if you need to write code in the constructor that depends on construct properties that have been set, use the constructed virtual function. There’s a code example here.

This is tricky because the wrong way seems like the most obvious way to me!

This has been a public service announcement for the GNOME community, but here’s where you come in! Please help figure out where this should be documented, and whether it’s possible to enforce it through automated tools.

For example, the Writing Bindable APIs page seems like a good place to warn about it, and I’ve already added it there. But this should probably go into Vala documentation in the appropriate place. I have no idea if this is a problem with Rust’s gobject_gen! macro, but if it is then it should be documented as well.

Documented pitfalls are better than undocumented pitfalls, but removing the pitfall altogether is better. Is there a way we can check this automatically?

5 thoughts on “Geek tip: g_object_new and constructors”

There’s no need to cast the return value of g_object_new() if you’re using it from C: it returns a void*, which means it’ll be implicitly cast to the return value of the constructor function. Unless you’re disabling the cast checks macros, you’re just performing a run time type check on something that can only return an instance of the type you used.

I’d known about this footgun for a long time, but had never considered its implications for Vala… looks like every class in libgnome-games-support has this flaw. Oops. Probably time for me to pay some attention to that….

Ooops, I have an unfixable API. My Vala class Scores.Context needs to be passed a function pointer at construct time, which will be used before the call to g_object_new() returns. I think the only way it’s possible using construct properties would be to use void*, but then that’s even worse for bindings. Oh well….