GtkLabel

Name

GtkLabel -- A widget that displays a small to medium amount of text.

Synopsis


#include <gtk/gtk.h>


struct      GtkLabel;
GtkWidget*  gtk_label_new                   (const char *str);
void        gtk_label_set_text              (GtkLabel *label,
                                             const char *str);
void        gtk_label_set_attributes        (GtkLabel *label,
                                             PangoAttrList *attrs);
void        gtk_label_set_markup            (GtkLabel *label,
                                             const gchar *str);
void        gtk_label_set_markup_with_mnemonic
                                            (GtkLabel *label,
                                             const gchar *str);
void        gtk_label_set_pattern           (GtkLabel *label,
                                             const gchar *pattern);
void        gtk_label_set_justify           (GtkLabel *label,
                                             GtkJustification jtype);
void        gtk_label_get                   (GtkLabel *label,
                                             char **str);
guint       gtk_label_parse_uline           (GtkLabel *label,
                                             const gchar *string);
void        gtk_label_set_line_wrap         (GtkLabel *label,
                                             gboolean wrap);
#define     gtk_label_set
void        gtk_label_get_layout_offsets    (GtkLabel *label,
                                             gint *x,
                                             gint *y);
guint       gtk_label_get_mnemonic_keyval   (GtkLabel *label);
gboolean    gtk_label_get_selectable        (GtkLabel *label);
G_CONST_RETURN gchar* gtk_label_get_text    (GtkLabel *label);
GtkWidget*  gtk_label_new_with_mnemonic     (const char *str);
void        gtk_label_select_region         (GtkLabel *label,
                                             gint start_offset,
                                             gint end_offset);
void        gtk_label_set_mnemonic_widget   (GtkLabel *label,
                                             GtkWidget *widget);
void        gtk_label_set_selectable        (GtkLabel *label,
                                             gboolean setting);
void        gtk_label_set_text_with_mnemonic
                                            (GtkLabel *label,
                                             const gchar *str);


Object Hierarchy


  GObject
   +----GtkObject
         +----GtkWidget
               +----GtkMisc
                     +----GtkLabel

Args


  "label"                gchararray           : Read / Write
  "attributes"           PangoAttrList        : Read / Write
  "use-markup"           gboolean             : Read / Write
  "use-underline"        gboolean             : Read / Write
  "justify"              GtkJustification     : Read / Write
  "pattern"              gchararray           : Write
  "wrap"                 gboolean             : Read / Write
  "selectable"           gboolean             : Read / Write
  "mnemonic-keyval"      guint                : Read
  "mnemonic-widget"      GtkWidget            : Read / Write

Description

The GtkLabel widget is usually used directly by the programmer to display word(s) describing an adjacent widget or its use. It is also used internally by Gtk+ as GtkButton labels, GtkMenu items, and many other widgets which use text.

Details

struct GtkLabel

struct GtkLabel;

This should not be accessed directly. Use the accessor functions as described below.


gtk_label_new ()

GtkWidget*  gtk_label_new                   (const char *str);

Creates a new GtkLabel, containing the text in str.

Creates a new label with the given string of text inside it. You can pass NULL to get an empty label widget.

str : The text of the label
Returns : a new GtkLabel


gtk_label_set_text ()

void        gtk_label_set_text              (GtkLabel *label,
                                             const char *str);

Sets the text of the label to str.

This will also clear any previously set mnemonic accelerators.

Sets the text within the GtkLabel widget. It overwrites any text that was there before. Note that underlines that were there before do not get overwritten. If you want to erase underlines just send NULL to gtk_label_set_pattern().

label : a GtkLabel
str : a string


gtk_label_set_attributes ()

void        gtk_label_set_attributes        (GtkLabel *label,
                                             PangoAttrList *attrs);

Sets a PangoAttrList; the attributes in the list are applied to the label text.

label : a GtkLabel
attrs : a PangoAttrList


gtk_label_set_markup ()

void        gtk_label_set_markup            (GtkLabel *label,
                                             const gchar *str);

Parses str which is marked up with the Pango text markup language, setting the label's text and attribute list based on the parse results.

label : a GtkLabel
str : a markup string (see <link linkend="PangoMarkupFormat">Pango markup format</link>)


gtk_label_set_markup_with_mnemonic ()

void        gtk_label_set_markup_with_mnemonic
                                            (GtkLabel *label,
                                             const gchar *str);

Parses str which is marked up with the Pango text markup language, setting the label's text and attribute list based on the parse results. If characters in str are preceded by an underscore, they are underlined indicating that they represent a keyboard accelerator called a mnemonic.

The mnemonic key can be used to activate another widget, chosen automatically, or explicitly using gtk_label_set_mnemonic_widget().

label : a GtkLabel
str : a markup string (see <link linkend="PangoMarkupFormat">Pango markup format</link>)


gtk_label_set_pattern ()

void        gtk_label_set_pattern           (GtkLabel *label,
                                             const gchar *pattern);

The pattern of underlines you want under the existing text within the GtkLabel widget. For example if the current text of the label says "FooBarBaz" passing a pattern of "___ ___" will underline "Foo" and "Baz" but not "Bar".

label :The GtkLabel you want to set the pattern to.
pattern :The pattern as described above.


gtk_label_set_justify ()

void        gtk_label_set_justify           (GtkLabel *label,
                                             GtkJustification jtype);

Set where the text within the GtkLabel will align to. This can be one of four values: GTK_JUSTIFY_LEFT, GTK_JUSTIFY_RIGHT, GTK_JUSTIFY_CENTER, and GTK_JUSTIFY_FILL. GTK_JUSTIFY_CENTER is the default value when the widget is first created with gtk_label_new().

label :The GtkLabel widget you want to set justification for.
jtype :The GtkJustification type as described above.


gtk_label_get ()

void        gtk_label_get                   (GtkLabel *label,
                                             char **str);

Warning

gtk_label_get is deprecated and should not be used in newly-written code.

Gets the current string of text within the GtkLabel and writes it to the given str argument. It does not make a copy of this string so you must not write to it.

label :The GtkLabel widget you want to get the text from.
str :The reference to the pointer you want to point to the text.


gtk_label_parse_uline ()

guint       gtk_label_parse_uline           (GtkLabel *label,
                                             const gchar *string);

Warning

gtk_label_parse_uline is deprecated and should not be used in newly-written code.

Parses the given string for underscores and converts the next character to an underlined character. The last character that was underlined will have its lower-cased accelerator keyval returned (i.e. "_File" would return the keyval for "f". This is probably only used within the Gtk+ library itself for menu items and such.

label :The GtkLabel you want to affect.
string :The string you want to parse for underlines.
Returns :The lowercase keyval of the last character underlined.


gtk_label_set_line_wrap ()

void        gtk_label_set_line_wrap         (GtkLabel *label,
                                             gboolean wrap);

Toggles line wrapping within the GtkLabel widget. TRUE makes it break lines if text exceeds the widget's size. FALSE lets the text get cut off by the edge of the widget if it exceeds the widget size.

label :The GtkLabel you want to set line wrapping for.
wrap :TRUE turns it on; FALSE turns it off.


gtk_label_set

#  define gtk_label_set				gtk_label_set_text

Aliases gtk_label_set_text. Probably used for backward compatibility with Gtk+ 1.0.x.


gtk_label_get_layout_offsets ()

void        gtk_label_get_layout_offsets    (GtkLabel *label,
                                             gint *x,
                                             gint *y);

Obtains the coordinates where the label will draw the PangoLayout representing the text in the label; useful to convert mouse events into coordinates inside the PangoLayout, e.g. to take some action if some part of the label is clicked. Of course you will need to create a GtkEventBox to receive the events, and pack the label inside it, since labels are a GTK_NO_WINDOW widget.

label : a GtkLabel
x : location to store X offset of layout, or NULL
y : location to store Y offset of layout, or NULL


gtk_label_get_mnemonic_keyval ()

guint       gtk_label_get_mnemonic_keyval   (GtkLabel *label);

If the label has been set so that it has an mnemonic key this function returns the keyval used for the mnemonic accelerator. If there is no mnemonic set up it returns GDK_VoidSymbol.

label : a GtkLabel
Returns : GDK keyval usable for accelerators, or GDK_VoidSymbol


gtk_label_get_selectable ()

gboolean    gtk_label_get_selectable        (GtkLabel *label);

label : 
Returns : 


gtk_label_get_text ()

G_CONST_RETURN gchar* gtk_label_get_text    (GtkLabel *label);

Fetches the text from a label widget

label : a GtkLabel
Returns : the text in the label widget. This is the internal string used by the label, and must not be modified.


gtk_label_new_with_mnemonic ()

GtkWidget*  gtk_label_new_with_mnemonic     (const char *str);

Creates a new GtkLabel, containing the text in str.

If characters in str are preceded by an underscore, they are underlined indicating that they represent a keyboard accelerator called a mnemonic. The mnemonic key can be used to activate another widget, chosen automatically, or explicitly using gtk_label_set_mnemonic_widget().

str : The text of the label, with an underscore in front of the mnemonic character
Returns : a new GtkLabel


gtk_label_select_region ()

void        gtk_label_select_region         (GtkLabel *label,
                                             gint start_offset,
                                             gint end_offset);

label : 
start_offset : 
end_offset : 


gtk_label_set_mnemonic_widget ()

void        gtk_label_set_mnemonic_widget   (GtkLabel *label,
                                             GtkWidget *widget);

If the label has been set so that it has an mnemonic key (using i.e. gtk_label_set_markup_with_mnemonic(), gtk_label_set_text_with_mnemonic(), gtk_label_new_with_mnemonic() or the "use_underline" property) the label can be associated with a widget that is the target of the mnemonic. When the label is inside a widget (like a GtkButton or a GtkNotebook tab) it is automatically associated with the correct widget, but sometimes (i.e. when the target is a GtkEntry next to the label) you need to set it explicitly using this function.

The target widget will be accelerated by emitting "mnemonic_activate" on it. The default handler for this signal will activate the widget if there are no mnemonic collisions and toggle focus between the colliding widgets otherwise.

label : a GtkLabel
widget : the target GtkWidget


gtk_label_set_selectable ()

void        gtk_label_set_selectable        (GtkLabel *label,
                                             gboolean setting);

label : 
setting : 


gtk_label_set_text_with_mnemonic ()

void        gtk_label_set_text_with_mnemonic
                                            (GtkLabel *label,
                                             const gchar *str);

Sets the label's text from the string str. If characters in str are preceded by an underscore, they are underlined indicating that they represent a keyboard accelerator called a mnemonic. The mnemonic key can be used to activate another widget, chosen automatically, or explicitly using gtk_label_set_mnemonic_widget().

label : a GtkLabel
str : a string

Args

"label" (gchararray : Read / Write)

The actual label text. Do not write to this pointer, it is not copied.

"attributes" (PangoAttrList : Read / Write)

"use-markup" (gboolean : Read / Write)

"use-underline" (gboolean : Read / Write)

"justify" (GtkJustification : Read / Write)

The GtkJustification setting. See gtk_label_set_justify() for more info.

"pattern" (gchararray : Write)

The pattern of underlines under the existing text. Do not change the pointer, it isn't copied.

"wrap" (gboolean : Read / Write)

"selectable" (gboolean : Read / Write)

"mnemonic-keyval" (guint : Read)

"mnemonic-widget" (GtkWidget : Read / Write)