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._

<!--
 
  Copyright © 2006 Operational Dynamics Consulting, Pty Ltd and Others

  As project documentation, this file forms an integral part of the source
  code of the library it accompanies, and thus is made available to you by its
  authors as open source software: you can redistribute it and/or modify it
  under the terms of the GNU General Public License version 2 ("GPL") as
  published by the Free Software Foundation.

  This program is distributed in the hope that it will be useful, but WITHOUT
  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  FITNESS FOR A PARTICULAR PURPOSE. See the GPL for more details.

  You should have received a copy of the GPL along with this program. If not,
  see http://www.gnu.org/licenses/. The authors of this program may be
  contacted through http://java-gnome.sourceforge.net/.

  vim: set textwidth=78 nowrap:

-->