<?xml version="1.0"?><!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [<!ENTITY legal SYSTEM "legal.xml"><!ENTITY date "Mar. 30, 2002"> <!-- date the manual was last updated --><!ENTITY app "<application>Glade</application>">]><article id="index" lang="en"> <articleinfo> <title>Glade FAQ</title> <copyright> <year>2000</year> <holder>Damon Chaplin</holder> </copyright> <publisher> <publishername> GNOME Documentation Project </publishername> </publisher> &legal; <legalnotice id="feedback"> <title>Feedback Information</title> <para> To report a bug or make a suggestion regarding this application or this documentation, please see the <ulink type="help" url="ghelp:gnome-feedback">GNOME Feedback Page</ulink>. </para> </legalnotice> <authorgroup> <author> <firstname>Damon</firstname> <surname>Chaplin</surname> </author> </authorgroup> <revhistory> <revision> <revnumber>1.0</revnumber> <date>11 May 2000</date> <!-- or use &date; --> <revdescription> <para role="author">Damon Chaplin <email>damon@gnome.org</email></para> <para role="publisher">GNOME Documentation Project</para> </revdescription> </revision> </revhistory> <releaseinfo> This is the Glade FAQ. It was last updated on &date;. </releaseinfo> </articleinfo> <!-- ============= General Information About Glade =========== --> <sect1 id="general"> <title>General Information</title> <sect2><title> What documentation is there for Glade? </title> <para> In the GNOME version of Glade the Glade Manual and this FAQ should beavailable from the Help menu. </para> <para>There are a few other tutorials and guides available on the Internet,in several languages. Links to these can be found on Glade's website at<ulink url="http://glade.gnome.org" type="http">glade.gnome.org</ulink>. </para> </sect2> <sect2><title> Is there any example code? </title> <para>Glade includes a simple text editor example application in the examples/editordirectory. If you have a binary-only package of Glade, these files haveprobably not been installed, so you'll need to download the Glade sourcecode from<ulink url="http://glade.gnome.org" type="http">glade.gnome.org</ulink>. </para> <para>The website also contains links to quite a few applications created using Glade.These may contain useful example code. See the 'Applications' page on<ulink url="http://glade.gnome.org" type="http">glade.gnome.org</ulink>. </para> </sect2> <sect2><title> Do I have to use a particular license for the C code generated by Glade? </title> <para>No. You are free to use whatever license you like for the C code generatedby Glade. </para> <para>Though in the spirit of free software we do encourage you to use the GPL orLGPL licenses. </para> </sect2> <sect2><title> Which is better - generated C code or libglade? </title> <para>For large projects libglade is recommended over generated C code.You can keep each window or dialog in a separate XML file, which makes itmore manageable for large projects with multiple developers. </para> <para>If you do want to use generated C code for large projects, I'd still suggestkeeping each window or dialog in a separate XML file. You can change theproject options so that the C code is output into separate files for eachwindow or dialog (e.g. change <filename>interface.c</filename> to<filename>main_window.c</filename>), and turnoff all the 'File Output' options. </para> </sect2> <sect2><title>How do I port a GTK+ 1.2 or GNOME 1.4 project to GTK+/GNOME 2.0. </title> <para>libglade includes a script called libglade-convert which will convert anold GTK+ 1.2 or GNOME 1.4 Glade XML file to the new GTK+/GNOME 2.0 format. </para> <para>However, for GTK+ applications there is currently a slight problem with this.You need to: (1) Convert the XML file with libglade-convert. (2) Open the new file in Glade and save it immediately. This will create the project options file with the same name as the XML file but with a 'p' on the end. (3) Add '<gnome_support>FALSE</gnome_support>' to the project options file, so Glade knows it is a GTK+ project. </para> </sect2> </sect1> <!-- ============= Creating A User Interface In Glade ======== --> <sect1 id="creating"> <title>Creating A User Interface</title> <sect2><title> When I add a widget to a window, it fills the whole window and I can't add any other widgets. </title> <para> This is not a bug in <application>Glade</application>! In GTK+ you use containers to lay out your widgets. The commonly-used containers are at the bottom of the main page on the palette. Try adding a vertical box to a window in <application>Glade</application>. Now add a table to one of the positions in the vertical box. Do you get the idea now? </para> <para> If you really want to position widgets at specific coordinates, try the Fixed container. However, this isn't recommended since your windows/dialogs will not look good when resized, and if you translate the text in the labels and buttons into other languages they may not fit. </para> </sect2> <sect2><title> How do I change the colors of a widget, e.g. make a label red? </title> <para>In GTK+ 2 there are new convenience functions to change some of the styleproperties of a widget, e.g. you can use gtk_widget_modify_fg() to set theforeground color of a widget. </para> <para>It is also possible to use GTK+ rc files to set the colors & fonts ofyour widgets.If you turn on the 'Set Widget Names' project option in Glade, that may makeit easier to refer to your widgets, as you can refer to them by name.See the GTK+ Resource Files documentation at <ulinkurl="http://developer.gnome.org/doc/API/gtk/index.html"type="http">developer.gnome.org/doc/API/gtk/index.html</ulink>. </para> <para>You can also change a widget's style within your code by callinggtk_widget_modify_style(), e.g. <programlisting> GdkColor red = { 0, 65535, 0, 0 }; GtkRcStyle *rc_style = gtk_rc_style_new (); rc_style->fg[GTK_STATE_NORMAL] = red; rc_style->color_flags[GTK_STATE_NORMAL] |= GTK_RC_FG; gtk_widget_modify_style (widget, rc_style); gtk_rc_style_unref (rc_style); </programlisting> </para> </sect2> <sect2><title> How do I add a pixmap to a button? </title> <para> Create a button and select <guilabel>Remove Label</guilabel> from the popup menu. You can then add any widgets you like to the button, e.g. a horizontal box with a pixmap and a label inside it. (<application>Glade</application> may make this even easier in future.) </para> </sect2> <sect2><title> How do I add several widgets of the same type in one go? </title> <para> Hold the 'Control' key when you select the widget in the <interface>Palette</interface>. It will then stay selected until you select another widget or the <interface>Selector</interface>. </para> </sect2> <sect2><title> I get this warning whenever I use a scrolled window: Gtk-WARNING **: <errorname>gtk_scrolled_window_add(): cannot add non scrollable widget use gtk_scrolled_window_add_with_viewport() instead</errorname> </title> <para> You can safely ignore this warning. It is output by GTK+ to remind people to update their code, since the behaviour of scrolled windows changed quite a bit between GTK+ 1.0 and GTK+ 1.2. But the <application>Glade</application> code is OK. The warning should not appear in your final application. </para> </sect2> <sect2><title> What graphics formats does Glade support? </title> <para>GTK+ 2.0 includes the gdk-pixbuf library which provides support for manygraphics formats, including PNG, TIFF, BMP, JPEG and XPM files. </para> <para>You can convert images between formats using the GIMP graphicsapplication or the 'convert' utility in the ImageMagick toolkit. </para> </sect2> <sect2><title> How do I add a signal handler? </title> <para>Follow these steps: <itemizedlist> <listitem> <para>Select the widget you want to add the handler to. </para> </listitem> <listitem> <para>Select the 'Signals' page in the Property Editor window. </para> </listitem> <listitem> <para>Click the '...' button to the right of the 'Signal:' field. This should show a popup window listing the signals that this widget emits. </para> </listitem> <listitem> <para>In the popup window, select which signal you want to connect a handler for and hit the 'OK' button. </para> </listitem> <listitem> <para>Glade automatically creates a name for the signal handler function in the 'Handler:' field, but you are free to change this if you desire. </para> </listitem> <listitem> <para>Click the 'Add' button to add it to the list of signal handlers for this widget. </para> </listitem> </itemizedlist> </para> <para>When you generate the C source code, an empty signal handler function shouldbe output in the callbacks.c file. You can add your code to this function. </para> </sect2> </sect1> <!-- ============= Building The C Code Generated By Glade ====== --> <sect1 id="building"> <title>Building The C Code</title> <sect2><title> How do I build the code generated by Glade? </title> <para> You need <application>automake</application> >= 1.4 & <application>autoconf</application> >= 2.52 to build the generated C code. You also need <application>gettext</application> >= 0.10.40 if you enabled <application>gettext</application> support. See the <citetitle>Requirements</citetitle> section in the <filename>README</filename> file for links to these. </para> <para> Run <command>./autogen.sh</command> in the toplevel directory of the project to run <application>automake</application>, <application>autoconf</application> and the related utilities to build the <filename>Makefile</filename>'s. Pass it any options you want passed to configure, e.g. <command>./autogen.sh --prefix /usr/local/gnome</command>. </para> <para> Then run <command>make</command> to build your application. </para> <para> You you must also do a <command>make install</command> so that the pixmaps are installed properly. If you don't do that, it will still run, but you won't see the pixmaps. </para> </sect2> <sect2><title> I get this error: aclocal: configure.in: 10: <errorname>macro `AM_PATH_GTK' not found in library</errorname> </title> <para> This means that the <filename>gtk.m4</filename> file cannot be found. (<filename>gtk.m4</filename> is a set of m4 macros which is installed as part of GTK+ and is used to build programs which use GTK+.) <application>aclocal</application> (part of <application>automake</application>) searches for these macros to add to <filename>aclocal.m4</filename> in your program's root directory. </para> <para> To find out whereabouts GTK+ is installed, run <command>pkg-config --cflags gtk+-2.0</command>. The <filename>gtk.m4</filename> file should be in the <filename class="directory">share/aclocal</filename> subdirectory rather than the <filename class="directory">include</filename> subdirectory. To find out the directory that <application>aclocal</application> is using, run <command>aclocal --print-ac-dir</command>. </para> <para> You should add the directory that the GTK+ m4 file is installed to the <varname>ACLOCAL_FLAGS</varname> environment variable, e.g. if the GTK+ m4 files are in <filename class="directory">/usr/local/share/aclocal</filename>, then add this to your <filename>$HOME/.profile</filename>: <command>export ACLOCAL_FLAGS="-I /usr/local/share/aclocal/"</command>. </para> </sect2> <sect2><title> I get this error: ** CRITICAL **: file glade_gnome.c: line 939 (glade_gnome_write_menu_item_source): assertion `source_buffer != NULL' failed. </title> <para> You are trying to use Gnome stock menu items in a GTK+-only app. Edit any menus you have and make sure the "Stock" property is set to "None" for every item. </para> <para>This shouldn't happen in the new version of Glade, as it prevents you fromusing GNOME features in GTK+ applications. </para> </sect2> </sect1> <!-- ============= Using The C Code Generated By Glade ====== --> <sect1 id="using"> <title>Using The C Code</title> <sect2><title> What are all the files output by Glade? </title> <para> These are the default output files, but some of your file names may differ if you have changed the project options. </para> <formalpara> <title> <filename>autogen.sh</filename> </title> <para> A script which runs <application>automake</application>, <application>autoconf</application> and the related programs in the correct order, making it very easy to build the application. You pass it any arguments you want to be passed to <application>configure</application>. After running it, you can type <command>make</command> to build the application. </para> </formalpara> <formalpara> <title> <filename>configure.in</filename> </title> <para> Standard script passed to <application>autoconf</application> to generate the configure script. </para> </formalpara> <formalpara> <title> <filename>Makefile.am</filename> </title> <para> Standard make rules passed to automake to generate the <filename>Makefile.in</filename>, which the configure script turns into <filename>Makefile</filename>. </para> </formalpara> <formalpara> <title> <filename>stamp-h.in</filename> </title> <para> Used as a timestamp by <application>automake</application>, for rebuilding some generated files. </para> </formalpara> <formalpara> <title> <filename>AUTHORS</filename>, <filename>ChangeLog</filename>, <filename>NEWS</filename>, <filename>README</filename> </title> <para> These files are all initially empty, but are created to comply with the GNU conventions. </para> </formalpara> <formalpara> <title> <filename>src/Makefile.am</filename> </title> <para> Standard automake file. </para> </formalpara> <formalpara> <title> <filename>src/main.c</filename> </title> <para> Contains the <function>main</function>() function which will create one of each window/dialog for you. </para> </formalpara> <formalpara> <title> <filename>src/interface.h</filename> </title> <para> Declarations of functions you can call to create the windows and dialogs which were built in <application>Glade</application>. </para> </formalpara> <formalpara> <title> <filename>src/interface.c</filename> </title> <para> The code to create the windows and dialogs and all the widgets. </para> </formalpara> <formalpara> <title> <filename>src/callbacks.h</filename> </title> <para> Declarations of the signal handler and callback functions which you will write. </para> </formalpara> <formalpara> <title> <filename>src/callbacks.c</filename> </title> <para> Tthe signal handler and callback functions. </para> </formalpara> <formalpara> <title> <filename>src/support.h</filename> </title> <para> Declarations of some support functions, including <function>lookup_widget</function>() which you can use to get pointers to widgets. </para> </formalpara> <formalpara> <title> <filename>src/support.c</filename> </title> <para> The support functions. </para> </formalpara> <para> If <application>gettext</application> support is enabled, the <filename class="directory">po</filename> directory is created, with <filename>POTFILES.in</filename> and a separate <filename>ChangeLog</filename>. <filename>POTFILES.in</filename> lists the source files which contain translatable strings, and you should add any source files you create here. </para> <para> <note> <title>Changing the GNOME and Gettext Support Options</title> <para> If you change the <guilabel>Gnome Support</guilabel> or <guilabel>Gettext Support</guilabel> project options after building the project, you will need to update some of the build files such as <filename>configure.in</filename> and <filename>Makefile.am</filename>. The best solution may be to change the project directory in the <interface>Project Options</interface> dialog, and to rebuild the project from scratch. However, you would have to copy over any code you have added to signal handlers. An alternative would be to delete <filename>autogen.sh</filename>, <filename>configure.in</filename>, <filename>Makefile.am</filename>, <filename>src/Makefile.am</filename>, and <filename>src/main.c</filename> and use <application>Glade</application> to recreate them. But if you have changed these files you will need to add the changes back in. (Hopefully <application>Glade</application> will deal with this better in future.) </para> </note> </para> </sect2> <sect2><title> What files can the developer edit safely and which files are overwritten? </title> <para> <application>Glade</application> will not overwrite most of the files. It will recreate the build files if they don't exist (and the corresponding project option is set.) </para> <para> The files which <application>Glade</application> overwrites are: <filename>interface.h</filename>, <filename>interface.c</filename>, <filename>support.h</filename>, and <filename>support.c</filename>. (Though you may have named them differently in your project, if you changed them in the <interface>Project Options</interface> dialog.) </para> <para> These files all have a warning at the top saying <quote>DO NOT EDIT</quote>. </para> <para> If you have added or updated any signal handlers, then these are appended to the <filename>callbacks.h</filename> and <filename>callbacks.c</filename> files. So any code you have already added for callbacks is completely safe! If you have renamed a handler function then it is up to you to remove the old version and copy any code to the new function. </para> <para> If you rename the top level widget name from, for example, <quote>OldName</quote> to <quote>New Name</quote>, then you must manually rename the corresponding function call from <function>create_OldName</function> to <function>create_New_Name</function> in the <filename>main.c</filename>. </para> </sect2> <sect2><title> How do I add my own source files to the project? </title> <para> Add the source file (and any header file) to <filename>src/Makefile.am</filename>, in the <varname><replaceable>project1</replaceable>_SOURCES</varname> variable (where <replaceable>project1</replaceable> is the name of your project). </para> <para> If you are using <application>gettext</application>, you may also want to add the source file to <filename>po/POTFILES.in</filename> so that the strings can be translated. </para> </sect2> <sect2><title> How do I add a library to the project? </title> <para>You need to add a test for the library in your project's configure.in file,making sure that the CPPFLAGS and LIBS are updated to account for the library.(The CPPFLAGS variable should contain any -I flags to pass to the Cpreprocessor, and the LIBS variable should contain the -l and -L options topass to the linker.) </para> <para>autoconf provides macros such as AC_CHECK_HEADER and AC_CHECK_LIB which canbe used to check for general headers and libraries. </para> <para>Many GTK+ and Gnome libraries provide a config script such as gtk-configwhich will output the CPPFLAGS and LIBS flags needed. </para> <para>For example, libxml provides an xml-config script which you can use like this: <programlisting> dnl Get libxml flags & libs AC_PATH_PROG(xml_config, xml-config) if test "x$xml_config" = "x"; then AC_MSG_ERROR([*** xml-config not found.]) fi XML_CFLAGS=`$xml_config --cflags 2>/dev/null` XML_LIBS=`$xml_config --libs 2>/dev/null` CPPFLAGS="$CPPFLAGS $XML_CFLAGS" LIBS="$LIBS $XML_LIBS" </programlisting> </para> <para>Make sure you place your configure.in test before the call to AC_OUTPUT. </para> </sect2> <sect2><title> How do I get a pointer to a widget from within a signal handler? </title> <para> Use the <function>lookup_widget</function>() function provided. (It can be found in <filename>support.c</filename>.) </para> <para> You pass it a pointer to any widget in a window, and the name of the widget that you want to get. Usually in signal handlers you can use the first argument to the signal handler as the first parameter to <function>lookup_widget</function>(), e.g. <programlisting>voidon_button1_clicked (GtkButton *button, gpointer user_data){ GtkWidget *entry1; entry1 = lookup_widget (GTK_WIDGET (button), "entry1"); ...} </programlisting> </para> <para> Note that this does not work if you are using libglade. The corresponding code for libglade would be: <programlisting>voidon_button1_clicked (GtkButton *button, gpointer user_data){ GladeXML* xml; GtkWidget* entry1; xml = glade_get_widget_tree (GTK_WIDGET (button1)); entry1 = glade_xml_get_widget (xml, "entry1"); ...} </programlisting> </para> </sect2> <sect2><title> How do I get a pointer to a widget in another window? </title> <para>You need to keep track of pointers to all your toplevel windows.For simple applications you can just use global variables to store thesepointers. </para> <para>For more complicated applications you can use<function>gtk_object_set_data</function>() and therelated functions to store a pointer to one window inside another window.For example, if you want to create a dialog which needs to access widgets inthe main window you can do this: <programlisting> dialog = create_dialog1 (); /* Call the function generated by Glade. */ gtk_object_set_data (GTK_OBJECT (dialog), "main_window", main_window); </programlisting>Then when you need to access the main window from within the dialog code,you can do this: <programlisting> main_window = gtk_object_get_data (GTK_OBJECT (dialog), "main_window"); </programlisting> </para> <para>You need to be careful to ensure that the pointer is always valid.If the window being pointed to is destroyed, make sure you no longer use thepointer to it or your application may crash. </para> </sect2> <sect2><title> How do I get the value of a GtkOptionMenu? </title> <para> Call <function>gtk_menu_get_active</function>() with the GtkOptionMenu's menu to get the currently selected menu item. You can use <function>g_list_index</function>() to find its index in the menu: <programlisting>voidon_button1_clicked (GtkButton *button, gpointer user_data){ GtkWidget *option_menu, *menu, *active_item; gint active_index; option_menu = lookup_widget (GTK_WIDGET (button), "optionmenu1"); menu = GTK_OPTION_MENU (option_menu)->menu; active_item = gtk_menu_get_active (GTK_MENU (menu)); active_index = g_list_index (GTK_MENU_SHELL (menu)->children, active_item); g_print ("Active index: %i\n", active_index);}</programlisting> </para> </sect2> <sect2 id="gtkoptionmenu"><title> How do I get a GtkOptionMenu to call a function when it changes? </title> <para> <application>Glade</application> doesn't support this at present, but you can set it up manually. </para> <para> When you create the window, get the option menu and connect to the <quote>deactivate</quote> signal emitted by its menu: <programlisting> window1 = create_window1 (); option_menu = lookup_widget (window1, "optionmenu1"); gtk_signal_connect (GTK_OBJECT (GTK_OPTION_MENU (option_menu)->menu), "deactivate", GTK_SIGNAL_FUNC (on_option_selected), NULL);</programlisting> </para> <para> Then add a handler to <filename>callbacks.c</filename>. You can get the index of the selected item just like the previous answer: <programlisting>static voidon_option_selected (GtkMenuShell *menu_shell, gpointer data){ GtkWidget *active_item; gint item_index; active_item = gtk_menu_get_active (GTK_MENU (menu_shell)); item_index = g_list_index (menu_shell->children, active_item); g_print ("In on_option_selected active: %i\n", item_index);}</programlisting> </para> </sect2> <sect2><title> How do I connect to GtkAdjustment signals? </title> <para> <application>Glade</application> doesn't support this at present, but you can set it up manually. </para> <para> When you create the window, get a pointer to the widget containing the adjustment, and connect to the <quote>changed</quote> or <quote>value_changed</quote> signals: <programlisting> window1 = create_window1 (); hscale = lookup_widget (window1, "hscale1"); gtk_signal_connect (GTK_OBJECT (GTK_RANGE (hscale)->adjustment), "changed", GTK_SIGNAL_FUNC (on_adjustment_changed), NULL);</programlisting> </para> </sect2> <sect2><title> How do I add rows to a GtkCList before the window is shown? </title> <para>After you create the window, using the 'create' function generated by Glade,use <function>lookup_widget</function>() to get a pointer to the GtkCListwidget, and add the rows as required. e.g. <programlisting> GtkWidget *window, *clist; gchar *row[2]; /* Our GtkCList only has 2 columns. */ window = create_window1 (); clist = lookup_widget (window, "clist1"); row[0] = "Hello"; row[1] = "World"; gtk_clist_append (GTK_CLIST (clist), row); row[0] = "Second"; row[1] = "Row"; gtk_clist_append (GTK_CLIST (clist), row); gtk_widget_show (window1); </programlisting> </para> </sect2> </sect1></article>