.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.13)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Gtk2::Ex::Entry::Pango 3pm"
.TH Gtk2::Ex::Entry::Pango 3pm "2010-01-25" "perl v5.10.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Gtk2::Ex::Entry::Pango \- Gtk2 Entry that accepts Pango markup.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&        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(\*(Aq<i>Pan</i><b>go</b> is <span color="red">fun</span>\*(Aq);
\&        
\&        
\&        # Create a simple search field
\&        my $search = Gtk2::Ex::Entry::Pango\->new();
\&        $search\->set_empty_markup("<span color=\*(Aqgrey\*(Aq size=\*(Aqsmaller\*(Aq>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\*(Aqs text
\&                if ($text =~ /^[a\-z]*$/) {
\&                        return;
\&                }
\&        
\&                # Mark the string as being erroneous
\&                my $escaped = Glib::Markup::escape_text($text);
\&                $validation\->set_markup("<span underline=\*(Aqerror\*(Aq underline_color=\*(Aqred\*(Aq>$escaped</span>");
\&                $validation\->signal_stop_emission_by_name(\*(Aqchanged\*(Aq);
\&        });
.Ve
.SH "HIERARCHY"
.IX Header "HIERARCHY"
\&\f(CW\*(C`Gtk2::Ex::Entry::Pango\*(C'\fR is a subclass of Gtk2::Entry.
.PP
.Vb 6
\&        Glib::Object
\&        +\-\-\-\-Glib::InitiallyUnowned
\&             +\-\-\-\-Gtk2::Object
\&                  +\-\-\-\-Gtk2::Widget
\&                       +\-\-\-\-Gtk2::Entry
\&                            +\-\-\-\-Gtk2::Ex::Entry::Pango
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`Gtk2::Ex::Entry::Pango\*(C'\fR is a \f(CW\*(C`Gtk2::Entry\*(C'\fR 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>).
.PP
The widget allows Pango markup to be used for input as an alternative to
\&\f(CW\*(C`set_text\*(C'\fR 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).
.PP
This widget allows for the text data to be entered either through the normal
methods provided by \f(CW\*(C`Gtk2::Entry\*(C'\fR or to use the method \*(L"set_markup\*(R". It's
possible to switch between two methods for applying the text. The standard
\&\f(CW\*(C`Gtk2::Entry\*(C'\fR methods will always apply a text without styles while
\&\f(CW\*(C`set_markup()\*(C'\fR will use a style.
.PP
The widget \f(CW\*(C`Gtk2::Ex::Entry::Pango\*(C'\fR keeps track of which style to apply by
listening to the signal \fIchanged\fR. This has some important consequences. If an
instance needs to provide it's own \fIchanged\fR listener that calls
\&\f(CW\*(C`set_markup()\*(C'\fR then the signal \fIchanged\fR has to be stopped otherwise the
layout will be lost. The following code snippet show how to stop the emission of
the \fIchanged\fR signal:
.PP
.Vb 2
\&        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=\*(Aqerror\*(Aq underline_color=\*(Aqred\*(Aq>$escaped</span>");
\&                $entry\->signal_stop_emission_by_name(\*(Aqchanged\*(Aq);
\&        });
.Ve
.PP
Another important thing to note is that \f(CW\*(C`Gtk2::Entry::set_text()\*(C'\fR 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 \fIchanged\fR 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 \f(CW\*(C`set_text()\*(C'\fR will not make an update. The method
\&\*(L"clear_markup\*(R" can be used for safely clearing the markup text.
.SH "CAVEATS"
.IX Header "CAVEATS"
A \f(CW\*(C`Gtk2::Entry\*(C'\fR 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.
.PP
Because a \f(CW\*(C`Gtk2::Entry\*(C'\fR 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 \f(CW\*(C`Gtk2::Entry\*(C'\fR widget display a different text than the one
stored (the text value). This can make things more confusing.
.PP
This widget tries as hard as possible to synchronize the text data and the
layout data.
.SH "INTERFACES"
.IX Header "INTERFACES"
.Vb 4
\&        Glib::Object::_Unregistered::AtkImplementorIface
\&        Gtk2::Buildable
\&        Gtk2::CellEditable
\&        Gtk2::Editable
.Ve
.SH "METHODS"
.IX Header "METHODS"
The following methods are added by this widget:
.SS "new"
.IX Subsection "new"
Creates a new instance.
.SS "set_markup"
.IX Subsection "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 \*(L"parse_markup\*(R" in Gtk2::Pango).
.PP
Parameters:
.IP "\(bu" 4
\&\f(CW$markup\fR
.Sp
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
\&\s-1XML\s0.
.Sp
You might want to use the following code snippet for escaping the characters:
.Sp
.Vb 4
\&        $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)
\&        );
.Ve
.SS "clear_markup"
.IX Subsection "clear_markup"
Clears the Pango markup that was applied to the widget. This method can be
called even if no markup was applied previously.
.PP
\&\fB\s-1NOTE\s0\fR: That this method will emit the signal \fImarkup-changed\fR.
.SS "set_empty_markup"
.IX Subsection "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 \*(L"parse_markup\*(R" in Gtk2::Pango).
.PP
\&\f(CW\*(C`NOTE:\*(C'\fR Setting an empty markup string has no effect on \f(CW\*(C`get_text\*(C'\fR. When an
empty markup string is used the entry holds no data thus \f(CW\*(C`get_text\*(C'\fR will return
an empty string.
.PP
Parameters:
.IP "\(bu" 4
\&\f(CW$markup\fR
.Sp
The text to add to the entry, the text is expected to be using Pango markup.
Make sure to escape all characters with \*(L"escape_text\*(R" in Glib::Markup. For more
details about escaping the markup see \*(L"set_markup\*(R".
.SS "clear_empty_markup"
.IX Subsection "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.
.SS "get_clear_on_focus"
.IX Subsection "get_clear_on_focus"
Returns if the widget's Pango markup will be cleared once the widget is focused
and has no user text.
.SS "set_clear_on_focus"
.IX Subsection "set_clear_on_focus"
Returns if the widget's Pango markup will be cleared once the widget is focused
and has no user text.
.PP
Parameters:
.IP "\(bu" 4
\&\f(CW$value\fR
.Sp
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).
.SH "PROPERTIES"
.IX Header "PROPERTIES"
The following properties are added by this widget:
.SS "markup"
.IX Subsection "markup"
(string: writable)
.PP
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.
.SS "empty-markup"
.IX Subsection "empty-markup"
(string: readable writable)
.PP
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.
.SS "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.', \s-1TRUE\s0, ['readable', 'writable'],"
.IX Subsection "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)
.PP
Indicates if the \f(CW\*(C`empty\-makrup\*(C'\fR has to be cleared when the entry is empty and
the widget has gained focus.
.SH "SIGNALS"
.IX Header "SIGNALS"
.SS "markup-changed"
.IX Subsection "markup-changed"
Emitted when the markup has been changed.
.PP
Signature:
.PP
.Vb 4
\&        sub markup_changed {
\&                my ($widget, $markup) = @_;
\&                # Returns nothing
\&        }
.Ve
.PP
Parameters:
.IP "\(bu" 4
\&\f(CW$markup\fR
.Sp
The new markup that's been applied. This field is a normal Perl string. If
\&\f(CW$markup\fR is \f(CW\*(C`undef\*(C'\fR then the markup was removed.
.SS "empty-markup-changed"
.IX Subsection "empty-markup-changed"
Emitted when the markup used when the widget is empty has been changed.
.PP
Signature:
.PP
.Vb 4
\&        sub empty_markup_changed {
\&                my ($widget, $markup) = @_;
\&                # Returns nothing
\&        }
.Ve
.PP
Parameters:
.IP "\(bu" 4
\&\f(CW$markup\fR
.Sp
The new markup that's been applied when the widget is empty. This field is a
normal Perl string. If \f(CW$markup\fR is \f(CW\*(C`undef\*(C'\fR then the markup was removed.
.SH "SEE ALSO"
.IX Header "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.
.SH "AUTHORS"
.IX Header "AUTHORS"
Emmanuel Rodriguez <potyl@cpan.org>.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2008\-2009 by Emmanuel Rodriguez.
.PP
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.