Property re-write...

[Michael Meeks <michael helixcode com>]

Hi,

	I've just committed the property re-write that we have been
working on for the last few days. Miguel asked me to write and tell people
what I've done or at least how to update your code. If you don't really
care much about the rational, the best way to update your code is to read:

	bonobo/samples/controls/bonobo-clock-control.c.

Some points to bear in mind:

	* I have scrapped textual typing; use BONOBO_ARG_BOOLEAN eg. or if
you have a death wish TC_boolean.

	* 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:

	BONOBO_ARG_SET_BOOLEAN (arg, my_boolean_value);

and

	my_boolean_value = BONOBO_ARG_GET_BOOLEAN (arg);

	etc.

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

	* 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 ?


	If on the other hand you want a detailed ChangeLog / a description
of how it works then read on. This is best read having read the clock
sample control.

	Essentialy the main change has been to rationalise state storage.
Previously we stored state in a 3rd party ( 'The Bag' [ beware of the bag
] ). Hence remote parties inserted things and local parties were notified
about this state change and grabbed the thing and updated their own state.

	This whilst working duplicated state it being stored in 'The Bag'
and also in 'The Object'. Furthermore, the problem of storing arbitary
state in a 3rd part is rather a nasty one. It transpires that the only way
to do this ( feasibly ) is to have the 3rd party understand ( ie. be
able to manipulate, and store ) all possible states.

	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.

	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.

	For particularly obtuse persons wanting more flexibility it is
possible to specify the get / set / user_data triplet per property.

	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);

	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);

	It's reference is stored in the property_bag.

	The rest of the code is internal and extremely transparent. In
order to implement the get/set functions I would copy & paste the sample.


	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 ?

	Regards,

		Michael.

-- 
 mmeeks@gnu.org  <><, Pseudo Engineer, itinerant idiot