3.7 Dividers and Decorations

If you need an occasional divider or decoration for widgets, GTK+ offers three:

GtkFrame is a container that draws a line around one enclosed widget. You can add an optional label to the frame. Frames can be useful, but don't overdo it. See Section 3.7.1.
GtkSeparator bars come in horizontal ( GtkHSeparator ) and vertical ( GtkVSeparator ) varieties. These typically divide two conceptually different parts of a window. See Section 3.7.2.
GtkArrow widgets display . . . (drum roll) arrows. See Section 3.7.3.

The following program shows off all three kinds of decorations; Figure 3.13 shows the final application.

Figure 3.13: Decorations.

Because the widgets in this program don't actually do anything, there are no special signal handlers.

 /* -*-coding: utf-8;-*- */ /* decorations.c -- various decoration widgets */ #include <gtk/gtk.h> gint delete_event(GtkWidget *widget, GdkEvent event, gpointer data) {   return FALSE; } void end_program(GtkWidget *widget, gpointer data) {   gtk_main_quit(); } int main(int argc, char **argv) {   GtkWindow *window;   GtkHBox *hbox[2];   GtkFrame *frame[5];   GtkArrow *arrow[4];   GtkVSeparator *v_sep[3];   GtkHSeparator *h_sep;   GtkVBox *vbox;   gint i;   /* initialize GTK+, create a window */   gtk_init(&argc, &argv);   window = g_object_new(GTK_TYPE_WINDOW,                         "title", "Decorations",                         "default-width", 500,                         "default-height", 200,                         "border-width", 12,                         NULL);   /* attach standard event handlers */   g_signal_connect(window, "delete_event", G_CALLBACK(delete_event), NULL);   g_signal_connect(window, "destroy", G_CALLBACK(end_program), NULL);

Creating widgets for all four arrow directions is a typing exercise. At least you can pack them automatically. Notice how there are vertical separators between the arrows.

 /* HBox with four arrows (different directions) */   hbox[0] = g_object_new(GTK_TYPE_HBOX, NULL);   arrow[0] = g_object_new(GTK_TYPE_ARROW, "arrow-type", GTK_ARROW_UP,    NULL);   arrow[1] = g_object_new(GTK_TYPE_ARROW, "arrow-type", GTK_ARROW_DOWN,  NULL);   arrow[2] = g_object_new(GTK_TYPE_ARROW, "arrow-type", GTK_ARROW_LEFT,  NULL);   arrow[3] = g_object_new(GTK_TYPE_ARROW, "arrow-type", GTK_ARROW_RIGHT, NULL);   /* pack the arrows into the hbox, put separators between */   for (i = 0; i < 4; i++)   {     gtk_box_pack_start_defaults(GTK_BOX(hbox[0]), GTK_WIDGET(arrow[i]));     if (i < 3)     {        v_sep[i] = g_object_new(GTK_TYPE_VSEPARATOR, NULL);        gtk_box_pack_start_defaults(GTK_BOX(hbox[0]), GTK_WIDGET(v_sep[i]));     }   }

Now it's time to show each frame style:

 /* create a frame and put the hbox above inside */   frame[0] = g_object_new(GTK_TYPE_FRAME, "label", "Arrows", NULL);   gtk_container_add(GTK_CONTAINER(frame[0]), GTK_WIDGET(hbox[0]));   /* create another hbox and put four more frames inside */   hbox[1] = g_object_new(GTK_TYPE_HBOX, "spacing", 5, NULL);   frame[1] = g_object_new(GTK_TYPE_FRAME,                           "shadow-type", GTK_SHADOW_IN,                           "label", "Shadowed In",                           "label-xalign", 0.0,                           NULL);   frame[2] = g_object_new(GTK_TYPE_FRAME,                           "shadow-type", GTK_SHADOW_OUT,                           "label", "Shadowed Out",                           "label-xalign", 0.5,                           NULL);   frame[3] = g_object_new(GTK_TYPE_FRAME,                           "shadow-type", GTK_SHADOW_ETCHED_IN,                           "label", "Etched Line",                           "label-xalign", 0.5,                           NULL);   frame[4] = g_object_new(GTK_TYPE_FRAME,                           "shadow-type", GTK_SHADOW_ETCHED_OUT,                           "label", "Embossed Line",                           "label-xalign", 1.0,                           NULL);   /* pack the frames into the hbox */   for (i = 1; i < 5; i++)   {     gtk_box_pack_start_defaults(GTK_BOX(hbox[1]), GTK_WIDGET(frame[i]));   }

With the frames out of the way, it's time to wrap things up by putting both HBoxes inside a VBox, with a GtkHSeparator object between:

 /* create a vbox, put both hboxes inside with a separator */   vbox = g_object_new(GTK_TYPE_VBOX, NULL);   gtk_box_pack_start_defaults(GTK_BOX(vbox), GTK_WIDGET(frame[0]));   h_sep = g_object_new(GTK_TYPE_HSEPARATOR, NULL);   gtk_box_pack_start_defaults(GTK_BOX(vbox), GTK_WIDGET(h_sep));   /* put everything inside the window, show window, start loop */   gtk_box_pack_start_defaults(GTK_BOX(vbox), GTK_WIDGET(hbox[1]));   gtk_container_add(GTK_CONTAINER(window), GTK_WIDGET(vbox));   gtk_widget_show_all(GTK_WIDGET(window));   gtk_main();   return 0; }

3.7.1 Frames

A frame ( GtkFrame , GTK_TYPE_FRAME ) is a decorated container for exactly one widget. When you create a frame, the following properties are at your disposal:

label ( gchararray ): A label for the top of the frame.
label-widget ( GtkWidget ): If you want to use an arbitrary widget instead of text for the label, assign this property to the widget. Don't put any user -adjustable widgets in the label ” that sort of thing is likely to get you dragged off by the user interface police.
label-xalign ( gfloat ): The label's relative position in the top of the frame; 0.0 tells the label to go all the way to the left, 0.5 to the center, and 1.0 to the right end.
shadow-type ( GtkShadowType ): How GTK+ should draw the frame line. Possible values are
- GTK_SHADOW_IN : Draw so that the contents of the frame appear to be in a depression.
- GTK_SHADOW_OUT : Draw so that the contents of the frame appear elevated.
- GTK_SHADOW_ETCHED_IN : Draw what appears to be a line etched around the contents.
- GTK_SHADOW_ETCHED_OUT : Draw what appears to be an embossed (elevated) line around the contents.
- GTK_SHADOW_NONE : Don't display a line.

Note

As mentioned many times before, try to exercise control when you employ frames. If you need to group widgets with frames, make sure that you do so with all of the widget groups, with a consistent frame style.

If you want to annoy the user, put frames inside other frames. (Seriously, consider some other container, such as a notebook. You could also try to make all widget group sizes equal.)

3.7.2 Separators

The two separator subclasses, GtkHSeparator ( GTK_TYPE_HSEPARATOR ) and GtkVSeparator ( GTK_TYPE_VSEPARATOR ), do not have properties, methods , or signals of their own.

Note	Separators have an etched look and therefore fit best with frames using the GTK_SHADOW_ETCHED_IN style.

3.7.3 Arrows

GtkArrow ( GTK_TYPE_ARROW ) widgets are almost as simple as separators, but they have an arrow-type property to indicate a direction. The possible values are GTK_ARROW_UP , GTK_ARROW_DOWN , GTK_ARROW_LEFT , and GTK_ARROW_RIGHT . You should set this property only when you create the widget.