gtk_tut-10.html

GTK development guide

</CODE></BLOCKQUOTE>
<P>The position of the label can be changed using this function:
<P>
<BLOCKQUOTE><CODE>
<PRE>
void gtk_frame_set_label_align( GtkFrame *frame,
                                gfloat    xalign,
                                gfloat    yalign );
</PRE>
</CODE></BLOCKQUOTE>
<P><CODE>xalign</CODE> and <CODE>yalign</CODE> take values between 0.0 and 1.0. <CODE>xalign</CODE>
indicates the position of the label along the top horizontal of the
frame. <CODE>yalign</CODE> is not currently used. The default value of xalign
is 0.0 which places the label at the left hand end of the frame.
<P>The next function alters the style of the box that is used to outline
the frame.
<P>
<BLOCKQUOTE><CODE>
<PRE>
void gtk_frame_set_shadow_type( GtkFrame      *frame,
                                GtkShadowType  type);
</PRE>
</CODE></BLOCKQUOTE>
<P>The <CODE>type</CODE> argument can take one of the following values:
<BLOCKQUOTE><CODE>
<PRE>
  GTK_SHADOW_NONE
  GTK_SHADOW_IN
  GTK_SHADOW_OUT
  GTK_SHADOW_ETCHED_IN (the default)
  GTK_SHADOW_ETCHED_OUT
</PRE>
</CODE></BLOCKQUOTE>
<P>The following code example illustrates the use of the Frame widget.
<P>
<BLOCKQUOTE><CODE>
<PRE>
/* example-start frame frame.c */

#include &lt;gtk/gtk.h>

int main( int   argc,
          char *argv[] )
{
  /* GtkWidget is the storage type for widgets */
  GtkWidget *window;
  GtkWidget *frame;
  GtkWidget *button;
  gint i;

  /* Initialise GTK */
  gtk_init(&amp;argc, &amp;argv);
    
  /* Create a new window */
  window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
  gtk_window_set_title(GTK_WINDOW(window), "Frame Example");

  /* Here we connect the "destroy" event to a signal handler */ 
  gtk_signal_connect (GTK_OBJECT (window), "destroy",
                      GTK_SIGNAL_FUNC (gtk_main_quit), NULL);

  gtk_widget_set_usize(window, 300, 300);
  /* Sets the border width of the window. */
  gtk_container_set_border_width (GTK_CONTAINER (window), 10);

  /* Create a Frame */
  frame = gtk_frame_new(NULL);
  gtk_container_add(GTK_CONTAINER(window), frame);

  /* Set the frame's label */
  gtk_frame_set_label( GTK_FRAME(frame), "GTK Frame Widget" );

  /* Align the label at the right of the frame */
  gtk_frame_set_label_align( GTK_FRAME(frame), 1.0, 0.0);

  /* Set the style of the frame */
  gtk_frame_set_shadow_type( GTK_FRAME(frame), GTK_SHADOW_ETCHED_OUT);

  gtk_widget_show(frame);
  
  /* Display the window */
  gtk_widget_show (window);
    
  /* Enter the event loop */
  gtk_main ();
    
  return(0);
}
/* example-end */
</PRE>
</CODE></BLOCKQUOTE>
<P>   
<H2><A NAME="ss10.6">10.6 Aspect Frames</A>
</H2>

<P>The aspect frame widget is like a frame widget, except that it also
enforces the aspect ratio (that is, the ratio of the width to the
height) of the child widget to have a certain value, adding extra
space if necessary. This is useful, for instance, if you want to
preview a larger image. The size of the preview should vary when the
user resizes the window, but the aspect ratio needs to always match
the original image.
<P>To create a new aspect frame use:
<P>
<BLOCKQUOTE><CODE>
<PRE>
GtkWidget *gtk_aspect_frame_new( const gchar *label,
                                 gfloat       xalign,
                                 gfloat       yalign,
                                 gfloat       ratio,
                                 gint         obey_child);
</PRE>
</CODE></BLOCKQUOTE>
<P><CODE>xalign</CODE> and <CODE>yalign</CODE> specify alignment as with Alignment
widgets. If <CODE>obey_child</CODE> is true, the aspect ratio of a child
widget will match the aspect ratio of the ideal size it requests.
Otherwise, it is given by <CODE>ratio</CODE>.
<P>To change the options of an existing aspect frame, you can use:
<P>
<BLOCKQUOTE><CODE>
<PRE>
void gtk_aspect_frame_set( GtkAspectFrame *aspect_frame,
                           gfloat          xalign,
                           gfloat          yalign,
                           gfloat          ratio,
                           gint            obey_child);
</PRE>
</CODE></BLOCKQUOTE>
<P>As an example, the following program uses an AspectFrame to present a
drawing area whose aspect ratio will always be 2:1, no matter how the
user resizes the top-level window.
<P>
<BLOCKQUOTE><CODE>
<PRE>
/* example-start aspectframe aspectframe.c */

#include &lt;gtk/gtk.h>
   
int main( int argc,
          char *argv[] )
{
    GtkWidget *window;
    GtkWidget *aspect_frame;
    GtkWidget *drawing_area;
    gtk_init (&amp;argc, &amp;argv);
   
    window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
    gtk_window_set_title (GTK_WINDOW (window), "Aspect Frame");
    gtk_signal_connect (GTK_OBJECT (window), "destroy",
                        GTK_SIGNAL_FUNC (gtk_main_quit), NULL);
    gtk_container_set_border_width (GTK_CONTAINER (window), 10);
   
    /* Create an aspect_frame and add it to our toplevel window */
   
    aspect_frame = gtk_aspect_frame_new ("2x1", /* label */
                                         0.5, /* center x */
                                         0.5, /* center y */
                                         2, /* xsize/ysize = 2 */
                                         FALSE /* ignore child's aspect */);
   
    gtk_container_add (GTK_CONTAINER(window), aspect_frame);
    gtk_widget_show (aspect_frame);
   
    /* Now add a child widget to the aspect frame */
   
    drawing_area = gtk_drawing_area_new ();
   
    /* Ask for a 200x200 window, but the AspectFrame will give us a 200x100
     * window since we are forcing a 2x1 aspect ratio */
    gtk_widget_set_usize (drawing_area, 200, 200);
    gtk_container_add (GTK_CONTAINER(aspect_frame), drawing_area);
    gtk_widget_show (drawing_area);
   
    gtk_widget_show (window);
    gtk_main ();
    return 0;
}
/* example-end */
</PRE>
</CODE></BLOCKQUOTE>
<P>   
<H2><A NAME="ss10.7">10.7 Paned Window Widgets</A>
</H2>

<P>The paned window widgets are useful when you want to divide an area
into two parts, with the relative size of the two parts controlled by
the user. A groove is drawn between the two portions with a handle
that the user can drag to change the ratio. The division can either be
horizontal (HPaned) or vertical (VPaned).
<P>To create a new paned window, call one of:
<P>
<BLOCKQUOTE><CODE>
<PRE>
GtkWidget *gtk_hpaned_new (void);

GtkWidget *gtk_vpaned_new (void);
</PRE>
</CODE></BLOCKQUOTE>
<P>After creating the paned window widget, you need to add child widgets
to its two halves. To do this, use the functions:
<P>
<BLOCKQUOTE><CODE>
<PRE>
void gtk_paned_add1 (GtkPaned *paned, GtkWidget *child);

void gtk_paned_add2 (GtkPaned *paned, GtkWidget *child);
</PRE>
</CODE></BLOCKQUOTE>
<P><CODE>gtk_paned_add1()</CODE> adds the child widget to the left or top half of
the paned window. <CODE>gtk_paned_add2()</CODE> adds the child widget to the
right or bottom half of the paned window.
<P>A paned widget can be changed visually using the following two
functions.
<P>
<BLOCKQUOTE><CODE>
<PRE>
void gtk_paned_set_handle_size( GtkPaned *paned,
                                guint16   size);

void gtk_paned_set_gutter_size( GtkPaned *paned,
                                guint16   size);
</PRE>
</CODE></BLOCKQUOTE>
<P>The first of these sets the size of the handle and the second sets the
size of the gutter that is between the two parts of the paned window.
<P>As an example, we will create part of the user interface of an
imaginary email program. A window is divided into two portions
vertically, with the top portion being a list of email messages and
the bottom portion the text of the email message. Most of the program
is pretty straightforward. A couple of points to note: text can't be
added to a Text widget until it is realized. This could be done by
calling <CODE>gtk_widget_realize()</CODE>, but as a demonstration of an
alternate technique, we connect a handler to the "realize" signal to
add the text. Also, we need to add the <CODE>GTK_SHRINK</CODE> option to some
of the items in the table containing the text window and its
scrollbars, so that when the bottom portion is made smaller, the
correct portions shrink instead of being pushed off the bottom of the
window.
<P>
<BLOCKQUOTE><CODE>
<PRE>
/* example-start paned paned.c */

#include &lt;stdio.h>
#include &lt;gtk/gtk.h>
   
/* Create the list of "messages" */
GtkWidget *create_list( void )
{

    GtkWidget *scrolled_window;
    GtkWidget *list;
    GtkWidget *list_item;
   
    int i;
    char buffer[16];
   
    /* Create a new scrolled window, with scrollbars only if needed */
    scrolled_window = gtk_scrolled_window_new (NULL, NULL);
    gtk_scrolled_window_set_policy (GTK_SCROLLED_WINDOW (scrolled_window),
                                    GTK_POLICY_AUTOMATIC, 
                                    GTK_POLICY_AUTOMATIC);
   
    /* Create a new list and put it in the scrolled window */
    list = gtk_list_new ();
    gtk_scrolled_window_add_with_viewport (
               GTK_SCROLLED_WINDOW (scrolled_window), list);
    gtk_widget_show (list);
   
    /* Add some messages to the window */
    for (i=0; i&lt;10; i++) {

        sprintf(buffer,"Message #%d",i);
        list_item = gtk_list_item_new_with_label (buffer);
        gtk_container_add (GTK_CONTAINER(list), list_item);
        gtk_widget_show (list_item);

    }
   
    return scrolled_window;
}
   
/* Add some text to our text widget - this is a callback that is invoked
when our window is realized. We could also force our window to be
realized with gtk_widget_realize, but it would have to be part of
a hierarchy first */

void realize_text( GtkWidget *text,
                   gpointer data )
{
    gtk_text_freeze (GTK_TEXT (text));
    gtk_text_insert (GTK_TEXT (text), NULL, &amp;text->style->black, NULL,
    "From: [e-mail]\n"
    "To: [e-mail]\n"
    "Subject: Made it!\n"
    "\n"
    "We just got in this morning. The weather has been\n"
    "great - clear but cold, and there are lots of fun sights.\n"
    "Sojourner says hi. See you soon.\n"
    " -Path\n", -1);
   
    gtk_text_thaw (GTK_TEXT (text));
}
   
/* Create a scrolled text area that displays a "message" */
GtkWidget *create_text( void )
{
    GtkWidget *table;
    GtkWidget *text;
    GtkWidget *hscrollbar;
    GtkWidget *vscrollbar;
   
    /* Create a table to hold the text widget and scrollbars */
    table = gtk_table_new (2, 2, FALSE);
   
    /* Put a text widget in the upper left hand corner. Note the use of
     * GTK_SHRINK in the y direction */
    text = gtk_text_new (NULL, NULL);
    gtk_table_attach (GTK_TABLE (table), text, 0, 1, 0, 1,
                      GTK_FILL | GTK_EXPAND,
                      GTK_FILL | GTK_EXPAND | GTK_SHRINK, 0, 0);
    gtk_widget_show (text);
   
    /* Put a HScrollbar in the lower left hand corner */
    hscrollbar = gtk_hscrollbar_new (GTK_TEXT (text)->hadj);
    gtk_table_attach (GTK_TABLE (table), hscrollbar, 0, 1, 1, 2,
                      GTK_EXPAND | GTK_FILL, GTK_FILL, 0, 0);
    gtk_widget_show (hscrollbar);
   
    /* And a VScrollbar in the upper right */
    vscrollbar = gtk_vscrollbar_new (GTK_TEXT (text)->vadj);
    gtk_table_attach (GTK_TABLE (table), vscrollbar, 1, 2, 0, 1,
                      GTK_FILL, GTK_EXPAND | GTK_FILL | GTK_SHRINK, 0, 0);
    gtk_widget_show (vscrollbar);
   
    /* Add a handler to put a message in the text widget when it is realized */
    gtk_signal_connect (GTK_OBJECT (text), "realize",
                        GTK_SIGNAL_FUNC (realize_text), NULL);
   
    return table;
}
   
int main( int   argc,
          char *argv[] )
{
    GtkWidget *window;
    GtkWidget *vpaned;
    GtkWidget *list;
    GtkWidget *text;

    gtk_init (&amp;argc, &amp;argv);
   
    window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
    gtk_window_set_title (GTK_WINDOW (window), "Paned Windows");
    gtk_signal_connect (GTK_OBJECT (window), "destroy",
                        GTK_SIGNAL_FUNC (gtk_main_quit), NULL);
    gtk_container_set_border_width (GTK_CONTAINER (window), 10);
    gtk_widget_set_usize (GTK_WIDGET(window), 450, 400);

    /* create a vpaned widget and add it to our toplevel window */
   
    vpaned = gtk_vpaned_new ();
    gtk_container_add (GTK_CONTAINER(window), vpaned);
    gtk_paned_set_handle_size (GTK_PANED(vpaned),
                               10);
    gtk_paned_set_gutter_size (GTK_PANED(vpaned),