Labels

Labels are used a lot in Gtk2Hs, 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 an EventBox widget, which allows you to catch signals for widgets which do not have their own window, or a button.

To create a new label, use:

labelNew :: Maybe String -> IO Label

labelNewWithMnemonic :: String -> IO Label

With the second function, if characters in the string are preceded by an underscore, they are underlined. If you need a literal underscore character in a label, use '__' (two underscores). The first underlined character represents a keyboard accelerator called a mnemonic. When that key is pressed the activable widget which contains the label (e.g. a button) will be activated. The widget which is to be affected can also be set by labelSetMnemonicWidget.

To change the label's text after creation, or to get the label's text, use the functions:

labelSetText :: LabelClass self => self -> String -> IO ()

labelGetLabel :: LabelClass self => self -> IO String

or, of course, the generic set or get functions. 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. If you have multi-line labels the lines can be justified relatively to each other using:

labelSetJustify :: LabelClass self => self -> Justification -> IO ()

where the type Justification has one of four constructors:

JustifyLeft
JustifyRight
JustifyCenter
JustifyFill

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

labelSetLineWrap :: LabelClass self => self -> Bool -> IO ()

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

labelSetPattern :: LabelClass self => self -> [Int] -> IO ()

The list of Ints marks the underlined parts of the label text alternated by the non-interlined parts. For example, [3,1,3] means first 3 characters underlined, the next not, the next 3 underlined.

You can also make text in a lable selectable, so the user can copy and paste it, and use some formatting options.

Below is a short example to illustrate a few of these functions. It makes use of the Frame widget to better demonstrate the label styles. A Frame is just an ornament like a HSeparator and a VSeparator but it surrounds the widget and is an instance of Container. Therefore the widget it frames must be added to it with containerAdd. A frame itself can have a label to convey information about its contents.

Because all the labels are framed, a function myLabelWithFrameNew is defined, which returns a tuple.Gtk2Hs is truly Haskell, so you can use all the Haskell data types and features. The justifications are pretty obvious, but they only refer to the lines inside the label. So, to to right justify label2 itself, you need miscSetAlignment as shown below. The last two widgets in the left horizontal box are packed with boxPackEnd instead of the usual boxPackStart. The button label demonstrates the use of a mnemonic as an accellarator key. Pressing Alt_C on the keyboard has the same effect as clicking the button.

Note: when tested on Fedora 6, pressing Enter or the space bar also had this effect. Also note the effect of the y-character on the placement of the underline.

import Graphics.UI.Gtk

main:: IO ()
main = do
     initGUI
     window <- windowNew
     set window [windowTitle := "Labels", containerBorderWidth := 10 ]
     mainbox <- vBoxNew False 10
     containerAdd window mainbox 
     hbox <- hBoxNew True 5
     boxPackStart mainbox hbox PackNatural 0
     vbox1 <- vBoxNew False 10
     vbox2 <- vBoxNew False 0
     boxPackStart hbox vbox1 PackNatural 0 
     boxPackStart hbox vbox2 PackNatural 0

     (label1,frame1) <- myLabelWithFrameNew
     boxPackStart vbox1 frame1 PackNatural 0
     labelSetText label1 "Penny Harter"

     (label2,frame2) <- myLabelWithFrameNew
     boxPackStart vbox1 frame2 PackNatural 0
     labelSetText label2 "broken bowl\nthe pieces\nstill rocking"
     miscSetAlignment label2 0.0 0.0
     hsep1 <- hSeparatorNew
     boxPackStart vbox1 hsep1 PackNatural 10

     (label3,frame3) <- myLabelWithFrameNew
     boxPackStart vbox1 frame3 PackNatural 0
     labelSetText label3 "Gary Snyder"

     (label4,frame4) <- myLabelWithFrameNew
     boxPackStart vbox1 frame4 PackNatural 0
     labelSetText label4 "After weeks of watching the roof leak\nI fixed it tonight\nby moving a single board"
     labelSetJustify label4 JustifyCenter

     (label5,frame5) <- myLabelWithFrameNew
     boxPackStart vbox2 frame5 PackNatural 0
     labelSetText label5 "Kobayashi Issa"
    
     (label7,frame7) <- myLabelWithFrameNew
     boxPackEnd vbox2 frame7 PackNatural 0
     labelSetText label7 "only one guy and\nonly one fly trying to\nmake the guest room do"
     labelSetJustify label7 JustifyRight

     (label6,frame6) <- myLabelWithFrameNew
     boxPackEnd vbox2 frame6 PackNatural 10
     labelSetText label6 "One Guy"
     frameSetLabel frame6 "Title:"
     labelSetPattern label6 [3,1,3]

     button <- buttonNew
     boxPackEnd mainbox button PackNatural 20
     buttonlabel <- labelNewWithMnemonic "Haiku _Clicked"
     containerAdd button buttonlabel

     widgetShowAll window
     onClicked button (putStrLn "button clicked...")
     onDestroy window mainQuit
     mainGUI


myLabelWithFrameNew :: IO (Label,Frame)
myLabelWithFrameNew = do
           label <- labelNew Nothing
           frame <- frameNew
           containerAdd frame label
           frameSetShadowType frame ShadowOut
           return (label, frame)
-- Haikus quoted from X.J. Kennedy, Dana Gioia, Introduction to Poetry, Longman, 1997