view release on metacpan or  search on metacpan

devel/AddOn-FollowAppend.pm  view on Meta::CPAN

=head1 NAME

Gtk2::Ex::TextView::FollowAppend -- make a TextView follow appended text

=head1 SYNOPSIS

 use Gtk2::Ex::TextView::FollowAppend;
 Gtk2::Ex::TextView::FollowAppend->new ($textview);

=head1 DESCRIPTION

B<Caution!  This is preliminary.  It will probably move to the WidgetBits
dist and might get a rename, so don't use it yet, or only give it a try at
your own peril!  :-)>

FollowAppend sets up a TextView so it automatically scrolls to follow text
added at the end of the TextBuffer.  The effect is like Emacs
C<compilation-scroll-output> and it's good for following text progressively
added by a background task or subprocess, yet still allow the user to scroll
to see earlier output.

A scroll is done when

=over

=item *

Text, pixbuf or child anchor is inserted at the end of the TextBuffer.
Insertions elsewhere are ignored.

=item *

The cursor mark is at end of the TextBuffer.  So if you've moved the cursor
up to look at or copy something else then the view is not scrolled away from
there.

=item *

The previous end position, from before the insert, is visible.  So if you've
scrolled up just with the scroll bar to see earlier parts of the buffer it's
not forcibly moved to the end.

=back

=head1 FUNCTIONS

=head2 Creation

=over 4

=item C<< $follow = Gtk2::Ex::TextView::FollowAppend->new ($textview) >>

Create and return a FollowAppend object which makes C<$textview> follow
output appended to its TextBuffer.

The FollowAppend works with whatever TextBuffer, if any, is set in
C<$textview> at a given time.  It doesn't need a textbuf set initially, and
any textbuf can be changed or unset later.

C<$follow> only keeps a weak reference to C<$textview> so the mere
FollowAppend feature doesn't keep C<$textview> alive if nobody else cares if
it lives or dies.  On that basis it's safe to hold C<$follow> in the hash of
C<$textview> itself,

    $textview->{'follow'} = Gtk2::Ex::TextView::FollowAppend->new($textview);

If the C<$follow> object is destroyed it removes its setups from the
C<$textview>, so be sure to save C<$follow> somewhere.

=back

=head1 SEE ALSO

L<Gtk2::TextView>

=head1 HOME PAGE

L<http://user42.tuxfamily.org/gtk2-ex-errortextdialog/index.html>

=head1 LICENSE

Gtk2-Ex-ErrorTextDialog is Copyright 2007, 2008, 2009, 2010, 2011, 2013 Kevin Ryde

Gtk2-Ex-ErrorTextDialog is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License as published
by the Free Software Foundation; either version 3, or (at your option) any
later version.

Gtk2-Ex-ErrorTextDialog is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
Public License for more details.

You should have received a copy of the GNU General Public License along
with Gtk2-Ex-ErrorTextDialog.  If not, see L<http://www.gnu.org/licenses/>.

=cut