10.5. Frames

Frames can be used to enclose one or a group of widgets with a box which can optionally be labelled. The position of the label and the style of the box can be altered to suit.

A Frame can be created with the following function:
 
frame = GtkFrame(label)

The label is by default placed in the upper left hand corner of the frame. Specifying a value of None for the label argument or specifying no label argument will result in no label being displayed. The text of the label can be changed using the method.
 
frame.set_label(label)

The position of the label can be changed using this method:
 
frame.set_label_align(xalign, yalign)

xalign and yalign take values between 0.0 and 1.0. xalign indicates the position of the label along the top horizontal of the frame. yalign is not currently used. The default value of xalign is 0.0 which places the label at the left hand end of the frame.

The next method alters the style of the box that is used to outline the frame.
 
frame.set_shadow_type(type)

The type argument can take one of the following values:
 
  SHADOW_NONE
  SHADOW_IN
  SHADOW_OUT
  SHADOW_ETCHED_IN      # the default
  SHADOW_ETCHED_OUT

The frame.py example illustrates the use of the Frame widget. Figure 10.4 shows the resulting display:

Figure 10.4 Frame Example

The source code of frame.py is:
 
    1   #!/usr/bin/env python
    2   
    3   # example frame.py
    4   
    5   import gtk
    6   
    7   class FrameExample:
    8       def __init__(self):
    9           # Create a new window
   10           window = gtk.GtkWindow(gtk.WINDOW_TOPLEVEL)
   11           window.set_title("Frame Example")
   12   
   13           # Here we connect the "destroy" event to a signal handler 
   14           window.connect("destroy", gtk.mainquit)
   15           window.set_usize(300, 300)
   16   
   17           # Sets the border width of the window.
   18           window.set_border_width(10)
   19   
   20           # Create a Frame
   21           frame = gtk.GtkFrame()
   22           window.add(frame)
   23   
   24           # Set the frame's label
   25           frame.set_label("GTK Frame Widget")
   26   
   27           # Align the label at the right of the frame
   28           frame.set_label_align(1.0, 0.0)
   29   
   30           # Set the style of the frame
   31           frame.set_shadow_type(gtk.SHADOW_ETCHED_OUT)
   32           frame.show()
   33     
   34           # Display the window
   35           window.show()
   36   
   37   def main():
   38       # Enter the event loop
   39       gtk.mainloop()
   40       return 0
   41   
   42   if __name__ == "__main__":
   43       FrameExample()
   44       main()

The calendar.py, label.py and spinbutton.py examples also use Frames.