]> James Henstridge

james@daa.com.au

1999-2001 James Henstridge Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. You may obtain a copy of the GNU Free Documentation License from the Free Software Foundation by visiting their Web site or by writing to: Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. Many of the names used by companies to distinguish their products and services are claimed as trademarks. Where those names appear in any GNOME documentation, and those trademarks are made aware to the members of the GNOME Documentation Project, the names have been printed in caps or initial caps. This manual documents the interfaces of the libglade library and has some short notes to help get you up to speed with using the library. Libglade is an alternative to using Glade's code generation. Instead of generating code from the XML interface description, libglade loads and parses the description at runtime. It also provides functions that can be used to connect signal handlers to parts of the interface. In this way, it allows you to separate your program code from the interface code. In fact, if you use the glade_xml_signal_autoconnect() function, the GUI code could be as simple as the test-libglade.c example that comes with libglade. Of course, you would also add your own signal handlers to the code. Note that the signals are connected the same way as if you had hand coded the interface. There is no extra overhead to interfaces generated by libglade (after the initial generating of course, and this is not much of an overhead) when compared to a hand crafted interface. Your basic libglade program will look something like this: #include <gtk/gtk.h> #include <glade/glade.h> void some_signal_handler_func(GtkWidget *widget, gpointer user_data) { /* do something useful here */ } int main(int argc, char *argv[]) { GladeXML *xml; gtk_init(&argc, &argv); glade_init(); /* load the interface */ xml = glade_xml_new("filename-for-interface", NULL); /* connect the signals in the interface */ glade_xml_signal_autoconnect(xml); /* start the event loop */ gtk_main(); return 0; } This will create the interface from the file filename-for-interface, then connect all the signals in the interface. The automatic signal connection is done by looking up function names in the symbol table using gmodule. This means that the interface file can use standard GTK functions such as gtk_widget_show, or gtk_main_quit, or others in the interface and not have to write any code to connect the signals. The some_signal_handler_func function is not referenced anywhere in the program explicitely, but if any signals are defined in the interface description that use "some_signal_handler_func" as the handler name, then this function will automatically be connected. Note that the function can not be static, since we require it to apear in the symbol table. Here is an example of the XML that would cause some_signal_handler_func to be connected: <widget> <class>GtkWindow</class> <name>MainWindow</name> <signal> <name>destroy</name> <handler>some_signal_handler_func</handler> </signal> ... To compile the program, we would use the following: cc -o testprogram testprogram.c `libglade-config --cflags --libs` The libglade-config script will give the correct parameters used to compile the program. If you are using automake or autoconf, you may want to investigate the AM_PATH_LIBGLADE macro that is installed as $(datadir)/aclocal/libglade.m4. Libglade is starting to support the GNOME widgets (I am adding support as it is added to Glade, so that the file formats do not get out of sync). The GNOME support is done in a modular way, so that applications that do not use the GNOME support do not need to link with the GNOME libraries. For this reason, you need to link with an extra library if you want GNOME support (add -lglade-gnome to the start of the library list), and call glade_gnome_init to intitialise libglade, instead of glade_init. To get the link flags for GNOME support, once again you use the libglade-config script. To build the program, you would now use: cc -o testprogram testprogram.c `libglade-config --cflags --libs gnome` If you use the AM_PATH_LIBGLADE autoconf macro, giving "gnome" as the third parameter will have the same effect. Note that libglade-config will give an error if GNOME support was not compiled, and GNOME support is asked for. Libglade now supports i18n through the gettext system. The libglade-xgettext program that is distributed with libglade can be used to extract translatable strings from (multiple) XML interface descriptions. It can output in either the standard PO file format, or output a dummy C file that can be fed to xgettext with the rest of the source of your package. For full details, run "libglade-xgettext --help". Note that this program requires python. If this is too inconvenient to a lot of people, I may consider rewriting it in C (patches welcome :) While building the interface, libglade will translate the strings it finds, if i18n was not disabled during build. It will default to using the current text domain for the translations. If you want to specify a different domain (this would be useful for libglade dialogs provided by a library), you can use the glade_xml_new_with_domain to create the GladeXML object, rather than glade_xml_new. This will cause the strings to be translated using a different translation domain. In some cases, libglade may not provide support for the widgets you want to use, or you may want to insert a bit of hand coded interface into the larger libglade generated interface. Libglade provides support for doing this. If you are only need a few custom widgets (eg. a word processor may have a custom widget for the document editing area), the simplest choice is probably Glade's custom widget. It allows you to specify a custom function that will be used to create the widget. The signature of the function is as follows: GtkWidget *custom_func(gchar *widget_name, gchar *string1, gchar *string2, gint int1, gint int2); When calling this function, widget_name is the name of the widget given in the XML file, and string1, string2, int1 and int2 are arbitrary constants whose values also come from the XML file. Libglade supports the custom widget using gmodule. For most cases, this is sufficient. If you wish to get libglade to recognise new widget types, you will need to do a bit more work. You will need to write a function that will create the widget from a node in the XML tree (the function need not worry about standard options like whether the widget is visible or not, or how it is added to its parent). If the widget is also a container, you will need to specify a child building function (which is also responsible for adding the widgets to container). If the container uses the standard gtk_container_add interface, you can use the glade_standard_build_children function that is provided by libglade. For a more extensive example of registering new widget types and build functions, see the files glade/glade-gtk.c or glade/glade-gnome.c in the libglade package. For more information on the exact API's used to register new widget types with libglade, see the Libglade Build section of this manual. Sometimes you will only want to use libglade for a small part of your program. If it is just for some dialogs, this is easy -- you just generate the dialogs from the interface files when needed (note that libglade caches the XML parse tree between calls to glade_xml_new, so you will not suffer the performance hit of parsing a particular XML file more than once). On the other hand, you may want to use libglade to generate just the menubar or just a notebook for a dialog or something. Libglade allows this as well. Libglade allows you to build only part of the interface if you want to. The second argument to glade_xml_new specifies the name of the base widget to build the interface from. This way we can limit the widgets that are constructed by libglade. For the menubar example, we would create a dummy window in Glade, and insert a menubar widget into the window. We would then name the menubar in glade ("menubar" isn't a bad name :), and customise it as much as we want. Now in the program, we can use the following code: GladeXML *xml; GtkWidget *menubar; xml = glade_xml_new("some-interface-file", "menubar"); glade_xml_signal_autoconnect(xml); menubar = glade_xml_get_widget(xml, "menubar"); /* do whatever we want to with the menubar */ From here, we can do what ever we want with the menubar widget. The dummy window we created in Glade is never created, so does not affect the program. You can also use similar code to only build a single dialog from a file that contains many dialogs. One thing to note -- if you don't want a widget to be displayed as soon as it is built with glade_xml_new, you should turn off the visible flag on that widget in Glade. This is the correct solution to the problem (putting a hack into libglade so that it never shows the toplevel windows is not The Right Thing). This section contains the API reference for libglade. All the public interfaces are documented here. &libglade-glade; &libglade-glade-xml; &libglade-glade-sax; &libglade-glade-build;