10.9. Scrolled Windows

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.

The following function is used to create a new scrolled window.
 
scrolled_window = GtkScrolledWindow(hadjustment, vadjustment)

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 None or not specified.
 
scrolled_window.set_policy(hscrollbar_policy, vscrollbar_policy)

This method sets the policy to be used with respect to the scrollbars. The first argument sets the policy for the horizontal scrollbar, and the second, the policy for the vertical scrollbar.

The policy may be one of POLICY_AUTOMATIC or POLICY_ALWAYS. POLICY_AUTOMATIC will automatically decide whether you need scrollbars, whereas POLICY_ALWAYS will always leave the scrollbars there.

You can then place your object into the scrolled window using the following method.
 
scrolled_window.add_with_viewport(child)

The scrolledwin.py example program packs a table with 100 toggle buttons into a scrolled window. I've only commented on the parts that may be new to you. Figure 10.7 illustrates the program display:

Figure 10.7 Scrolled Window Example

The source code for the scrolledwin.py program is:
 
    1   #!/usr/bin/env python
    2   
    3   # example scrolledwin.py
    4   
    5   import gtk
    6   
    7   class ScrolledWindowExample:
    8       def destroy(self, widget):
    9           gtk.mainquit()
   10   
   11       def __init__(self):
   12           # Create a new dialog window for the scrolled window to be
   13           # packed into. 
   14           window = gtk.GtkDialog()
   15           window.connect("destroy", self.destroy)
   16           window.set_title("GtkScrolledWindow example")
   17           window.set_border_width(0)
   18           window.set_usize(300, 300)
   19   
   20           # create a new scrolled window.
   21           scrolled_window = gtk.GtkScrolledWindow()
   22           scrolled_window.set_border_width(10)
   23   
   24           # the policy is one of POLICY AUTOMATIC, or POLICY_ALWAYS.
   25           # POLICY_AUTOMATIC will automatically decide whether you need
   26           # scrollbars, whereas POLICY_ALWAYS will always leave the scrollbars
   27           # there. The first one is the horizontal scrollbar, the second, the
   28           # vertical.
   29           scrolled_window.set_policy(gtk.POLICY_AUTOMATIC, gtk.POLICY_ALWAYS)
   30   
   31           # The dialog window is created with a vbox packed into it.
   32           window.vbox.pack_start(scrolled_window, gtk.TRUE, gtk.TRUE, 0)
   33           scrolled_window.show()
   34       
   35           # create a table of 10 by 10 squares.
   36           table = gtk.GtkTable(10, 10, gtk.FALSE)
   37   
   38           # set the spacing to 10 on x and 10 on y
   39           table.set_row_spacings(10)
   40           table.set_col_spacings(10)
   41   
   42           # pack the table into the scrolled window
   43           scrolled_window.add_with_viewport(table)
   44           table.show()
   45   
   46           # this simply creates a grid of toggle buttons on the table
   47           # to demonstrate the scrolled window.
   48           for i in range(10):
   49               for j in range(10):
   50                   buffer = "button (%d,%d)" % (i, j)
   51                   button = gtk.GtkToggleButton(buffer)
   52                   table.attach(button, i, i+1, j, j+1)
   53                   button.show()
   54   
   55           # Add a "close" button to the bottom of the dialog
   56           button = gtk.GtkButton("close")
   57           button.connect_object("clicked", self.destroy, window)
   58   
   59           # this makes it so the button is the default.
   60           button.set_flags(gtk.CAN_DEFAULT)
   61           window.action_area.pack_start( button, gtk.TRUE, gtk.TRUE, 0)
   62   
   63           # This grabs this button to be the default button. Simply hitting
   64           # the "Enter" key will cause this button to activate.
   65           button.grab_default()
   66           button.show()
   67           window.show()
   68   
   69   def main():
   70       gtk.mainloop()
   71       return 0
   72   
   73   if __name__ == "__main__":
   74       ScrolledWindowExample()
   75       main()

Try resizing the window. You'll notice how the scrollbars react. You may also wish to use the set_usize() method to set the default size of the window or other widgets.