gtk_tut-10.html

GTK development guide

                               15);                       
    gtk_widget_show (vpaned);
   
    /* Now create the contents of the two halves of the window */
   
    list = create_list ();
    gtk_paned_add1 (GTK_PANED(vpaned), list);
    gtk_widget_show (list);
   
    text = create_text ();
    gtk_paned_add2 (GTK_PANED(vpaned), text);
    gtk_widget_show (text);
    gtk_widget_show (window);
    gtk_main ();
    return 0;
}
/* example-end */
</PRE>
</CODE></BLOCKQUOTE>
<P>
<H2><A NAME="sec_Viewports"></A> <A NAME="ss10.8">10.8 Viewports </A>
</H2>

<P>It is unlikely that you will ever need to use the Viewport widget
directly. You are much more likely to use the
<A HREF="#sec_ScrolledWindow">Scrolled Window</A> widget which
itself uses the Viewport.
<P>A viewport widget allows you to place a larger widget within it such
that you can view a part of it at a time. It uses
<A HREF="gtk_tut-7.html#sec_Adjustment">Adjustments</A> to define the area that
is currently in view.
<P>A Viewport is created with the function
<P>
<BLOCKQUOTE><CODE>
<PRE>
GtkWidget *gtk_viewport_new( GtkAdjustment *hadjustment,
                             GtkAdjustment *vadjustment );
</PRE>
</CODE></BLOCKQUOTE>
<P>As you can see you can specify the horizontal and vertical Adjustments
that the widget is to use when you create the widget. It will create
its own if you pass NULL as the value of the arguments.
<P>You can get and set the adjustments after the widget has been created
using the following four functions:
<P>
<BLOCKQUOTE><CODE>
<PRE>
GtkAdjustment *gtk_viewport_get_hadjustment (GtkViewport *viewport );

GtkAdjustment *gtk_viewport_get_vadjustment (GtkViewport *viewport );

void gtk_viewport_set_hadjustment( GtkViewport   *viewport,
                                   GtkAdjustment *adjustment );

void gtk_viewport_set_vadjustment( GtkViewport   *viewport,
                                   GtkAdjustment *adjustment );
</PRE>
</CODE></BLOCKQUOTE>
<P>The only other viewport function is used to alter its appearance:
<P>
<BLOCKQUOTE><CODE>
<PRE>
void gtk_viewport_set_shadow_type( GtkViewport   *viewport,
                                   GtkShadowType  type );
</PRE>
</CODE></BLOCKQUOTE>
<P>Possible values for the <CODE>type</CODE> parameter are:
<BLOCKQUOTE><CODE>
<PRE>
  GTK_SHADOW_NONE,
  GTK_SHADOW_IN,
  GTK_SHADOW_OUT,
  GTK_SHADOW_ETCHED_IN,
  GTK_SHADOW_ETCHED_OUT
</PRE>
</CODE></BLOCKQUOTE>
<P>
<H2><A NAME="sec_ScrolledWindow"></A> <A NAME="ss10.9">10.9 Scrolled Windows </A>
</H2>

<P>Scrolled windows are used to create a scrollable area with another
widget inside it. You may insert any type of widget into a scrolled
window, and it will be accessible regardless of the size by using the
scrollbars.
<P>The following function is used to create a new scrolled window.
<P>
<BLOCKQUOTE><CODE>
<PRE>
GtkWidget *gtk_scrolled_window_new( GtkAdjustment *hadjustment,
                                    GtkAdjustment *vadjustment );
</PRE>
</CODE></BLOCKQUOTE>
<P>Where the first argument is the adjustment for the horizontal
direction, and the second, the adjustment for the vertical direction.
These are almost always set to NULL.
<P>
<BLOCKQUOTE><CODE>
<PRE>
void gtk_scrolled_window_set_policy( GtkScrolledWindow *scrolled_window,
                                     GtkPolicyType      hscrollbar_policy,
                                     GtkPolicyType      vscrollbar_policy );
</PRE>
</CODE></BLOCKQUOTE>
<P>This sets the policy to be used with respect to the scrollbars.
The first argument is the scrolled window you wish to change. The second
sets the policy for the horizontal scrollbar, and the third the policy for 
the vertical scrollbar.
<P>The policy may be one of <CODE>GTK_POLICY_AUTOMATIC</CODE> or
<CODE>GTK_POLICY_ALWAYS</CODE>. <CODE>GTK_POLICY_AUTOMATIC</CODE> will automatically
decide whether you need scrollbars, whereas <CODE>GTK_POLICY_ALWAYS</CODE>
will always leave the scrollbars there.
<P>You can then place your object into the scrolled window using the
following function.
<P>
<BLOCKQUOTE><CODE>
<PRE>
void gtk_scrolled_window_add_with_viewport( GtkScrolledWindow *scrolled_window,
                                            GtkWidget         *child);
</PRE>
</CODE></BLOCKQUOTE>
<P>Here is a simple example that packs a table eith 100 toggle buttons
into a scrolled window. I've only commented on the parts that may be
new to you.
<P>
<BLOCKQUOTE><CODE>
<PRE>
/* example-start scrolledwin scrolledwin.c */

#include &lt;stdio.h>
#include &lt;gtk/gtk.h>

void destroy( GtkWidget *widget,
              gpointer   data )
{
    gtk_main_quit();
}

int main( int   argc,
          char *argv[] )
{
    static GtkWidget *window;
    GtkWidget *scrolled_window;
    GtkWidget *table;
    GtkWidget *button;
    char buffer[32];
    int i, j;
    
    gtk_init (&amp;argc, &amp;argv);
    
    /* Create a new dialog window for the scrolled window to be
     * packed into.  */
    window = gtk_dialog_new ();
    gtk_signal_connect (GTK_OBJECT (window), "destroy",
                        (GtkSignalFunc) destroy, NULL);
    gtk_window_set_title (GTK_WINDOW (window), "GtkScrolledWindow example");
    gtk_container_set_border_width (GTK_CONTAINER (window), 0);
    gtk_widget_set_usize(window, 300, 300);
    
    /* create a new scrolled window. */
    scrolled_window = gtk_scrolled_window_new (NULL, NULL);
    
    gtk_container_set_border_width (GTK_CONTAINER (scrolled_window), 10);
    
    /* the policy is one of GTK_POLICY AUTOMATIC, or GTK_POLICY_ALWAYS.
     * GTK_POLICY_AUTOMATIC will automatically decide whether you need
     * scrollbars, whereas GTK_POLICY_ALWAYS will always leave the scrollbars
     * there.  The first one is the horizontal scrollbar, the second, 
     * the vertical. */
    gtk_scrolled_window_set_policy (GTK_SCROLLED_WINDOW (scrolled_window),
                                    GTK_POLICY_AUTOMATIC, GTK_POLICY_ALWAYS);
    /* The dialog window is created with a vbox packed into it. */                                                              
    gtk_box_pack_start (GTK_BOX (GTK_DIALOG(window)->vbox), scrolled_window, 
                        TRUE, TRUE, 0);
    gtk_widget_show (scrolled_window);
    
    /* create a table of 10 by 10 squares. */
    table = gtk_table_new (10, 10, FALSE);
    
    /* set the spacing to 10 on x and 10 on y */
    gtk_table_set_row_spacings (GTK_TABLE (table), 10);
    gtk_table_set_col_spacings (GTK_TABLE (table), 10);
    
    /* pack the table into the scrolled window */
    gtk_scrolled_window_add_with_viewport (
                   GTK_SCROLLED_WINDOW (scrolled_window), table);
    gtk_widget_show (table);
    
    /* this simply creates a grid of toggle buttons on the table
     * to demonstrate the scrolled window. */
    for (i = 0; i &lt; 10; i++)
       for (j = 0; j &lt; 10; j++) {
          sprintf (buffer, "button (%d,%d)\n", i, j);
          button = gtk_toggle_button_new_with_label (buffer);
          gtk_table_attach_defaults (GTK_TABLE (table), button,
                                     i, i+1, j, j+1);
          gtk_widget_show (button);
       }
    
    /* Add a "close" button to the bottom of the dialog */
    button = gtk_button_new_with_label ("close");
    gtk_signal_connect_object (GTK_OBJECT (button), "clicked",
                               (GtkSignalFunc) gtk_widget_destroy,
                               GTK_OBJECT (window));
    
    /* this makes it so the button is the default. */
    
    GTK_WIDGET_SET_FLAGS (button, GTK_CAN_DEFAULT);
    gtk_box_pack_start (GTK_BOX (GTK_DIALOG (window)->action_area), button, TRUE, TRUE, 0);
    
    /* This grabs this button to be the default button. Simply hitting
     * the "Enter" key will cause this button to activate. */
    gtk_widget_grab_default (button);
    gtk_widget_show (button);
    
    gtk_widget_show (window);
    
    gtk_main();
    
    return(0);
}
/* example-end */
</PRE>
</CODE></BLOCKQUOTE>
<P>Try playing with resizing the window. You'll notice how the scrollbars
react. You may also wish to use the gtk_widget_set_usize() call to set
the default size of the window or other widgets.
<P>   
<H2><A NAME="ss10.10">10.10 Button Boxes</A>
</H2>

<P>Button Boxes are a convenient way to quickly layout a group of
buttons. They come in both horizontal and vertical flavours. You
create a new Button Box with one of the following calls, which create
a horizontal or vertical box, respectively:
<P>
<BLOCKQUOTE><CODE>
<PRE>
GtkWidget *gtk_hbutton_box_new( void );

GtkWidget *gtk_vbutton_box_new( void );
</PRE>
</CODE></BLOCKQUOTE>
<P>The only attributes pertaining to button boxes effect how the buttons
are laid out. You can change the spacing between the buttons with:
<P>
<BLOCKQUOTE><CODE>
<PRE>
void gtk_hbutton_box_set_spacing_default( gint spacing );

void gtk_vbutton_box_set_spacing_default( gint spacing );
</PRE>
</CODE></BLOCKQUOTE>
<P>Similarly, the current spacing values can be queried using:
<P>
<BLOCKQUOTE><CODE>
<PRE>
gint gtk_hbutton_box_get_spacing_default( void );

gint gtk_vbutton_box_get_spacing_default( void );
</PRE>
</CODE></BLOCKQUOTE>
<P>The second attribute that we can access effects the layout of the
buttons within the box. It is set using one of:
<P>
<BLOCKQUOTE><CODE>
<PRE>
void gtk_hbutton_box_set_layout_default( GtkButtonBoxStyle layout );

void gtk_vbutton_box_set_layout_default( GtkButtonBoxStyle layout );
</PRE>
</CODE></BLOCKQUOTE>
<P>The <CODE>layout</CODE> argument can take one of the following values:
<P>
<BLOCKQUOTE><CODE>
<PRE>
  GTK_BUTTONBOX_DEFAULT_STYLE
  GTK_BUTTONBOX_SPREAD
  GTK_BUTTONBOX_EDGE
  GTK_BUTTONBOX_START
  GTK_BUTTONBOX_END
</PRE>
</CODE></BLOCKQUOTE>
<P>The current layout setting can be retrieved using:
<P>
<BLOCKQUOTE><CODE>
<PRE>
GtkButtonBoxStyle gtk_hbutton_box_get_layout_default( void );

GtkButtonBoxStyle gtk_vbutton_box_get_layout_default( void );
</PRE>
</CODE></BLOCKQUOTE>
<P>Buttons are added to a Button Box using the usual function:
<P>
<BLOCKQUOTE><CODE>
<PRE>
    gtk_container_add( GTK_CONTAINER(button_box), child_widget );
</PRE>
</CODE></BLOCKQUOTE>
<P>Here's an example that illustrates all the different layout settings
for Button Boxes.
<P>
<BLOCKQUOTE><CODE>
<PRE>
/* example-start buttonbox buttonbox.c */

#include &lt;gtk/gtk.h>

/* Create a Button Box with the specified parameters */
GtkWidget *create_bbox( gint  horizontal,
                        char *title,
                        gint  spacing,
                        gint  child_w,
                        gint  child_h,
                        gint  layout )
{
  GtkWidget *frame;
  GtkWidget *bbox;
  GtkWidget *button;

  frame = gtk_frame_new (title);

  if (horizontal)
    bbox = gtk_hbutton_box_new ();
  else
    bbox = gtk_vbutton_box_new ();

  gtk_container_set_border_width (GTK_CONTAINER (bbox), 5);
  gtk_container_add (GTK_CONTAINER (frame), bbox);

  /* Set the appearance of the Button Box */
  gtk_button_box_set_layout (GTK_BUTTON_BOX (bbox), layout);
  gtk_button_box_set_spacing (GTK_BUTTON_BOX (bbox), spacing);
  gtk_button_box_set_child_size (GTK_BUTTON_BOX (bbox), child_w, child_h);

  button = gtk_button_new_with_label ("OK");
  gtk_container_add (GTK_CONTAINER (bbox), button);

  button = gtk_button_new_with_label ("Cancel");
  gtk_container_add (GTK_CONTAINER (bbox), button);

  button = gtk_button_new_with_label ("Help");
  gtk_container_add (GTK_CONTAINER (bbox), button);

  return(frame);
}

int main( int   argc,
          char *argv[] )
{
  static GtkWidget* window = NULL;
  GtkWidget *main_vbox;
  GtkWidget *vbox;
  GtkWidget *hbox;
  GtkWidget *frame_horz;
  GtkWidget *frame_vert;

  /* Initialize GTK */
  gtk_init( &amp;argc, &amp;argv );

  window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
  gtk_window_set_title (GTK_WINDOW (window), "Button Boxes");

  gtk_signal_connect (GTK_OBJECT (window), "destroy",
                      GTK_SIGNAL_FUNC(gtk_main_quit),
                      NULL);