view release on metacpan or  search on metacpan

lib/Gtk2/Ex/Dragger.pm  view on Meta::CPAN

#------------------------------------------------------------------------------

1;
__END__

=for stopwords Gtk2-Ex-Dragger Dragger scrollbars WidgetCursor natively viewport dragger scrollbar timestamp Gdk ungrab Viewport TextView pixmap Ryde WidgetEvents boolean enum UpdatePolicy mozilla

=head1 NAME

Gtk2::Ex::Dragger -- drag to move adjustment position

=for test_synopsis my ($widget)

=head1 SYNOPSIS

 use Gtk2::Ex::Dragger;
 Gtk2::Ex::Dragger->new (widget => $widget,
                         hadjustment => $widget->get_hadjustment);

=head1 DESCRIPTION

C<Gtk2::Ex::Dragger> implements mouse pointer dragging to move the contents
of a widget horizontally, vertically, or both.  It works on any windowed
widget which has C<Gtk2::Adjustment> objects controlling the visible part.

The width or height of the widget corresponds to the "page" in the
adjustment.  Dragger scales pixel movement onto the adjustment "value"
accordingly.  It's then up to the usual widget drawing to follow
C<value-changed> signals from the adjustment for redraws, the same as for
scrollbars etc.  The effect for the user is that the contents are pulled
around with the mouse.

                 Adjustment
                      +--+ --upper
                      |  |
     Window           |  |
    +-------------+ \ |  |
    |             |  \|  |
    |             |   +--+ \_ page size
    |             |   |  | /
    |             |   +--+ ___ value
    |             |  /|  |
    +-------------+ / |  |
                      |  |
                      |  |
                      +--+ --lower

If you've got scrollbars then they move with the dragging too.  It can be
good to have both ways of moving since the scrollbars give visual feedback
but dragging allows finer movements if the visible page is a very small part
of the total adjustable extent.

The "confine" option lets you to restrict mouse movement to screen positions
corresponding to the adjustment upper/lower, so the user gets an obvious
feedback at the limits.

The "cursor" option changes the mouse pointer cursor while dragging.  This
is good if it's not clear for a given widget which button press etc
activates a drag.  The cursor is set through WidgetCursor (see
L<Gtk2::Ex::WidgetCursor>) and so cooperates with other uses of that.  See
F<examples/heart.pl> in the Gtk2-Ex-Dragger sources, or F<examples/busy.pl>
for the global "busy" indication.

Dragger can work on both natively scrollable widgets and widgets put into a
C<Gtk2::Viewport>.  For a viewport it's the viewport widget which is passed
to the dragger since that's the widget showing a portion of a larger
underlying thing.  (Eg. F<examples/textview.pl> natively or
F<examples/label.pl> and F<examples/layout.pl> in a Viewport or Layout, and
F<examples/vruler.pl> with separately jigged up adjusters.)

Changes to the adjustment value, upper/lower, page size, or the widget
window size are all allowed during a drag.  A change to the value could come
from a keyboard page-up etc.  In all cases the Dragger continues relative to
the new position and will update any "confine" window limits.

=head2 Event Mask

The dragger adds the following events mask bits to the target widget.  It
uses the WidgetEvents mechanism (see L<Gtk2::Ex::WidgetEvents>) so they're
cleaned up if the dragger is destroyed.

    button-press-mask
    button-motion-mask
    button-release-mask

The dragger doesn't itself have a button press handler (at present), rather
an application is expected to start the drag for some button/modifier
combination.  The dragger adds the press mask in readiness for that.

If you want to defer dragger creation until actually needed in a button
press then you must explicitly select the motion and release events
beforehand.  For example,

    # events selected beforehand
    $widget->add_events (['button-press-mask',
                          'button-motion-mask',
                          'button-release-mask']);

    # dragger not created until actually wanted
    sub my_button_press_handler {
      my ($widget, $event) = @_;
      if (some_thing()) {
        require Gtk2::Ex::Dragger;
        $dragger = Gtk2::Ex::Dragger->new (...);
        $dragger->start ($event);
      }
    }

The motion and release masks beforehand are important if the application is
lagged.  It's possible the user has already released when the application
receives the press.  If the release mask wasn't already on then the release
event is not generated.  If you forget those masks then currently the
dragger turns on but then doesn't work and won't turn off (either all the
time, or when lagged, or the first use).

=head1 FUNCTIONS

=over 4

=item C<< Gtk2::Ex::Dragger->new (key=>value, ...) >>

Create and return a new dragger.  Key/value pairs set the following various