StdProp events !

[Cyrille Chepelov <chepelov calixo net>]

Hi all,

   just a short notice on a new capability of the StdProp code, and a HOWTO:

First, grab the last CVS, and put a few "SADT - Annotation" objects in a
document (type a few random characters, to be able to see the text).

Now, open the property page, and click on the "click me" button. Apply,
check the colour ! Group a few annotations together, try again ; add just
another kind of object in the group, and check that you don't have this
"click me" button anymore.

(This demo, of course, will vanish from SADT annotation shortly, it was just
convenient to do it there for testing purposes).

Back to technical realm:
        * basically, most property types can be attached an event handler.
If the property value changes, an event is triggered (yes, it's actually a
Gtk signal but hidden), and you handler gets passed a copy of the object
being edited, with the properties reflecting what is currently in the
property dialog. You can modify that object's properties to you heart's
content, and the new state of the scratch object is copied in the property
dialog when you return from your property handler.

        * For an object writer, it's actually very simple: you just write a
short handler
        static gboolean 
        handle_event_foo (YourObjectType *obj, Property *prop) 
        {
           /* do whatever you want with your object, it's a scratch copy */
           return TRUE;
        }

        then you just register it as the event_handler field of a property
descriptor. In the case of a button property (which is a property which has
a widget, has no in-object and no on-disk representations), it's simply
something like that:
          {"btn1", PROP_TYPE_BUTTON, PROP_FLAG_VISIBLE, NULL, "Click Me !", NULL, 
           (PropEventHandler)handle_btn1},
         (since a button has no in-object representation, you don't have to
put a PropOffset record for that property, though it would not do harm).

        Most basic property widgets are able to send signals, the more
complex ones (dia-specific widgets, mostly) need some trivial fixing up to
send signals too (or to check that they already do send signals).

A few guarantees the event delivery code is supposed to enforce:
        * your event handler will always be passed the correct object type,
and the object will exist, and it will be a scratch object, and there is no
undo to support in that object.
        * properties with event handlers will merge only with properties of
the same name, exact same event handler, and only if the flag
PROP_FLAG_DONT_MERGE is absent. Most of the time, this means that the
property is not edited if you edit a heterogenic group, and could be edited
if you have a homogenic one.
        * the homogeny rule works as follow: there can be as many nested levels of
groups and subgroups, which are never taken into account. Only non-group
objects are evaluated.

Most of the UML and EML objects could be converted to StdProp code (some of
the simpler UML ones already are more or less). We still lack a (visible,
in-object but not on-disk) property type to hold a list of strings and
select one line. With that last property type, I'm extremely confident we
could convert the juggernauts like UML Class and EML Process to some
interesting level of StdProp code !

        -- Cyrille

-- 
Grumpf.