Chapter 9. Miscellaneous Widgets
Prev |  | Next

## Chapter 9. Miscellaneous Widgets

## 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

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.

Prev | Up | Next
8.5. Range Widget Example | Home | 9.2. Arrows