[Glade-devel] Glade Binding Framework

[juanpablougarte at gmail.com (Juan Pablo Ugarte)]

There you go, This is a draft i would like to include in the binding
directory and use it as a base for the documentation.

Please ask as many question you like!

glade rules!

Juan Pablo
-------------- next part --------------
GladeBindings plugins are to add support for differents interpreted languages such as python and perl.

Support is divided in two things: catalog support and script support.

The bindings modules provides these functionalities to the core trough a couple of obligatory functions.

GladeBindingInitFunc
        called after loading the binding plugin (initialize the language's interpreter)

GladeBindingFinalizeFunc
        called after unloading the binding plugin. should freed everything allocated by the init function

GladeBindingLibraryLoadFunc
        used to load a library written in the language that is supported by the binding

GladeBindingRunScriptFunc
        optionally to add scripting support.

Catalog Support:
the ability to load a widget library and its support code plugin written in other language than C.

First we need to specify the catalog's language (language="GladeBinding plugin name")
then for each widget class that needs support code we setup an adaptor class name (GladeWidgetAdaptor)
which has to be registered in the GType system when the library is loaded.

-- pythontest.xml

<?xml version="1.0" encoding="UTF-8"?>
<glade-catalog name="pythontest" library="pythontest" domain="glade-3" depends="gtk+" language="python">
        <glade-widget-classes>
                <glade-widget-class title="MyBox" name="MyBox" generic-name="mybox" 
adaptor="GladeMyBoxAdaptor"/>
        </glade-widget-classes>
        <glade-widget-group name="python" title="Python">
        <glade-widget-class-ref name="MyBox"/>
        </glade-widget-group>
</glade-catalog>

When the core find this catalog it will try to find a GladeBinding called "python" if it does it will load
the library "pythontest" calling GladeBindingLibraryLoadFunc function.

Luckily Python's gtk binding registers GTypes when importing a module.(Name is specified by __gtype_name__ 
variable)

-- pythontest.py

import gtk
import gobject
import glade

class GladeMyBoxAdaptor(glade.get_adaptor_for_type ('GtkHBox')):
        __gtype_name__ = 'GladeMyBoxAdaptor'
        def __init__(self):
                glade.GladeGtkHBoxAdaptor.__init__(self)
        def do_post_create(self, obj, reason):
                print "Hello Monty world!\n";
        def do_child_set_property(self, container, child, property_name, value):
                glade.GladeGtkHBoxAdaptor.do_child_set_property(self,container, child, property_name, value);
                print "Hello do_child_set_property\n";
        def do_child_get_property(self, container, child, property_name):
                a = glade.GladeGtkHBoxAdaptor.do_child_get_property(self,container, child, property_name);
                print "Hello do_child_get_property\n";
                return a;
        def do_get_children(self, container):
                a = glade.GladeGtkHBoxAdaptor.do_get_children(self, container);
                print "Hello do_get_children\n";
                return a;

class MyBox(gtk.HBox):
        __gtype_name__ = 'MyBox'
        def __init__(self):
                gtk.HBox.__init__(self)

Scripts:

The core will search for script in two different directories,
datadir/package/scripts/ and g_get_user_config_dir()/package/scripts/

The hierarchy in those directories should be binding_name/gtype_name/ *
For example if you want to add a python script to GtkContainers you can do it by
installing the script file in g_get_user_config_dir()/glade3/scripts/python/GtkContainer/Delete_Children.py
This will add a context menu item called "Delete Children" for any GtkContainer 
that will trigger GtkContainer's widget adaptor "action-activated::Delete_Children" signal.
This signal is used by the core to call glade_binding_run_script()

The GladeBinding has to provide a set of useful functions to be used in the scripts.

Command list:
        undo: Execute undo command.
        redo: Execute redo command.
        project_new: Create a new project.
        project_open: Open an existing project.
        project_save: Save the current project.
        project_close: Close the current project.
        project_get: Get the current project.
        project_set: Set the current project.
        project_list: List all projects.
        widget_new: Create a new GtkWidget.
        widget_delete: Delete a GtkWidget.
        widget_set: Set a GtkWidget's property.
        widget_get: Get a GtkWidget's property.
        widget_list: List all widgets.

GladeBinding TODO:

        * Support every GNOME Platform Bindings (http://gtk.org/bindings.html)

        * Perl: do some research to find out if perl gtk binding makes an actual gobject 
          when creating a perl object derived from a gobject wrapper,
          and if it does wel.. write a GladeBinding!

        * Java: see http://sablevm.org we might be able to use that jvm to run java widgets
          (http://java-gnome.sourceforge.net/)

Python binding TODO:
        * rename glade module to gladeui to avoid possible naming conflicts with libglade
        * add gladeui widgets wrappers (Palette, Inspector, etc)
        * review command list, are those command enough to use in a script?
        * find out a way to provide translations for script names!