10.7. Paned Window Widgets

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).

To create a new paned window, call one of:
 
hpane = GtkHPaned()

vpane = GtkVPaned()

After creating the paned window widget, you need to add child widgets to its two halves. To do this, use the methods:
 
paned.add1(child)

paned.add2(child)

The add1() method adds the child widget to the left or top half of the paned window. The add2() method adds the child widget to the right or bottom half of the paned window.

A paned widget can be changed visually using the following two methods.
 
paned.set_handle_size(size)

paned.set_gutter_size(size)

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.

The paned.py example program creates 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 the realize() method, 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 SHRINK 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. Figure 10.6 shows the result of running the program:

Figure 10.6 Paned Example

The source code of the paned.py program is:
 
    1   #!/usr/bin/env python
    2   
    3   # example paned.py
    4   
    5   import gtk
    6   
    7   class PanedExample:
    8       # Create the list of "messages"
    9       def create_list(self):
   10           # Create a new scrolled window, with scrollbars only if needed
   11           scrolled_window = gtk.GtkScrolledWindow()
   12           scrolled_window.set_policy(gtk.POLICY_AUTOMATIC, gtk.POLICY_AUTOMATIC)
   13   
   14           # Create a new list and put it in the scrolled window
   15           list = gtk.GtkList()
   16           scrolled_window.add_with_viewport (list)
   17           list.show()
   18   
   19           # Add some messages to the window
   20           for i in range(10):
   21               buffer = "Message #%d" % i
   22               list_item = gtk.GtkListItem(buffer)
   23               list.add(list_item)
   24               list_item.show()
   25      
   26           return scrolled_window
   27      
   28       # Add some text to our text widget - this is a callback that is invoked
   29       # when our window is realized. We could also force our window to be
   30       # realized with gtk_widget_realize, but it would have to be part of a
   31       # hierarchy first
   32       def realize_text(self, text):
   33           text.freeze()
   34           text.insert(None, text.get_style().black, None,
   35                       "From: pathfinder@nasa.gov\n"
   36                       "To: mom@nasa.gov\n"
   37                       "Subject: Made it!\n"
   38                       "\n"
   39                       "We just got in this morning. The weather has been\n"
   40                       "great - clear but cold, and there are lots of fun sights.\n"
   41                       "Sojourner says hi. See you soon.\n"
   42                       " -Path\n")
   43           text.thaw()
   44      
   45       # Create a scrolled text area that displays a "message"
   46       def create_text(self):
   47           # Create a table to hold the text widget and scrollbars
   48           table = gtk.GtkTable(2, 2, gtk.FALSE)
   49   
   50           # Put a text widget in the upper left hand corner. Note the use of
   51           # SHRINK in the y direction
   52           text = gtk.GtkText()
   53           table.attach(text, 0, 1, 0, 1, gtk.FILL | gtk.EXPAND,
   54                        gtk.FILL | gtk.EXPAND | gtk.SHRINK, 0, 0)
   55           text.show()
   56      
   57           # Put a HScrollbar in the lower left hand corner
   58           hscrollbar = gtk.GtkHScrollbar(text.get_hadjustment())
   59           table.attach(hscrollbar, 0, 1, 1, 2,
   60                        gtk.EXPAND | gtk.FILL, gtk.FILL, 0, 0)
   61           hscrollbar.show()
   62   
   63           # And a VScrollbar in the upper right
   64           vscrollbar = gtk.GtkVScrollbar(text.get_vadjustment())
   65           table.attach(vscrollbar, 1, 2, 0, 1,
   66                        gtk.FILL, gtk.EXPAND | gtk.FILL | gtk.SHRINK, 0, 0)
   67           vscrollbar.show()
   68   
   69           # Add a handler to put a message in the text widget when it is realized
   70           text.connect("realize", self.realize_text)
   71   
   72           return table
   73      
   74       def __init__(self):
   75           window = gtk.GtkWindow(gtk.WINDOW_TOPLEVEL)
   76           window.set_title("Paned Windows")
   77           window.connect("destroy", gtk.mainquit)
   78           window.set_border_width(10)
   79           window.set_usize(450, 400)
   80   
   81           # create a vpaned widget and add it to our toplevel window
   82           vpaned = gtk.GtkVPaned()
   83           window.add(vpaned)
   84           vpaned.set_handle_size(10)
   85           vpaned.set_gutter_size(15)                       
   86           vpaned.show()
   87   
   88           # Now create the contents of the two halves of the window
   89           list = self.create_list()
   90           vpaned.add1(list)
   91           list.show()
   92   
   93           text = self.create_text()
   94           vpaned.add2(text)
   95           text.show()
   96           window.show()
   97   
   98   def main():
   99       gtk.mainloop()
  100       return 0
  101   
  102   if __name__ == "__main__":
  103       PanedExample()
  104       main()