Re: Property re-write...

[Nat Friedman <nat helixcode com>]

Hi Michael,

    Wow, this is fabulous.  I've always been dissatisfied with the
component-side property API and you've really, really, really taken it
a long way.

Michael Meeks <michael@helixcode.com> writes:

> 	* You don't want to get state out of the BonoboArg's yourself, I
> have seen lots of bugs in code to do this ( particularly assuming you can
> cast a CORBA_boolean * to a gboolean * [ CORBA_boolean is a uchar,
> gboolean is an int ]. So instead use:

Are they args or are they properties?  Let's settle on a nomenclature.
I vote for properties.  We can call them props for short.

> 	* I have drasticaly reduced the number of base types we reccommend
> to: boolean, int, float, double, string. Since the arguments must be
> marshalled at length etc. it makes no sense to have a signed / unsigned
> distinction.

We need an example of a custom enum.  Enums are going to be tricky
either way.

> 	* You _REALLY_ don't want to do:
> 
> 	BONOBO_ARG_SET_STRING (arg, NULL);
> 
> 	oh no, this will blow up ORBit good and proper at some interesting
> place and you'll blame me. Instead use a "" string. Should we consider
> adding the check in the set_string ?

Yes, please put the check in.  Experience with this particular issue
has taught me that people will screw it up if given the opportunity.

> 	Hence or otherwise it was thought that a better approach would be
> to transmit property get / set's to the actual object and leave that to
> store the state as it wished.

Attributes on steroids.  Yup.

> 	This then is the essence of the change. Each property has a get /
> set / user_data triplet that determines how it will behave. In a typical
> use all object properties would use the same get/set/user_data triplet,
> and be identified by a unique integer arg_id ( set up at register time ).
> This can then be handled efficiently using a switch statement. Previously
> all arguments were recognised by slow string compares.

Which doesn't really matter since that's how methods are basically
done in ORBit and the strings are usually short and with quad word
comparisons on modern hardware... but anyways...

I think we need to set the example of defining your property
identifiers with enums at the beginning of each component
implementation file, like people do with Gtk signals.  Enums have the
advantages of being usable from gdb and gcc will issue the appropriate
warning if you miss one.

> 	Each basic property is created by this function:
> 
> void bonobo_property_bag_add (BonoboPropertyBag  *pb,
>                               const char         *name,
> 			      int                 idx,
>                               BonoboArgType       type,
> 		              BonoboArg          *default_value,
> 	    		      const char         *docstring,
>                               BonoboPropertyFlags flags);

Let's make sure we have types defined that'll be needed by glade.  I
think we need to define color, for example.  Or maybe that's just a
string.

> 	It looks horrendous, but is horribly simple in most cases; the idx
> is the index that will be passed to a generic get/set function for this
> property. The type is one of the BONOBO_ARG_[BOOLEAN,INT,FLOAT...] defines
> which maps to an ORBit TypeCode [ hence any arbitary type can be added
> without the property-bag knowing anything about it ( allocation of that
> type is the users responsibility ) ]. Default_value is either NULL or a
> value created thusly:
> 
> 	BonoboArg *def = bonobo_arg_new (BONOBO_ARG_DOUBLE);
> 	BONOBO_ARG_SET_DOUBLE (def, 0.3127);

Can't we do this in-line somehow?  Default value is going to be really
commonly needed and this means you have to have three lines per new
property.  I'm thinking something like

bonobo_property_bag_new (....

        BONOBO_ARG_SET_DOUBLE (
            bonobo_arg_new (BONOBO_ARG_DOUBLE),
            0.3127)  /* Default value */

        ...);

where BONOBO_ARG_SET_DOUBLE is defined in such a way that the value of
the expression is the new value for the property.  Of course, it
should be BONOBO_PROP_SET_DOUBLE.

> 	We have also macroified the code to remove some of the cutting and
> pasting neccessary to provide the C API.
> 
> 	I suppose this could form the body of a 'properties howto', so any
> questions ? where have I been unclear ?

Pretty good!  We need a client-side use case though.

You kick butt Michael.

Nat