diff options
Diffstat (limited to 'tools/glade/doc/C/glade-faq/glade-faq.xml')
| -rw-r--r-- | tools/glade/doc/C/glade-faq/glade-faq.xml | 910 |
1 files changed, 910 insertions, 0 deletions
diff --git a/tools/glade/doc/C/glade-faq/glade-faq.xml b/tools/glade/doc/C/glade-faq/glade-faq.xml new file mode 100644 index 00000000..a668e23b --- /dev/null +++ b/tools/glade/doc/C/glade-faq/glade-faq.xml @@ -0,0 +1,910 @@ +<?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 be +available 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/editor +directory. If you have a binary-only package of Glade, these files have +probably not been installed, so you'll need to download the Glade source +code 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 generated +by Glade. + </para> + <para> +Though in the spirit of free software we do encourage you to use the GPL or +LGPL 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 it +more manageable for large projects with multiple developers. + </para> + <para> +If you do want to use generated C code for large projects, I'd still suggest +keeping each window or dialog in a separate XML file. You can change the +project options so that the C code is output into separate files for each +window or dialog (e.g. change <filename>interface.c</filename> to +<filename>main_window.c</filename>), and turn +off 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 an +old 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 style +properties of a widget, e.g. you can use gtk_widget_modify_fg() to set the +foreground color of a widget. + </para> + <para> +It is also possible to use GTK+ rc files to set the colors & fonts of +your widgets. +If you turn on the 'Set Widget Names' project option in Glade, that may make +it easier to refer to your widgets, as you can refer to them by name. +See the GTK+ Resource Files documentation at <ulink +url="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 calling +gtk_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 many +graphics formats, including PNG, TIFF, BMP, JPEG and XPM files. + </para> + <para> +You can convert images between formats using the GIMP graphics +application 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 should +be 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 from +using 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> + + </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 C +preprocessor, and the LIBS variable should contain the -l and -L options to +pass to the linker.) + </para> + <para> +autoconf provides macros such as AC_CHECK_HEADER and AC_CHECK_LIB which can +be used to check for general headers and libraries. + </para> + <para> +Many GTK+ and Gnome libraries provide a config script such as gtk-config +which 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> +void +on_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> + +void +on_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 these +pointers. + </para> + <para> +For more complicated applications you can use +<function>gtk_object_set_data</function>() and the +related 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 in +the 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 the +pointer 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> +void +on_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 void +on_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 GtkCList +widget, 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> |