diff --git a/docs/reference/gtk/getting_started.xml b/docs/reference/gtk/getting_started.xml index 7ebba53cac..3f8293c3e9 100644 --- a/docs/reference/gtk/getting_started.xml +++ b/docs/reference/gtk/getting_started.xml @@ -184,4 +184,54 @@ + + + Building UIs + + When construcing a more complicated interface, with dozens + or hundreds of widgets, doing all the setup work in C code is + cumbersome, and making changes becomes next to impossible. + + Thankfully, GTK+ supports the separation of user interface + layout from your business logic, by using UI descriptions in an + XML format that can be parsed by the #GtkBuilder class. + + + Packing buttons with GtkBuilder + + + FIXME: MISSING XINCLUDE CONTENT + + + The builder.ui file looks like this: + + + FIXME: MISSING XINCLUDE CONTENT + + + + + Note that GtkBuilder can also be used to construct objects + that are not widgets, such as tree models, adjustments, etc. + That is the reason the method we use here is called + gtk_builder_get_object() and returns a GObject* instead of a + GtkWidget*. + + Normally, you would pass a full path to + gtk_builder_add_From_file() to make the execution of your program + independent of the current directory. A common location to install + UI descriptions and similar data is + /usr/share/appname. + + + It is also possible to embed the UI description in the source + code as a string and use gtk_builder_add_from_string() to load it. + But keeping the UI description in a separate file has several + advantages: It is then possible to make minor adjustments to the UI + without recompiling your program, and, more importantly, graphical + UI editors such as glade + can load the file and allow you to create and modify your UI by + point-and-click. + + diff --git a/examples/Makefile.am b/examples/Makefile.am index 440197fd0e..25539e12ee 100644 --- a/examples/Makefile.am +++ b/examples/Makefile.am @@ -56,4 +56,7 @@ noinst_PROGRAMS = \ window-default \ bloatpad \ grid-packing \ - drawing + drawing \ + builder + +EXTRA_DIST = builder.ui diff --git a/examples/builder.c b/examples/builder.c new file mode 100644 index 0000000000..a05646fdbe --- /dev/null +++ b/examples/builder.c @@ -0,0 +1,40 @@ +#include + +static void +print_hello (GtkWidget *widget, + gpointer data) +{ + g_print ("Hello World\n"); +} + +int +main (int argc, + char *argv[]) +{ + GtkBuilder *builder; + GObject *window; + GObject *button; + + gtk_init (&argc, &argv); + + /* Construct a GtkBuilder instance and load our UI description */ + builder = gtk_builder_new (); + gtk_builder_add_from_file (builder, "builder.ui", NULL); + + /* Connect signal handlers to the constructed widgets. */ + window = gtk_builder_get_object (builder, "window"); + g_signal_connect (window, "destroy", G_CALLBACK (gtk_main_quit), NULL); + + button = gtk_builder_get_object (builder, "button1"); + g_signal_connect (button, "clicked", G_CALLBACK (print_hello), NULL); + + button = gtk_builder_get_object (builder, "button2"); + g_signal_connect (button, "clicked", G_CALLBACK (print_hello), NULL); + + button = gtk_builder_get_object (builder, "quit"); + g_signal_connect (button, "clicked", G_CALLBACK (gtk_main_quit), NULL); + + gtk_main (); + + return 0; +} diff --git a/examples/builder.ui b/examples/builder.ui new file mode 100644 index 0000000000..6321c93ca0 --- /dev/null +++ b/examples/builder.ui @@ -0,0 +1,45 @@ + + + True + Grid + 10 + + + True + + + True + Button 1 + + + 0 + 0 + + + + + True + Button 2 + + + 1 + 0 + + + + + True + Quit + + + 0 + 1 + 2 + + + + + + + +