<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/loose.dtd"> <HTML ><HEAD ><TITLE >Miscellaneous Widgets</TITLE ><META NAME="GENERATOR" CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK REL="HOME" TITLE="GTK+ 2.0 Tutorial" HREF="book1.html"><LINK REL="PREVIOUS" TITLE="Example" HREF="x743.html"><LINK REL="NEXT" TITLE="Arrows" HREF="x793.html"></HEAD ><BODY CLASS="CHAPTER" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#840084" ALINK="#0000FF" ><DIV CLASS="NAVHEADER" ><TABLE SUMMARY="Header navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" ><TR ><TH COLSPAN="3" ALIGN="center" >GTK+ 2.0 Tutorial</TH ></TR ><TR ><TD WIDTH="10%" ALIGN="left" VALIGN="bottom" ><A HREF="x743.html" ACCESSKEY="P" ><<< Previous</A ></TD ><TD WIDTH="80%" ALIGN="center" VALIGN="bottom" ></TD ><TD WIDTH="10%" ALIGN="right" VALIGN="bottom" ><A HREF="x793.html" ACCESSKEY="N" >Next >>></A ></TD ></TR ></TABLE ><HR ALIGN="LEFT" WIDTH="100%"></DIV ><DIV CLASS="CHAPTER" ><H1 ><A NAME="CH-MISCWIDGETS" ></A >Miscellaneous Widgets</H1 ><DIV CLASS="SECT1" ><H1 CLASS="SECT1" ><A NAME="SEC-LABELS" >Labels</A ></H1 ><P >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 <A HREF="c1226.html#SEC-EVENTBOX" >EventBox</A > widget or a Button widget.</P ><P >To create a new label, use:</P ><TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="PROGRAMLISTING" >GtkWidget *gtk_label_new( const char *str ); GtkWidget *gtk_label_new_with_mnemonic( const char *str );</PRE ></TD ></TR ></TABLE ><P >The sole argument is the string you wish the label to display.</P ><P >To change the label's text after creation, use the function:</P ><TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="PROGRAMLISTING" >void gtk_label_set_text( GtkLabel *label, const char *str );</PRE ></TD ></TR ></TABLE ><P >The first argument is the label you created previously (cast using the <TT CLASS="LITERAL" >GTK_LABEL()</TT > macro), and the second is the new string.</P ><P >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.</P ><P >To retrieve the current string, use:</P ><TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="PROGRAMLISTING" >const gchar* gtk_label_get_text( GtkLabel *label ); </PRE ></TD ></TR ></TABLE ><P >Do not free the returned string, as it is used internally by GTK.</P ><P >The label text can be justified using:</P ><TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="PROGRAMLISTING" >void gtk_label_set_justify( GtkLabel *label, GtkJustification jtype );</PRE ></TD ></TR ></TABLE ><P >Values for <TT CLASS="LITERAL" >jtype</TT > are:</P ><TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="PROGRAMLISTING" > GTK_JUSTIFY_LEFT GTK_JUSTIFY_RIGHT GTK_JUSTIFY_CENTER (the default) GTK_JUSTIFY_FILL</PRE ></TD ></TR ></TABLE ><P >The label widget is also capable of line wrapping the text automatically. This can be activated using:</P ><TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="PROGRAMLISTING" >void gtk_label_set_line_wrap (GtkLabel *label, gboolean wrap);</PRE ></TD ></TR ></TABLE ><P >The <TT CLASS="LITERAL" >wrap</TT > argument takes a TRUE or FALSE value.</P ><P >If you want your label underlined, then you can set a pattern on the label:</P ><TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="PROGRAMLISTING" >void gtk_label_set_pattern (GtkLabel *label, const gchar *pattern);</PRE ></TD ></TR ></TABLE ><P >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 <TT CLASS="LITERAL" >"__ __"</TT > would underline the first two characters and eight and ninth characters.</P ><DIV CLASS="NOTE" ><P ></P ><TABLE CLASS="NOTE" WIDTH="100%" BORDER="0" ><TR ><TD WIDTH="25" ALIGN="CENTER" VALIGN="TOP" ><IMG SRC="./stylesheet-images/note.gif" HSPACE="5" ALT="Note"></TD ><TD ALIGN="LEFT" VALIGN="TOP" ><P >If you simply want to have an underlined accelerator ("mnemonic") in your label, you should use gtk_label_new_with_mnemonic() or gtk_label_set_text_with_mnemonic(), not gtk_label_set_pattern().</P ></TD ></TR ></TABLE ></DIV ><P >Below is a short example to illustrate these functions. This example makes use of the Frame widget to better demonstrate the label styles. You can ignore this for now as the <A HREF="x1291.html" >Frame</A > widget is explained later on.</P ><P >In GTK+ 2.0, label texts 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.</P ><P ><SPAN CLASS="INLINEMEDIAOBJECT" ><IMG SRC="images/label.png"></SPAN ></P ><TABLE BORDER="0" BGCOLOR="#E0E0E0" WIDTH="100%" ><TR ><TD ><PRE CLASS="PROGRAMLISTING" > #include <gtk/gtk.h> int main( int argc, char *argv[] ) { static GtkWidget *window = NULL; GtkWidget *hbox; GtkWidget *vbox; GtkWidget *frame; GtkWidget *label; /* Initialise GTK */ gtk_init (&argc, &argv); window = gtk_window_new (GTK_WINDOW_TOPLEVEL); g_signal_connect (window, "destroy", G_CALLBACK (gtk_main_quit), NULL); gtk_window_set_title (GTK_WINDOW (window), "Label"); vbox = gtk_vbox_new (FALSE, 5); hbox = gtk_hbox_new (FALSE, 5); gtk_container_add (GTK_CONTAINER (window), hbox); gtk_box_pack_start (GTK_BOX (hbox), vbox, FALSE, FALSE, 0); gtk_container_set_border_width (GTK_CONTAINER (window), 5); frame = gtk_frame_new ("Normal Label"); label = gtk_label_new ("This is a Normal label"); gtk_container_add (GTK_CONTAINER (frame), label); gtk_box_pack_start (GTK_BOX (vbox), frame, FALSE, FALSE, 0); frame = gtk_frame_new ("Multi-line Label"); label = gtk_label_new ("This is a Multi-line label.\nSecond line\n" \ "Third line"); gtk_container_add (GTK_CONTAINER (frame), label); gtk_box_pack_start (GTK_BOX (vbox), frame, FALSE, FALSE, 0); frame = gtk_frame_new ("Left Justified Label"); label = gtk_label_new ("This is a Left-Justified\n" \ "Multi-line label.\nThird line"); gtk_label_set_justify (GTK_LABEL (label), GTK_JUSTIFY_LEFT); gtk_container_add (GTK_CONTAINER (frame), label); gtk_box_pack_start (GTK_BOX (vbox), frame, FALSE, FALSE, 0); frame = gtk_frame_new ("Right Justified Label"); label = gtk_label_new ("This is a Right-Justified\nMulti-line label.\n" \ "Fourth line, (j/k)"); gtk_label_set_justify (GTK_LABEL (label), GTK_JUSTIFY_RIGHT); gtk_container_add (GTK_CONTAINER (frame), label); gtk_box_pack_start (GTK_BOX (vbox), frame, FALSE, FALSE, 0); vbox = gtk_vbox_new (FALSE, 5); gtk_box_pack_start (GTK_BOX (hbox), vbox, FALSE, FALSE, 0); frame = gtk_frame_new ("Line wrapped label"); label = gtk_label_new ("This is an example of a line-wrapped label. It " \ "should not be taking up the entire " /* big space to test spacing */\ "width allocated to it, but automatically " \ "wraps the words to fit. " \ "The time has come, for all good men, to come to " \ "the aid of their party. " \ "The sixth sheik's six sheep's sick.\n" \ " It supports multiple paragraphs correctly, " \ "and correctly adds "\ "many extra spaces. "); gtk_label_set_line_wrap (GTK_LABEL (label), TRUE); gtk_container_add (GTK_CONTAINER (frame), label); gtk_box_pack_start (GTK_BOX (vbox), frame, FALSE, FALSE, 0); frame = gtk_frame_new ("Filled, wrapped label"); label = gtk_label_new ("This is an example of a line-wrapped, filled label. " \ "It should be taking "\ "up the entire width allocated to it. " \ "Here is a sentence to prove "\ "my point. Here is another sentence. "\ "Here comes the sun, do de do de do.\n"\ " This is a new paragraph.\n"\ " This is another newer, longer, better " \ "paragraph. It is coming to an end, "\ "unfortunately."); gtk_label_set_justify (GTK_LABEL (label), GTK_JUSTIFY_FILL); gtk_label_set_line_wrap (GTK_LABEL (label), TRUE); gtk_container_add (GTK_CONTAINER (frame), label); gtk_box_pack_start (GTK_BOX (vbox), frame, FALSE, FALSE, 0); frame = gtk_frame_new ("Underlined label"); label = gtk_label_new ("This label is underlined!\n" "This one is underlined in quite a funky fashion"); gtk_label_set_justify (GTK_LABEL (label), GTK_JUSTIFY_LEFT); gtk_label_set_pattern (GTK_LABEL (label), "_________________________ _ _________ _ ______ __ _______ ___"); gtk_container_add (GTK_CONTAINER (frame), label); gtk_box_pack_start (GTK_BOX (vbox), frame, FALSE, FALSE, 0); gtk_widget_show_all (window); gtk_main (); return 0; }</PRE ></TD ></TR ></TABLE ></DIV ></DIV ><DIV CLASS="NAVFOOTER" ><HR ALIGN="LEFT" WIDTH="100%"><TABLE SUMMARY="Footer navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" ><A HREF="x743.html" ACCESSKEY="P" ><<< Previous</A ></TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="book1.html" ACCESSKEY="H" >Home</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" ><A HREF="x793.html" ACCESSKEY="N" >Next >>></A ></TD ></TR ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" >Example</TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" > </TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" >Arrows</TD ></TR ></TABLE ></DIV ></BODY ></HTML >