NAME

Gtk2::Ex::WidgetEvents -- event mask merging for widgets

SYNOPSIS

 use Gtk2::Ex::WidgetEvents;
 my $wm = Gtk2::Ex::WidgetEvents->new ($widget, ['motion-notify-mask']);

 my $we = Gtk2::Ex::WidgetEvents->new ($widget);
 $we->add (['motion-notify-mask','exposure-mask']);
 $we->remove ('exposure-mask');

DESCRIPTION

WidgetEvents represents an event mask wanted on a particular widget for an add-on feature or semi-independent widget component. The event mask on the widget's window is the union of WidgetEvents masks and the widget's base mask.

The plain GtkWidget add_events is geared towards permanent additions to the event mask. Often this is enough. But for removing mask bits to clean up after a widget add-on it's important to check whether anyone else is still interested in those events. WidgetEvents keeps track of that.

Turning event mask bits on and off is mostly a matter of optimization. For example it does no great harm to have mouse motion events left on, but it's wasteful. Sometimes it's important for event propagation rules to have an event turned off when unwanted, so for example a button press can go up to a parent window instead.

FUNCTIONS

In the following functions $mask can be any of the usual Glib flags forms, meaning an actual Gtk2::Gdk::EventMask object, an arrayref of flag name strings, or a single flag name string (see "This Is Now That" in Glib).

$wevents = Gtk2::Ex::WidgetEvents->new ($widget)

$wevents = Gtk2::Ex::WidgetEvents->new ($widget, $mask)

Create a new WidgetEvents object which adds $mask to $widget. $mask can be omitted to start a WidgetEvents with no mask bits.

    $wevents = Gtk2::Ex::WidgetEvents->new
                 ($widget, ['button-press-mask']);

The $wevents object only keeps a weak reference to the given $widget, which means it's safe to keep it in the widget's instance data without creating a circular reference.

$wevents->add ($mask)

Add $mask events to those already selected by $wevents. The target widget's window is updated immediately if it's realized.

    $wevents->add (['enter-notify-mask', 'leave-notify-mask']);

$wevents->remove ($mask)

Remove $mask events from those selected by $wevents. The target widget's window is updated immediately if it's realized and if nobody else is interested in each $mask bit.

    $wevents->remove (['enter-notify-mask', 'leave-notify-mask']);

OTHER NOTES

The event mask for a widget window comes from flags coded into the widget implementation plus those in the widget events property. The hard coded flags are normally for a widget's builtin features, and the events property is extras wanted by external code. The $widget->add_events method extends the events property.

WidgetEvents notices both of these on a window and takes them as a base set of event mask bits. The base flags are always left installed. Additional bits wanted or not by WidgetEvents objects are then set or cleared.

SEE ALSO

Gtk2::Widget, Gtk2::Gdk::Window, Gtk2::Ex::WidgetCursor

HOME PAGE

http://user42.tuxfamily.org/gtk2-ex-widgetbits/index.html

LICENSE

Copyright 2008, 2009, 2010, 2011, 2012 Kevin Ryde

Gtk2-Ex-WidgetBits 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-WidgetBits 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-WidgetBits. If not, see http://www.gnu.org/licenses/.