The Shifting Sands of Bonobo.

[Nat Friedman <nat helixcode com>]

    I broke the Bonobo API again today.  And this time I really put my
weight into it, so I thought I ought to explain (but not to justify,
because frankly, what's done is done).  I'll try to make it fun.  So
come on, let's find out how to fix our source code together!

    There are really only three changes:

        1.  Activation was moved from Views to Controls.  This was
            necessary for a lot of the development that is going on
            now (Nautilus, Evolution).  Basically, people are
            starting to use controls, and are demanding more
            functionality from them than they were originally intended
            to deliver[1].  So I moved menu/toolbar merging there,
            which meant that activation had to move there as well,
            since you needed to know *when* to merge your menu/toolbar
            items (and when to unmerge them).  I made this change
            yesterday.  The things which moved:

                . The activation signals.  The "view_activate" signal
                  which used to be on GnomeView was moved to
                  GnomeControl and renamed to "activate".  Similarly,
                  "view_activated" was moved from GnomeViewFrame to
                  GnomeControlFrame and renamed to "activated".

                . The UIHandler which was stored on the ViewFrame is
                  now stored on the ControlFrame.  The old convenience 
                  routines (gnome_view_frame_[set|get]_ui_handler)
                  have been modified to defer to the superclass
                  routines (gnome_control_frame_[get|set]_ui_handler).

                . All of the activation/deactivation/notification
                  convenience routines have been moved to the
                  controls.  In all cases, the convenience routines
                  were left on the View/ViewFrame, and modified to
                  defer to the superclass routines.

                . GNOME::View::view_activate() => GNOME::Control::activate()

                . GNOME::ViewFrame::view_activated() =>
                        GNOME::ControlFrame::activated()

            
            How to fix your code:

                * If you are using GNOME_ViewFrame_view_activated()
                  directly, start using gnome_view_activate_notify().

                * Change the signal name from "view_activate" to
                  "activate" and from "view_activated" to "activated".


        2.  I renamed every Bonobo identifier.

            This is definitely the most putrescent change I've ever
            made to Bonobo, so I won't be surprised if I get hit by
            rocks when I walk down the street for the next few days.

            Basically, Miguel and I got sick of Bonobo sharing the
            Gnome namespace, both in the IDLs and all over the Gtk
            code.  So I spent a disgustingly long time renaming
            everything.  Here's a laundry list of what I changed:

            Gtk Objects
            ========================================================

                . GnomeObject             --> BonoboObject
                . GnomeObjectClient       --> BonoboObjectClient
                . GnomeControl            --> BonoboControl
                . GnomeControlFrame       --> BonoboControlFrame
                . GnomeUIHandler          --> BonoboUIHandler
                . GnomeView               --> BonoboView
                . GnomeViewFrame          --> BonoboViewFrame
                . GnomeEmbeddable         --> BonoboEmbeddable
                . GnomeClientSite         --> BonoboClientSite
                . GnomeContainer          --> BonoboContainer
                . GnomePersist            --> BonoboPersist
                . GnomePersistFile        --> BonoboPersistFile
                . GnomePersistStream      --> BonoboPersistStream
                . GnomeStream             --> BonoboStream
                . GnomeStorage            --> BonoboStorage
                . GnomeProgressive        --> BonoboProgressive
                . GnomeMoniker            --> BonoboMoniker
                . GnomeDesktopWindow      --> BonoboDesktopWindow
                . GnomeComponentDirectory --> BonoboComponentDirectory
                . GnomeGenericFactory     --> BonoboGenericFactory
                . GnomePropertyBag        --> BonoboPropertyBag
                . GnomePropertyBagClient  --> BonoboPropertyBagClient
                . GnomeWrapper            --> BonoboWrapper

                . GnomeCanvasItem         --> BonoboCanvasComponent
                . GnomeBonoboItem         --> BonoboCanvasItem
                . GnomeBonoboWidget       --> BonoboWidget
                . GnomeBonoboSelector     --> BonoboSelector

            So as you can see[2], I pretty much just replaced "Gnome"
            with "Bonobo".  The only exceptions were those names which 
            just wouldn't make sense otherwise (the last 4).  I also
            took the opportunity to clean up the naming scheme on the
            Bonobo Canvas stuff.

            CORBA Interfaces
            ========================================================

            CORBA module "GNOME" has been renamed to "Bonobo".  This
            affects all the vepvs, epvs, skels, stubs...

            File names
            ========================================================

            All the .[ch] files in bonobo/bonobo were renamed to match
            the changes in the Gtk class names (e.g. gnome-view.c =>
            bonobo-view.c).  All of the IDLs were renamed similarly
            (gnome-control.idl ==> bonobo-control.idl).  The
            non-obvious changes:

                bonobo/gnome-bonobo.h

                    This was the name of the "main" bonobo header file 
                    which you are supposed to include in your
                    application to use Bonobo.  For some reason,
                    someone[3] gave it this really non-intuitive name
                    when Bonobo was begun many moons ago.  Anyways,
                    it's been renamed to "bonobo.h" and now gets
                    installed in your top-level includedir.  Change:

                        #include <bonobo/gnome-bonobo.h>

                            to

                        #include <bonobo.h>
        
                idl/bonobo.idl

                    This was the top-level IDL file which contained
                    all of the others and which is used to general the 
                    stubs/skels/etc.  So when orbit-idl processed this
                    file, it would autogenerate bonobo.h.  But we just
                    renamed gnome-bonobo.h to bonobo.h.  So I renamed
                    this file to Bonobo.idl.


        3.  GNOME::Unknown and GNOME::GenericFactory were moved into
            Bonobo from gnome-libs.  So we now use Bonobo::Unknown and 
            Bonobo::GenericFactory, as defined in:

                 bonobo/idl/bonobo-unknown.idl
                 bonobo/idl/bonobo-factory.idl


    Now, I realize that all these changes sum up to an egregious act
of heresay.  Rest assured that this should be the last of the big API
changes in Bonobo (for 1.0 anyways).  I also wrote some scripts that
can help you to convert your Bonobo-using application to the new API.
These aren't guaranteed to work and the first version turned all my C
files zero-length so beware.  I have fixed Gnumeric and Gill and am
committing those fixes now.  Gpdf I could not fix because of a
namespace collision my changes evoked (sigh).

    The scripts I wrote are checked in and are called
bonobo/nat-namechange.pl and bonobo/nat-rename.sh.  This mail is in
bonobo/nat-rename.txt.

    Also, if anyone notices anything that I missed, please let me
know.

Best of luck,
Nat

[1] The other way of looking at it is that we didn't make the
    View/Embeddable system sufficiently general for day-to-day use.
    Of course if Bonobo is going to be a compound document system, I
    think View/Embeddable need to be significantly *less* general and
    markedly more document-specific.

[2] I may have left a class or two out of this list.  If it's not
    listed, that doesn't mean it's unaffected.

[3] Miguel.