gtk.glade.XML
Prev | The gtk.glade Class Reference | Next

## gtk.glade.XML

gtk.glade.XML — Allows dynamic loading of user interfaces from XML descriptions.

## Synopsis

    class gtk.glade.XML(gobject.GObject):
        gtk.glade.XML(fname, root=None, domain="", typedict={})
        def signal_connect(handler_name, func)
        def signal_autoconnect(dict)
        def get_widget(name)
        def get_widget_prefix(name)
        def relative_file(filename)

    Functions

        def gtk.glade.xml_new_from_buffer(buffer, size, root="", domain="", typedict={})
        def gtk.glade.get_widget_name(widget)
        def gtk.glade.get_widget_tree(widget)
        def gtk.glade.set_custom_handler(handler, user_data)
        def gtk.glade.bindtextdomain(domainname, dirname="")
        def gtk.glade.textdomain(domainname="")
        def gtk.glade.set_custom_widget_callbacks(dict)

## Ancestry

    +-- gobject.GObject
          +-- gtk.glade.XML

## gtk.glade.XML Signal Prototypes

gobject.GObject Signal Prototypes

## Description

This object represents an `instantiation' of an XML interface description. When one of these objects is created, the XML file is read, and the interface is created. The `gtk.glade.XML` object then provides an interface for accessing the widgets in the interface by the names assigned to them inside the XML description.

The `gtk.glade.XML` object can also be used to connect handlers to the named signals in the description. Libglade also provides an interface by which it can look up the signal handler names in the program's symbol table and automatically connect as many handlers up as it can that way.

## Constructor

        gtk.glade.XML(fname, root=None, domain="", typedict={})

`fname` : | the XML file name
`root` : | the widget node in `fname` to start building from (or `None`)
`domain` : | the translation domain for the XML file (or `""` for default)
`typedict` : | A dictionary used to lookup types (or `{}` for default)
Returns : | a new `gtk.glade.XML` object

Creates a new `gtk.glade.XML` object (and the corresponding widgets) from the XML file specified by `fname`. Optionally it will only build the interface from the widget node specified by `root` (if it is not `None`). This feature is useful if you only want to build say a toolbar or menu from the XML file, but not the window it is embedded in. Note also that the XML parse tree is cached to speed up creating another `gtk.glade.XML` object for the same file.

## Methods

### gtk.glade.XML.signal_connect

        def signal_connect(handler_name, func)

`handler_name` : | the signal handler name
`func` : | the signal handler function

In the glade interface descriptions, signal handlers are specified for widgets by name. The `signal_connect`() method allows you to connect a callback specified by `func` to all signals in the `gtk.glade.XML` file with the signal handler name specified by `handler_name`.

### gtk.glade.XML.signal_autoconnect

        def signal_autoconnect(dict)

`dict` : | a mapping or an instance

The `signal_autoconnect`() method is a variation of the gtk.glade.XML.signal_connect method. It uses Python's introspective features to look at the keys (if `dict` is a mapping) or attributes (if `dict` is an instance) and tries to match them with the signal handler names given in the interface description. The callbacks referenced by each matched key or attribute are connected to their matching signals. The argument is called `dict` due to compatibility reasons since originally only the mapping interface was supported. The instance variant was introduced in PyGTK 2.0.

### gtk.glade.XML.get_widget

        def get_widget(name)

`name` : | the name of the widget
Returns : | the widget matching the name or `None`

The `get_widget`() method returns a reference to the `gtk.Widget` specified by `name` in the interface description. `None` is returned, if `name` doesn't specify a widget in the interface.

### gtk.glade.XML.get_widget_prefix

        def get_widget_prefix(name)

`name` : | the prefix the widget names or `""` for all widgets
Returns : | A list of widgets that match `name` as the start of their name or `None`

The `get_widget_prefix`() method returns a list of interface `gtk.Widget` objects that have names prefixed by `name`. `None` is returned if no interface widget names match the prefix `name`.

### gtk.glade.XML.relative_file

        def relative_file(filename)

`filename` : | a relative file pathname
Returns : | the absolute file pathname

The `relative_file`() method resolves the relative pathname specified by `filename`, using the directory of the XML file as a base. If `filename` contains an absolute pathname, then the original file name is returned.

## Functions

### gtk.glade.xml_new_from_buffer

        def gtk.image_new_from_buffer(buffer, size, root="", domain="", typedict={})

`buffer` : | the string containing the XML buffer
`size` : | size of the string
`root` : | the widget node in fname to start building from (or `""`)
`domain` : | the translation domain for the XML file (or `""` for default)
`typedict` : | A dictionary used to lookup types (or `{}` for default)
Returns : | a new `gtk.glade.XML` object.

The `gtk.glade.xml_new_from_buffer`() function creates a new `gtk.glade.XML` object (and the corresponding widgets) from the string specified by `buffer`. Optionally it will only build the interface from the widget node specified by `root` (if it is not `""`). This feature is useful if you only want to build say a toolbar or menu from the XML document, but not the window it is embedded in.

### gtk.glade.get_widget_name

        def gtk.glade.get_widget_name(widget)

`widget` : | a `gtk.Widget`
Returns : | the name of the widget

The `gtk.glade.get_widget_name`() function returns the name of the `gtk.Widget` specified by `widget` that was generated by a `gtk.glade.XML` object.

### gtk.glade.get_widget_tree

        def gtk.glade.get_widget_tree(widget)

`widget` : | a `gtk.Widget`
Returns : | the `gtk.glade.XML` object that built `widget`

This `gtk.glade.get_widget_tree`() function is used to get the `gtk.glade.XML` object that built the `gtk.Widget` specified by `widget`.

### gtk.glade.set_custom_handler

        def gtk.glade.set_custom_handler(handler, user_data)

`handler` : | the custom widget handler.
`user_data` : | user data passed to the custom handler.

This `gtk.glade.set_custom_handler`() function allows you to override the default behaviour when a Custom widget is found in an interface.

### gtk.glade.bindtextdomain

        def gtk.glade.bindtextdomain(domainname, dirname)

`domainname` : | the name of the application.
`dirname` : | the directory where to find locales.
Returns : | the value of `dirname`

This `gtk.glade.bindtextdomain`() function allows you to use internationalisation with glade.

### gtk.glade.textdomain

        def gtk.glade.textdomain(domainname)

`domainname` : | the name of the application.
Returns : | the value of `domainname`

This `gtk.glade.textdomain`() function allows you to use internationalisation with glade.

### gtk.glade.set_custom_widget_callbacks

        def gtk.glade.set_custom_widget_callbacks(dict)

`dict` : | a dictionary of function names.

This `gtk.glade.set_custom_widget_callbacks`() function takes a dictionary of function names->functions, for an example see PyGTK FAQ 22.7 for an example.

Prev | Up | Next
The gtk.glade Class Reference | Home | The pango Class Reference