Chapter 9. Miscellaneous Widgets

Table of Contents

9.1. Labels
9.2. Arrows
9.3. The Tooltips Object
9.4. Progress Bars
9.5. Dialogs
9.5.1. Message Dialogs
9.6. Images
9.6.1. Pixmaps
9.7. Rulers
9.8. Statusbars
9.9. Text Entries
9.10. Spin Buttons
9.11. Combo Widget
9.12. Calendar
9.13. Color Selection
9.14. File Selections
9.15. Font Selection Dialog

9.1. Labels

Labels are used a lot in GTK, and are relatively simple. Labels emit no signals as they do not have an associated X window. If you need to catch signals, or do clipping, place it inside a EventBox (see Section 10.1, “The EventBox”) widget or a Button (see Section 6.1, “Normal Buttons”) widget.

To create a new label, use:

  label = gtk.Label(str)

The sole argument is the string you wish the label to display. To change the label's text after creation, use the method:

  label.set_text(str)

label is the label you created previously, and str is the new string. The space needed for the new string will be automatically adjusted if needed. You can produce multi-line labels by putting line breaks in the label string.

To retrieve the current string, use:

  str = label.get_text()

label is the label you've created, and str is the return string. The label text can be justified using:

  label.set_justify(jtype)

Values for jtype are:

  JUSTIFY_LEFT # the default
  JUSTIFY_RIGHT
  JUSTIFY_CENTER
  JUSTIFY_FILL # does not work

The label widget is also capable of line wrapping the text automatically. This can be activated using:

  label.set_line_wrap(wrap)

The wrap argument takes a TRUE or FALSE value.

If you want your label underlined, then you can set a pattern on the label:

  label.set_pattern(pattern)

The pattern argument indicates how the underlining should look. It consists of a string of underscore and space characters. An underscore indicates that the corresponding character in the label should be underlined. For example, the string "__ __" would underline the first two characters and fourth and fifth characters. If you simply want to have an underlined accelerator ("mnemonic") in your label, you should use set_text_with_mnemonic(str), not set_pattern().

The label.py program is a short example to illustrate these methods. This example makes use of the Frame (see Section 10.5, “Frames”) widget to better demonstrate the label styles. You can ignore this for now as the Frame widget is explained later on.

In GTK+ 2.0, label text can contain markup for font and other text attribute changes, and labels may be selectable (for copy-and-paste). These advanced features won't be explained here.

Figure 9.1, “Label Examples” illustrates the result of running the example program:

Figure 9.1. Label Examples

Label Examples

The label.py source code is:

    1	#!/usr/bin/env python
    2	
    3	# example label.py
    4	
    5	import pygtk
    6	pygtk.require('2.0')
    7	import gtk
    8	
    9	class Labels:
   10	    def __init__(self):
   11	        self.window = gtk.Window(gtk.WINDOW_TOPLEVEL)
   12	        self.window.connect("destroy", lambda w: gtk.main_quit())
   13	
   14	        self.window.set_title("Label")
   15	        vbox = gtk.VBox(False, 5)
   16	        hbox = gtk.HBox(False, 5)
   17	        self.window.add(hbox)
   18	        hbox.pack_start(vbox, False, False, 0)
   19	        self.window.set_border_width(5)
   20	
   21	        frame = gtk.Frame("Normal Label")
   22	        label = gtk.Label("This is a Normal label")
   23	        frame.add(label)
   24	        vbox.pack_start(frame, False, False, 0)
   25	  
   26	        frame = gtk.Frame("Multi-line Label")
   27	        label = gtk.Label("This is a Multi-line label.\nSecond line\n"
   28	                             "Third line")
   29	        frame.add(label)
   30	        vbox.pack_start(frame, False, False, 0)
   31	  
   32	        frame = gtk.Frame("Left Justified Label")
   33	        label = gtk.Label("This is a Left-Justified\n"
   34	                             "Multi-line label.\nThird      line")
   35	        label.set_justify(gtk.JUSTIFY_LEFT)
   36	        frame.add(label)
   37	        vbox.pack_start(frame, False, False, 0)
   38	  
   39	        frame = gtk.Frame("Right Justified Label")
   40	        label = gtk.Label("This is a Right-Justified\nMulti-line label.\n"
   41	                             "Fourth line, (j/k)")
   42	        label.set_justify(gtk.JUSTIFY_RIGHT)
   43	        frame.add(label)
   44	        vbox.pack_start(frame, False, False, 0)
   45	
   46	        vbox = gtk.VBox(False, 5)
   47	        hbox.pack_start(vbox, False, False, 0)
   48	        frame = gtk.Frame("Line wrapped label")
   49	        label = gtk.Label("This is an example of a line-wrapped label.  It "
   50	                             "should not be taking up the entire             "
   51	                             "width allocated to it, but automatically "
   52	                             "wraps the words to fit.  "
   53	                             "The time has come, for all good men, to come to "
   54	                             "the aid of their party.  "
   55	                             "The sixth sheik's six sheep's sick.\n"
   56	                             "     It supports multiple paragraphs correctly, "
   57	                             "and  correctly   adds "
   58	                             "many          extra  spaces. ")
   59	        label.set_line_wrap(True)
   60	        frame.add(label)
   61	        vbox.pack_start(frame, False, False, 0)
   62	  
   63	        frame = gtk.Frame("Filled, wrapped label")
   64	        label = gtk.Label("This is an example of a line-wrapped, filled label.  "
   65	                             "It should be taking "
   66	                             "up the entire              width allocated to it.  "
   67	                             "Here is a sentence to prove "
   68	                             "my point.  Here is another sentence. "
   69	                             "Here comes the sun, do de do de do.\n"
   70	                             "    This is a new paragraph.\n"
   71	                             "    This is another newer, longer, better "
   72	                             "paragraph.  It is coming to an end, "
   73	                             "unfortunately.")
   74	        label.set_justify(gtk.JUSTIFY_FILL)
   75	        label.set_line_wrap(True)
   76	        frame.add(label)
   77	        vbox.pack_start(frame, False, False, 0)
   78	  
   79	        frame = gtk.Frame("Underlined label")
   80	        label = gtk.Label("This label is underlined!\n"
   81	                             "This one is underlined in quite a funky fashion")
   82	        label.set_justify(gtk.JUSTIFY_LEFT)
   83	        label.set_pattern(
   84	            "_________________________ _ _________ _ ______     __ _______ ___")
   85	        frame.add(label)
   86	        vbox.pack_start(frame, False, False, 0)
   87	        self.window.show_all ()
   88	
   89	def main():
   90	    gtk.main()
   91	    return 0
   92	
   93	if __name__ == "__main__":
   94	    Labels()
   95	    main()

Note that the "Filled, wrapped label" is not fill justified.