Emmanuel Rodriguez > Gtk2-Ex-Entry-Pango-0.10 > Gtk2::Ex::Entry::Pango

Download:
Gtk2-Ex-Entry-Pango-0.10.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.10   Source  

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:

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:

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:

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:

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:

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-2010 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.

syntax highlighting: