java-gnome 4.1.3, released 4 May 2013
About
Overview, News
Documentation
Tutorials, API, and Hacking
Download
Binaries and Source
Interact
Mailing Lists, IRC, and Reporting Bugs

doc/design/4b-ObjectProperties

Re-engineering (4): GObject property handling API

I was chatting with Davyd last night about how I’d achieved a generalized setProperty() capability for GObjects in the new bindings. I wrote him an email about one of the details, included below, but along the way I’ve arrived at a design decision that I’d like to make sure everyone is ok with.

Type safety

Java is strongly and statically typed. That’s a burden in some cases, but of course the benefit of that is type safety if something takes an Image, you can’t shot yourself in the foot by passing it a Font.

That all goes out the window if you have a generic mechanism that takes a String as the property name, and some arbitrary Object to use as the its value and then tries to do something with it:

setProperty("label", someFont)

this will compile but blow at runtime in a really ugly fashion.

Method Signatures

For a while I’ve considered properties as special, or at least as needing special treatment compared to the more usual functions that are provided. I had a good chat with Sandor about this, and we agreed that we would probably end up with:

setPropertyFoo()
setPropertyBar()

etc as a good way to present such properties to developers using our bindings in a way that would allow us type safety.

But consider that things like GtkButton have a property called “label”. GtkButton of course provides a “convenience” method to set the label. Yup, it’s gtk_button_set_label() which java-gnome mapped years ago as setLabel(). If we consider our wrapper around the standard method, and the property, we would end up with

setLabel()
setPropertyLabel()

in the same Button class, and that’s just silly.

Completion

One of the characteristics we discussed that we’re all in love with is code-completion of appropriate methods turning out to be a really cool way of finding out what things you can manipulate in (say) a Button, like,

setLabel()
setRelief()
setFocusOnClick()
setImage()

etc.

These all exist as explicit methods because in a lot of cases the methods pre-date the property system in GObject (since GtkObject predates GObject which was abstracted out of GTK+).

However, just because there is a label property does not mean that we should just set the property directly and bypass the explicit method supplied by GTK. That’s just asking for trouble, as there is always the risk that the real C function does more than just twiddling the public property.

[ok, a String label is a bad example, but there are many more properties which are decidedly internal mechanisms, especially in the more complex widgets]

So here comes a design decision:

Explicit methods for everything

We will have an explicit, strongly typed method for any characteristic that can be written to or read from.

Where a characteristic has an explicit function provided by GTK already, and we have chosen to expose it, we will wrap and bind that function as normal

setImage(Image image) -> gtk_button_set_image(button, image)

and ignore a property by the same name if such exists.

When there is no pre-existing explicit function [convenience or otherwise] on the C side for a characteristic, and a property exists and is public [and in this case, writable], and if we wish to expose it in our public API, we will do so with an appropriately named, strongly typed setter method for that property doing so by using the GObject property setting mechanism.

setAlignmentX(float align) {
    setPropertyFloat(this, "xalign", align) -> g_object_set_property(button, "xalign", align);
}

Thus our developers will never have to know that “xalign” is a property, and nor do they need to risk runtime type smashups. They can simply learn that they can set the x alignment with a predictably named method call.

Details

The hacker visible (ie protected)

setPropertyFloat()

is a type safe wrapper around the actual setProperty(); although we could have done a pile of overloading, we can’t overload a method’s return type in Java, so getProperty() wouldn’t work, whereas

getPropertyFloat()
getPropertyString(), etc

work fine… and along the way allows us to create a GValue which we can a) memory manage properly and b) pass to setProperty(String name, Value value) without having to expose the mechanics of wrapping Fundamental types. More below.

AfC

———— Forwarded Message ————
From: Andrew Cowie
To: Davyd Madeley
Subject: Method overloading
Date: Mon, 06 Nov 2006 14:26:15 +1100

After you mentioned method overloading the other day and wondered why I was bothering with different explicitly named convenience functions (protected so only bindings hackers see ‘em, but anyway), I woke up screaming worried that I may have briefly given you the idea that I didn’t know what overloading was.

Just so that you don’t think I’m a complete basket case, it occurred to me to show you what the constructor of those (likely rarely used) various fundamental Value types all call. Each one gets its pointer [as stored Java side in a long] by calling one of the various

GValue.createValue()

which looks something like the code snippet that follows. Actually, not only is the hacker visible static factory (-esque) method overloaded, but the native methods are also overloaded (for the value of the fact that crossing the JNI boundary with primitives is far more efficient than passing objects across then having to reach back to get field values).

So,

class GValue extends Plumbing {

    ...

    static final long createValue(int i) {
        return g_value_init(i);
    }

    static final long createValue(boolean b) {
        return g_value_init(b);
    }

    static final long createValue(String str) {
        return g_value_init(str);
    }

    ...

    /*
     * These ones does not match the exact prototype of g_value_init()
     * [which is (GValue*, GType)]; we do the type system magic on the
     * other side (where its all mostly macros in any case) and carry
     * out allocation using GSlice.  A rare occasion when we overload
     * the native call.
     */

    private static native final long g_value_init(int i);

    private static native final long g_value_init(boolean b);

    private static native final long g_value_init(String str);

    ...

    static final void free(Fundamental reference) {
        g_slice_free(pointerOf(reference));
    }

    /*
     * This could live in GSlice.java, I suppose, but no real reason.
     * We're below the level of clean abstraction here, and it just
     * needs to go somewhere.
     */
    private static native final long g_slice_free(long value);

    ...
}

Given that I pass primitives across the JNI boundary in the end anyway, it’s tempting to wonder why not just have the setProperty() methods do that — and indeed that is what I once had. But the underlying g_object_set_property() takes a GValue as an argument, so going to the trouble of wrapping Java primitives into a GValue means that my single hacker visible setProperty() is org.gnome.glib.Object’s

setProperty(String name, Value value)

can be used for any of the various things that can be passed to g_object_set_property(), be they Glib Fundamentals, GBoxeds, GObjects, etc, rather than needing an overload of setProperty() for every single type at each of developer API, generated java layer, and native layer levels.

Emailing my friends code commentary in an email. I must be on crack.

AfC
Sydney

Originally written as an email to java-gnome-hackers by Andrew Cowie on 6 Nov 06; last modified 4 Dec 06.

Contents copyright © 2006-2011 Operational Dynamics Consulting Pty Ltd, and Others. See AUTHORS file and source code history for the various files comprising this site for full details. This page was generated from a text document! We use John Gruber's Markdown syntax as ported to PHP by Michel Fortin. See MARKUP for details