Gtk::Label Class Reference
[Widgets]

Inheritance diagram for Gtk::Label:

[legend]

List of all members.

Detailed Description

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

A simple setable widget for holding a Glib::ustring.

The Label widget looks like this:


Public Member Functions
double	get_angle () const
	Gets the angle of rotation for the label.
Pango::AttrList	get_attributes () const
	Gets the attribute list that was set on the label using set_attributes(), if any.
Pango::EllipsizeMode	get_ellipsize () const
	Return value: Pango::EllipsizeMode.
Justification	get_justify () const
	Return value: Gtk::Justification.
Glib::ustring	get_label () const
	Fetches the text from a label widget including any embedded underlines indicating mnemonics and Pango markup.
Glib::RefPtr<const Pango::Layout>	get_layout () const
	Gets the Pango::Layout used to display the label.
Glib::RefPtr<Pango::Layout>	get_layout ()
	Gets the Pango::Layout used to display the label.
void	get_layout_offsets (int& x, int& y) const
	Obtains the coordinates where the label will draw the Pango::Layout representing the text in the label; useful to convert mouse events into coordinates inside the Pango::Layout, e.g. to take some action if some part of the label is clicked.
bool	get_line_wrap () const
	Return value: `true` if the lines of the label are automatically wrapped.
Pango::WrapMode	get_line_wrap_mode () const
	Return value: `true` if the lines of the label are automatically wrapped.
int	get_max_width_chars () const
	Retrieves the desired maximum width of label, in characters.
guint	get_mnemonic_keyval () const
	If the label has been set so that it has an mnemonic key this function Returns: GDK keyval usable for accelerators, or GDK_VoidSymbol.
const Widget*	get_mnemonic_widget () const
	Retrieves the target of the mnemonic (keyboard shortcut) of this label.
Widget*	get_mnemonic_widget ()
	Retrieves the target of the mnemonic (keyboard shortcut) of this label.
bool	get_selectable () const
	Gets the value set by set_selectable().
bool	get_selection_bounds (int& start, int& end) const
	Gets the selected range of characters in the label, returning `true` if there's a selection.
bool	get_single_line_mode () const
	Return value: `true` when the label is in single line mode.
Glib::ustring	get_text () const
	Fetches the text from a label widget, as displayed on the screen.
bool	get_use_markup () const
	Return value: `true` if the label's text will be parsed for markup.
bool	get_use_underline () const
	Return value: `true` whether an embedded underline in the label indicates.
int	get_width_chars () const
	Retrieves the desired width of label, in characters.
const GtkLabel*	gobj () const
	Provides access to the underlying C GtkObject.
GtkLabel*	gobj ()
	Provides access to the underlying C GtkObject.
	Label (const Glib::ustring& label, AlignmentEnum xalign, AlignmentEnum yalign=ALIGN_CENTER, bool mnemonic=false)
	This constructor is a shortcut for often used code when you want to create a label with alignment different than default one.
	Label (const Glib::ustring& label, float xalign, float yalign, bool mnemonic=false)
	This constructor is a shortcut for often used code when you want to create a label with alignment different than default one.
	Label (const Glib::ustring& label, bool mnemonic=false)
	Label ()
Glib::PropertyProxy_ReadOnly <double>	property_angle () const
	Angle at which the label is rotated.
Glib::PropertyProxy<double>	property_angle ()
	Angle at which the label is rotated.
Glib::PropertyProxy_ReadOnly <Pango::AttrList>	property_attributes () const
	A list of style attributes to apply to the text of the label.
Glib::PropertyProxy <Pango::AttrList>	property_attributes ()
	A list of style attributes to apply to the text of the label.
Glib::PropertyProxy_ReadOnly<int>	property_cursor_position () const
	The current position of the insertion cursor in chars.
Glib::PropertyProxy_ReadOnly <Pango::EllipsizeMode>	property_ellipsize () const
	The preferred place to ellipsize the string.
Glib::PropertyProxy <Pango::EllipsizeMode>	property_ellipsize ()
	The preferred place to ellipsize the string.
Glib::PropertyProxy_ReadOnly <Justification>	property_justify () const
	The alignment of the lines in the text of the label relative to each other.
Glib::PropertyProxy <Justification>	property_justify ()
	The alignment of the lines in the text of the label relative to each other.
Glib::PropertyProxy_ReadOnly <Glib::ustring>	property_label () const
	The text of the label.
Glib::PropertyProxy <Glib::ustring>	property_label ()
	The text of the label.
Glib::PropertyProxy_ReadOnly<int>	property_max_width_chars () const
	The desired maximum width of the label.
Glib::PropertyProxy<int>	property_max_width_chars ()
	The desired maximum width of the label.
Glib::PropertyProxy_ReadOnly <guint>	property_mnemonic_keyval () const
	The mnemonic accelerator key for this label.
Glib::PropertyProxy_ReadOnly <Widget*>	property_mnemonic_widget () const
	The widget to be activated when the label's mnemonic key is pressed.
Glib::PropertyProxy<Widget*>	property_mnemonic_widget ()
	The widget to be activated when the label's mnemonic key is pressed.
Glib::PropertyProxy_WriteOnly <Glib::ustring>	property_pattern ()
	A string with _ characters in positions correspond to characters in the text to underline.
Glib::PropertyProxy_ReadOnly <bool>	property_selectable () const
	Whether the label text can be selected with the mouse.
Glib::PropertyProxy<bool>	property_selectable ()
	Whether the label text can be selected with the mouse.
Glib::PropertyProxy_ReadOnly<int>	property_selection_bound () const
	The position of the opposite end of the selection from the cursor in chars.
Glib::PropertyProxy_ReadOnly <bool>	property_single_line_mode () const
	Whether the label is in single line mode.
Glib::PropertyProxy<bool>	property_single_line_mode ()
	Whether the label is in single line mode.
Glib::PropertyProxy_ReadOnly <bool>	property_use_markup () const
	The text of the label includes XML markup.
Glib::PropertyProxy<bool>	property_use_markup ()
	The text of the label includes XML markup.
Glib::PropertyProxy_ReadOnly <bool>	property_use_underline () const
	If set.
Glib::PropertyProxy<bool>	property_use_underline ()
	If set.
Glib::PropertyProxy_ReadOnly<int>	property_width_chars () const
	The desired width of the label.
Glib::PropertyProxy<int>	property_width_chars ()
	The desired width of the label.
Glib::PropertyProxy_ReadOnly <bool>	property_wrap () const
	If set.
Glib::PropertyProxy<bool>	property_wrap ()
	If set.
Glib::PropertyProxy_ReadOnly <Pango::WrapMode>	property_wrap_mode () const
	If wrap is set.
Glib::PropertyProxy <Pango::WrapMode>	property_wrap_mode ()
	If wrap is set.
void	select_region (int start_offset)
	Selects a range of characters in the label, from start_offset to the end, if the label is selectable.
void	select_region (int start_offset, int end_offset)
	Selects a range of characters in the label, if the label is selectable.
void	set_angle (double angle)
	Sets the angle of rotation for the label.
void	set_attributes (Pango::AttrList& attrs)
	Sets a Pango::AttrList; the attributes in the list are applied to the label text.
void	set_ellipsize (Pango::EllipsizeMode mode)
	Sets the mode used to ellipsize (add an ellipsis: "...") to the text if there is not enough space to render the entire string.
void	set_justify (Justification jtype)
	Sets the alignment of the lines in the text of the label relative to each other.
void	set_label (const Glib::ustring& str)
	Sets the text of the label.
void	set_line_wrap (bool wrap=true)
	Toggles line wrapping within the Gtk::Label widget.
void	set_line_wrap_mode (Pango::WrapMode wrap_mode)
	If line wrapping is on (see set_line_wrap()) this controls how the line wrapping is done.
void	set_markup (const Glib::ustring& 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.
void	set_markup_with_mnemonic (const Glib::ustring& 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.
void	set_max_width_chars (int n_chars)
	Sets the desired maximum width in characters of label to n_chars.
void	set_mnemonic_widget (Widget& widget)
	If the label has been set so that it has an mnemonic key (using i.e. set_markup_with_mnemonic(), set_text_with_mnemonic(), new_with_mnemonic() or the "use_underline" property) the label can be associated with a widget that is the target of the mnemonic.
void	set_pattern (const Glib::ustring& pattern)
void	set_selectable (bool setting=true)
	Selectable labels allow the user to select text from the label, for copy-and-paste.
void	set_single_line_mode (bool single_line_mode=true)
	Sets whether the label is in single line mode.
void	set_text (const Glib::ustring& str)
	Doesn't use markup.
void	set_text_with_mnemonic (const Glib::ustring& str)
	Sets the label's text from the string str.
void	set_use_markup (bool setting=true)
	Sets whether the text of the label contains markup in Pango's text markup language.
void	set_use_underline (bool setting=true)
	If true, an underline in the text indicates the next character should be used for the mnemonic accelerator key.
void	set_width_chars (int n_chars)
	Sets the desired width in characters of label to n_chars.
Glib::SignalProxy1<void, Menu*>	signal_populate_popup ()
virtual	~Label ()
Protected Member Functions
virtual void	on_populate_popup (Menu* menu)
Related Functions
(Note that these are not member functions.)
Gtk::Label*	wrap (GtkLabel* object, bool take_copy=false)
	A Glib::wrap() method for this object.

Constructor & Destructor Documentation

virtual Gtk::Label::~Label ( ) [virtual]

Gtk::Label::Label ( )

Gtk::Label::Label	(	const Glib::ustring &	label,
		bool	mnemonic = `false`
	)			`[explicit]`

Gtk::Label::Label	(	const Glib::ustring &	label,
		float	xalign,
		float	yalign,
		bool	mnemonic = `false`
	)

This constructor is a shortcut for often used code when you want to create a label with alignment different than default one.

 Gtk::Label label(text, x, y, mnemonic);

is equivalent to:

 Gtk::Label label(text, mnemonic);
 label.set_alignment(x, y);

Gtk::Label::Label	(	const Glib::ustring &	label,
		AlignmentEnum	xalign,
		AlignmentEnum	yalign = `ALIGN_CENTER`,
		bool	mnemonic = `false`
	)

This constructor is a shortcut for often used code when you want to create a label with alignment different than default one.

 Gtk::Label label(text, x, y, mnemonic);

is equivalent to:

 Gtk::Label label(text, mnemonic);
 label.set_alignment(x, y);

Member Function Documentation

double Gtk::Label::get_angle ( ) const

Gets the angle of rotation for the label.

See set_angle().

Returns:: The angle of rotation for the label

Since gtkmm 2.6:

Pango::AttrList Gtk::Label::get_attributes ( ) const

Gets the attribute list that was set on the label using set_attributes(), if any.

This function does not reflect attributes that come from the labels markup (see set_markup()). If you want to get the effective attributes for the label, use pango_layout_get_attribute (gtk_label_get_layout (label)).

Returns:: The attribute list, or 0 if none was set.

Pango::EllipsizeMode Gtk::Label::get_ellipsize ( ) const

Return value: Pango::EllipsizeMode.

Returns:: Pango::EllipsizeMode

Since gtkmm 2.6:

Justification Gtk::Label::get_justify ( ) const

Return value: Gtk::Justification.

Returns:: Gtk::Justification.

Glib::ustring Gtk::Label::get_label ( ) const

Fetches the text from a label widget including any embedded underlines indicating mnemonics and Pango markup.

(See get_text()).

Returns:: The text of the label widget..

Glib::RefPtr<const Pango::Layout> Gtk::Label::get_layout ( ) const

Gets the Pango::Layout used to display the label.

The layout is useful to e.g. convert text positions to pixel positions, in combination with get_layout_offsets().

Returns:: The Pango::Layout for this label.

Glib::RefPtr<Pango::Layout> Gtk::Label::get_layout ( )

Gets the Pango::Layout used to display the label.

The layout is useful to e.g. convert text positions to pixel positions, in combination with get_layout_offsets().

Returns:: The Pango::Layout for this label.

void Gtk::Label::get_layout_offsets	(	int &	x,
		int &	y
	)			const

Obtains the coordinates where the label will draw the Pango::Layout representing the text in the label; useful to convert mouse events into coordinates inside the Pango::Layout, e.g. to take some action if some part of the label is clicked.

Of course you will need to create a Gtk::EventBox to receive the events, and pack the label inside it, since labels are a Gtk::NO_WINDOW widget. Remember when using the Pango::Layout functions you need to convert to and from pixels using PANGO_PIXELS() or Pango::SCALE.

Parameters:

	x	Location to store X offset of layout, or `0`.
	y	Location to store Y offset of layout, or `0`.

bool Gtk::Label::get_line_wrap ( ) const

Return value: true if the lines of the label are automatically wrapped.

Returns:: true if the lines of the label are automatically wrapped.

Pango::WrapMode Gtk::Label::get_line_wrap_mode ( ) const

Return value: true if the lines of the label are automatically wrapped.

Returns:: true if the lines of the label are automatically wrapped.

Since gtkmm 2.10:

int Gtk::Label::get_max_width_chars ( ) const

Retrieves the desired maximum width of label, in characters.

See set_width_chars().

Returns:: The maximum width of the label in characters.

Since gtkmm 2.6:

guint Gtk::Label::get_mnemonic_keyval ( ) const

If the label has been set so that it has an mnemonic key this function Returns: GDK keyval usable for accelerators, or GDK_VoidSymbol.

Returns:: GDK keyval usable for accelerators, or GDK_VoidSymbol.

const Widget* Gtk::Label::get_mnemonic_widget ( ) const

Retrieves the target of the mnemonic (keyboard shortcut) of this label.

See set_mnemonic_widget().

Returns:: The target of the label's mnemonic, or 0 if none has been set and the default algorithm will be used.

Widget* Gtk::Label::get_mnemonic_widget ( )

Retrieves the target of the mnemonic (keyboard shortcut) of this label.

See set_mnemonic_widget().

Returns:: The target of the label's mnemonic, or 0 if none has been set and the default algorithm will be used.

bool Gtk::Label::get_selectable ( ) const

Gets the value set by set_selectable().

Returns:: true if the user can copy text from the label.

bool Gtk::Label::get_selection_bounds	(	int &	start,
		int &	end
	)			const

Gets the selected range of characters in the label, returning true if there's a selection.

Parameters:

	start	Return location for start of selection, as a character offset.
	end	Return location for end of selection, as a character offset.

Returns:: true if selection is non-empty.

bool Gtk::Label::get_single_line_mode ( ) const

Return value: true when the label is in single line mode.

Returns:: true when the label is in single line mode.

Since gtkmm 2.6:

Glib::ustring Gtk::Label::get_text ( ) const

Fetches the text from a label widget, as displayed on the screen.

This does not include any embedded underlines indicating mnemonics or Pango markup. (See get_label())

Returns:: The text in the label widget.

bool Gtk::Label::get_use_markup ( ) const

Return value: true if the label's text will be parsed for markup.

Returns:: true if the label's text will be parsed for markup.

bool Gtk::Label::get_use_underline ( ) const

Return value: true whether an embedded underline in the label indicates.

Returns:: true whether an embedded underline in the label indicates the mnemonic accelerator keys.

int Gtk::Label::get_width_chars ( ) const

Retrieves the desired width of label, in characters.

See set_width_chars().

Returns:: The width of the label in characters.

Since gtkmm 2.6:

const GtkLabel* Gtk::Label::gobj ( ) const [inline]

Provides access to the underlying C GtkObject.

Reimplemented from Gtk::Misc.

Reimplemented in Gtk::AccelLabel.

GtkLabel* Gtk::Label::gobj ( ) [inline]

Provides access to the underlying C GtkObject.

Reimplemented from Gtk::Misc.

Reimplemented in Gtk::AccelLabel.

virtual void Gtk::Label::on_populate_popup ( Menu* menu ) [protected, virtual]

Glib::PropertyProxy_ReadOnly<double> Gtk::Label::property_angle ( ) const

Angle at which the label is rotated.