Provided by: libgtk2-ex-entry-pango-perl_0.09-1_all 
NAME
Gtk2::Ex::Entry::Pango - Gtk2 Entry that accepts Pango markup.
SYNOPSIS
use Gtk2::Ex::Entry::Pango;
# You can use any method defined in Gtk2::Entry or set_markup()
my $entry = Gtk2::Ex::Entry::Pango->new();
$entry->set_markup('<i>Pan</i><b>go</b> is <span color="red">fun</span>');
# Create a simple search field
my $search = Gtk2::Ex::Entry::Pango->new();
$search->set_empty_markup("<span color='grey' size='smaller'>Search...</span>");
# Realtime validation - accept only ASCII letters
my $validation = Gtk2::Ex::Entry::Pango->new();
$validation->signal_connect(changed => sub {
my $text = $validation->get_text;
# Validate the entry's text
if ($text =~ /^[a-z]*$/) {
return;
}
# Mark the string as being erroneous
my $escaped = Glib::Markup::escape_text($text);
$validation->set_markup("<span underline='error' underline_color='red'>$escaped</span>");
$validation->signal_stop_emission_by_name('changed');
});
HIERARCHY
"Gtk2::Ex::Entry::Pango" is a subclass of Gtk2::Entry.
Glib::Object
+----Glib::InitiallyUnowned
+----Gtk2::Object
+----Gtk2::Widget
+----Gtk2::Entry
+----Gtk2::Ex::Entry::Pango
DESCRIPTION
"Gtk2::Ex::Entry::Pango" is a "Gtk2::Entry" that can accept Pango markup for various
purposes (for more information about Pango text markup language see
<http://library.gnome.org/devel/pango/stable/PangoMarkupFormat.html>).
The widget allows Pango markup to be used for input as an alternative to "set_text" or for
setting a default value when the widget is empty. The default value when empty is ideal
for standalone text entries that have no accompanying label (such as a text field for a
search).
This widget allows for the text data to be entered either through the normal methods
provided by "Gtk2::Entry" or to use the method "set_markup". It's possible to switch
between two methods for applying the text. The standard "Gtk2::Entry" methods will always
apply a text without styles while "set_markup()" will use a style.
The widget "Gtk2::Ex::Entry::Pango" keeps track of which style to apply by listening to
the signal changed. This has some important consequences. If an instance needs to provide
it's own changed listener that calls "set_markup()" then the signal changed has to be
stopped otherwise the layout will be lost. The following code snippet show how to stop the
emission of the changed signal:
my $entry = Gtk2::Ex::Entry::Pango->new();
$entry->signal_connect(changed => sub {
# Validate the text
my $text = $entry->get_text;
if (validate($text)) {
return;
}
# Mark the text as being erroneous
my $escaped = Glib::Markup::escape_text($text);
$entry->set_markup("<span underline='error' underline_color='red'>$escaped</span>");
$entry->signal_stop_emission_by_name('changed');
});
Another important thing to note is that "Gtk2::Entry::set_text()" will not update it's
content if the input text is the same as the text already stored. This means that if set
text is called with the same string it will not emit the signal changed and the widget
will not pickup that the markup styles have to be dropped. This is true even it the string
displayed uses markup, as long as the contents are the same "set_text()" will not make an
update. The method "clear_markup" can be used for safely clearing the markup text.
CAVEATS
A "Gtk2::Entry" keeps track of both the text and the markup styles (Pango layout) as two
different entities . The markup styles are just styles applied over the internal text.
Because of this it's possible to have the widget display a different text than the one
stored internally.
Because a "Gtk2::Entry" keeps track of both the text and the style layouts. It's
important to always keep track of both. If the styles and text are not totally
synchronized strange things will happen. In the worst case it's even possible to make the
"Gtk2::Entry" widget display a different text than the one stored (the text value). This
can make things more confusing.
This widget tries as hard as possible to synchronize the text data and the layout data.
INTERFACES
Glib::Object::_Unregistered::AtkImplementorIface
Gtk2::Buildable
Gtk2::CellEditable
Gtk2::Editable
METHODS
The following methods are added by this widget:
new
Creates a new instance.
set_markup
Sets the text of the entry using Pango markup. This method can die if the markup is not
valid and fails to parse (see "parse_markup" in Gtk2::Pango).
Parameters:
• $markup
The text to add to the entry, the text is expected to be using Pango markup. This
means that even if no markup is used special characters like <, >, &, ' and " need to
be escaped. Keep in mind that Pango markup is a subset of XML.
You might want to use the following code snippet for escaping the characters:
$entry->set_markup(
sprintf "The <i>%s</i> <b>%s</b> fox <sup>%s</sup> over the lazy dog",
map { Glib::Markup::escape_text($_) } qw(quick brown jumps)
);
clear_markup
Clears the Pango markup that was applied to the widget. This method can be called even if
no markup was applied previously.
NOTE: That this method will emit the signal markup-changed.
set_empty_markup
Sets the Pango markup that was applied to the widget when there's the entry is empty. This
method can die if the markup is not valid and fails to parse (see "parse_markup" in
Gtk2::Pango).
"NOTE:" Setting an empty markup string has no effect on "get_text". When an empty markup
string is used the entry holds no data thus "get_text" will return an empty string.
Parameters:
• $markup
The text to add to the entry, the text is expected to be using Pango markup. Make
sure to escape all characters with "escape_text" in Glib::Markup. For more details
about escaping the markup see "set_markup".
clear_empty_markup
Clears the Pango markup that was applied to the widget. This method can be called even if
no markup was applied previously.
get_clear_on_focus
Returns if the widget's Pango markup will be cleared once the widget is focused and has no
user text.
set_clear_on_focus
Returns if the widget's Pango markup will be cleared once the widget is focused and has no
user text.
Parameters:
• $value
A boolean value that dictates if the Pango markup has to be cleared when the widget is
focused and there's no text entered (the entry is empty).
PROPERTIES
The following properties are added by this widget:
markup
(string: writable)
The markup text used by this widget. This property is a string that's only writable.
That's right, there's no way for extracting the markup from the widget.
empty-markup
(string: readable writable)
The markup text used by this widget when the entry field is empty. If this property is set
the entry will display a default string in the widget when there's no text provided by the
user.
clear-on-focus '', 'Clear the markup when the widget has focus', 'If the Pango markup to
display has to cleared when the entry has focus.', TRUE, ['readable', 'writable'],
(boolean: readable writable)
Indicates if the "empty-makrup" has to be cleared when the entry is empty and the widget
has gained focus.
SIGNALS
markup-changed
Emitted when the markup has been changed.
Signature:
sub markup_changed {
my ($widget, $markup) = @_;
# Returns nothing
}
Parameters:
• $markup
The new markup that's been applied. This field is a normal Perl string. If $markup is
"undef" then the markup was removed.
empty-markup-changed
Emitted when the markup used when the widget is empty has been changed.
Signature:
sub empty_markup_changed {
my ($widget, $markup) = @_;
# Returns nothing
}
Parameters:
• $markup
The new markup that's been applied when the widget is empty. This field is a normal
Perl string. If $markup is "undef" then the markup was removed.
SEE ALSO
Take a look at the examples for getting some ideas or inspiration on how to use this
widget. For a more powerful text widget that supports more operations take a look at
Gtk2::TextView.
AUTHORS
Emmanuel Rodriguez <potyl@cpan.org>.
COPYRIGHT AND LICENSE
Copyright (C) 2008-2009 by Emmanuel Rodriguez.
This library is free software; you can redistribute it and/or modify it under the same
terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of
Perl 5 you may have available.