diff options
Diffstat (limited to 'tools/glade/FAQ')
| -rw-r--r-- | tools/glade/FAQ | 506 |
1 files changed, 506 insertions, 0 deletions
diff --git a/tools/glade/FAQ b/tools/glade/FAQ new file mode 100644 index 00000000..a5b2bdd8 --- /dev/null +++ b/tools/glade/FAQ @@ -0,0 +1,506 @@ + +Table of Contents +================= + +1. General Information About Glade + + 1.1 What documentation is there for Glade? + 1.2 Is there any example code? + 1.3 Do I have to use a particular license for the C code generated by Glade? + 1.4 Which is better - generated C code or libglade? + 1.5 How do I port a GTK+ 1.2 or GNOME 1.4 project to GTK+/GNOME 2.0. + +2. Creating A User Interface In Glade + + 2.1 When I add a widget to a window, it fills the whole window and I can't + add any other widgets. + 2.2 How do I change the colors of a widget, e.g. make a label red? + 2.3 How do I add several widgets of the same type in one go? + 2.4 What graphics formats does Glade support? + 2.5 How do I add a signal handler? + +3. Building The C Code Generated By Glade + + 3.1 How do I build the code generated by Glade? + + 3.2 I get this error: + aclocal: configure.in: 10: macro `AM_PATH_GTK' not found in library + +4. Using The C Code Generated By Glade + + 4.1 What are all the files output by Glade? + 4.2 What files can the developer edit safely and which are overwritten? + 4.3 How do I add my own source files to the project? + 4.4 How do I add a library to the project? + 4.5 How do I get a pointer to a widget from within a signal handler? + 4.6 How do I get a pointer to a widget in another window? + 4.7 How do I get the value of a GtkOptionMenu? + 4.8 How do I get a GtkOptionMenu to call a function when it changes? + 4.9 How do I connect to GtkAdjustment signals? + 4.10 How do I add rows to a GtkCList before the window is shown? + + +============================================================================== + +1. General Information About Glade +================================== + +1.1 What documentation is there for Glade? + +In the GNOME version of Glade the Glade Manual and this FAQ should be +available from the Help menu. + +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 +http://glade.gnome.org. + + +1.2 Is there any example code? + +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 http://glade.gnome.org. + +The website also contains links to quite a few applications created using Glade. +These may contain useful example code. See the 'Applications' page on +http://glade.gnome.org. + + +1.3 Do I have to use a particular license for the C code generated by Glade? + +No. You are free to use whatever license you like for the C code generated +by Glade. + +Though in the spirit of free software we do encourage you to use the GPL or +LGPL licenses. + + +1.4 Which is better - generated C code or libglade? + +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. + +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 'interface.c' to 'main_window.c'), and turn +off all the 'File Output' options. + + +1.5 How do I port a GTK+ 1.2 or GNOME 1.4 project to GTK+/GNOME 2.0. + +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. + +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. + + +============================================================================== + +2. Creating A User Interface In Glade +===================================== + +2.1 When I add a widget to a window, it fills the whole window and I can't + add any other widgets. + +This is not a bug in Glade! 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 Glade. +Now add a table to one of the positions in the vertical box. +Do you get the idea now? + +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. + + +2.2 How do I change the colors of a widget, e.g. make a label red? + +In GTK+ 2 the label widget allows the use of special markup to change the +text attributes, e.g. in Glade select the label and turn on the "Use Markup" +property, then entrt "<span color="red">Hello World</span>" into the "Label" +property. + +For other widgets you can use functions like gtk_widget_modify_fg() to set the +foreground color of a widget, or gtk_widget_modify_style() e.g. + + 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); + +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 http://developer.gnome.org/doc/API + + +2.3 How do I add several widgets of the same type in one go? + +Hold the 'Control' key when you select the widget in the palette. It will +then stay selected until you select another widget or the selector. + + +2.4 What graphics formats does Glade support? + +GTK+ 2.0 includes the gdk-pixbuf library which provides support for many +graphics formats, including PNG, TIFF, BMP, JPEG and XPM files. + +You can convert images between formats using the GIMP graphics +application or the 'convert' utility in the ImageMagick toolkit. + + +2.5 How do I add a signal handler? + +Follow these steps: + + o Select the widget you want to add the handler to. + o Select the 'Signals' page in the Property Editor window. + o Click the '...' button to the right of the 'Signal:' field. This should + show a popup window listing the signals that this widget emits. + o In the popup window, select which signal you want to connect a handler for + and hit the 'OK' button. + o Glade automatically creates a name for the signal handler function in the + 'Handler:' field, but you are free to change this if you desire. + o Click the 'Add' button to add it to the list of signal handlers for this + widget. + +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. + + +============================================================================== + +3. Building The C Code Generated By Glade +========================================= + +3.1 How do I build the code generated by Glade? + +You need automake >= 1.4 & autoconf >= 2.52 to build the generated C code. +You also need gettext >= 0.10.40 if you enabled gettext support. See the +'Requirements' section in the README file for links to these. + +Run './autogen.sh' in the toplevel directory of the project to run +automake, autoconf and the related utilities to build the Makefiles. Pass +it any options you want passed to configure, e.g. + + ./autogen.sh --prefix /usr/local/gnome + +Then run 'make' to build your application. + +You must also do a 'make install' so that the pixmaps are installed +properly. If you don't do that, it will still +run, but you won't see the pixmaps. + + +3.2 I get this error: + + aclocal: configure.in: 10: macro `AM_PATH_GTK' not found in library + +This means that the gtk.m4 file cannot be found. (gtk.m4 is a set of m4 +macros which is installed as part of GTK+ and is used to build programs +which use GTK+.) aclocal (part of automake) searches for these macros to +add to aclocal.m4 in your program's root directory. + +To find out whereabouts GTK+ is installed, run +'pkg-config --cflags gtk+-2.0'. +The gtk.m4 file should be in the 'share/aclocal' subdirectory rather than +the 'include' subdirectory. +To find out the directory that aclocal is using, run 'aclocal --print-ac-dir' + +You should add the directory that the GTK+ m4 file is installed to the +ACLOCAL_FLAGS environment variable, e.g. if the GTK+ m4 files are in +/usr/local/share/aclocal, then add this to your $HOME/.profile: + + export ACLOCAL_FLAGS="-I /usr/local/share/aclocal/" + + +============================================================================== + +4. Using The C Code Generated By Glade +====================================== + + +4.1 What are all the files output by Glade? + +These are the default output files, but some of your file names may differ +if you have changed the project options. + +autogen.sh - a script which runs automake, autoconf 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 configure. After running it, you can type 'make' + to build the application. +configure.in - standard script passed to autoconf to generate the configure + script. +Makefile.am - standard make rules passed to automake to generate the + Makefile.in, which the configure script turns into Makefile. +stamp-h.in - used as a timestamp by automake, for rebuilding some + generated files. + +AUTHORS - these files are all initially empty, but are created to +ChangeLog comply with the GNU conventions. +NEWS +README + +src/Makefile.am - standard automake file. +src/main.c - contains the main() function which will create one of each + window/dialog for you. +src/interface.h - declarations of functions you can call to create the windows + and dialogs which were built in Glade. +src/interface.c - the code to create the windows and dialogs and all the + widgets. +src/callbacks.h - declarations of the signal handler and callback functions + which you will write. +src/callbacks.c - the signal handler and callback functions, +src/support.h - declarations of some support functions, including + lookup_widget() which you can use to get pointers to widgets. +src/support.c - the support functions. + + +If gettext support is enabled, the po directory is created, with POTFILES.in +and a separate ChangeLog. POTFILES.in lists the source files which contain +translatable strings, and you should add any source files you create here. + +*NOTE*: if you change the 'GNOME Support' or 'Gettext Support' project +options after building the project, you will need to update some of the +build files such as configure.in, Makefile.am +The best solution may be to change the project directory in the 'Project +Options' 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 autogen.sh, configure.in, Makefile.am, src/Makefile.am, +and src/main.c and use Glade to recreate them. But if you have changed these +files you will need to add the changes back in. +(Hopefully Glade will deal with this better in future.) + + + +4.2 What files can the developer edit safely and which files are overwritten? + +Glade 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.) + +The files which Glade overwrites are: + + interface.h + interface.c + support.h + support.c + +(Though you may have named them differently in your project, if you changed +them in the Project Options dialog.) + +These files all have a warning at the top saying 'DO NOT EDIT'. + + +If you have added or updated any signal handlers, then these are appended to +the callbacks.h and callbacks.c 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. + + + +4.3 How do I add my own source files to the project? + +Add the source file (and any header file) to src/Makefile.am, in the +project1_SOURCES variable (where 'project1' is the name of your project). + +If you are using gettext, you may also want to add the source file to +po/POTFILES.in so that the strings can be translated. + + + +4.4 How do I add a library to the project? + +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.) + +autoconf provides macros such as AC_CHECK_HEADER and AC_CHECK_LIB which can +be used to check for general headers and libraries. + +Many GTK+ and Gnome libraries provide a config script such as gtk-config +which will output the CPPFLAGS and LIBS flags needed. + +For example, libxml provides an xml-config script which you can use like this: + + 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" + +NOTE: Make sure you place your configure.in test before the call to AC_OUTPUT. + + +4.5 How do I get a pointer to a widget from within a signal handler? + +If you have a pointer to any widget in a window, you can get a pointer to +any other widget in the window using the lookup_widget() function that Glade +provides (in support.c). + +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 lookup_widget(), e.g. + +void +on_button1_clicked (GtkButton *button, + gpointer user_data) +{ + GtkWidget *entry1; + + entry1 = lookup_widget (GTK_WIDGET (button), "entry1"); + + ... +} + + +Note that this does not work if you are using libglade. The corresponding +code for libglade would be: + +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"); + + ... +} + + +4.6 How do I get a pointer to a widget in another window? + +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. + +For more complicated applications you can use the gtk_object_set_data() and +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: + + dialog = create_dialog1 (); /* Call the function generated by Glade. */ + gtk_object_set_data (GTK_OBJECT (dialog), "main_window", main_window); + +Then when you need to access the main window from within the dialog code, +you can do this: + + main_window = gtk_object_get_data (GTK_OBJECT (dialog), "main_window"); + +NOTE: 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. + + +4.7 How do I get the value of a GtkOptionMenu? + +Call gtk_menu_get_active() with the GtkOptionMenu's menu to get the currently +selected menu item. You can use g_list_index() to find its index in the menu: + +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); +} + + +4.8 How do I get a GtkOptionMenu to call a function when it changes? + +Glade doesn't support this at present, but you can set it up manually. + +When you create the window, get the option menu and connect to the "deactivate" +signal emitted by its menu: + + 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); + + +Then add a handler to callbacks.c. You can get the index of the selected item +just like the previous answer: + +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); +} + + +4.9 How do I connect to GtkAdjustment signals? + +Glade doesn't support this at present, but you can set it up manually. + +When you create the window, get a pointer to the widget containing the +adjustment, and connect to the "changed" or "value_changed" signals: + + 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); + + +4.10 How do I add rows to a GtkCList before the window is shown? + +After you create the window, using the 'create' function generated by Glade, +use lookup_widget() to get a pointer to the GtkCList widget, and add the rows +as required. e.g. + + 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); + |