NAME

Gtk2::Ex::SyncCall -- server sync callback

SYNOPSIS

 use Gtk2::Ex::SyncCall;
 Gtk2::Ex::SyncCall->sync ($widget, sub { some code; });

DESCRIPTION

Gtk2::Ex::SyncCall sends a synchronizing request to the X server and calls back to your code when the response is returned. This is like $display->sync() (see Gtk2::Gdk::Display), but done as a callback instead of blocking.

A sync like this is a good way to wait for the server to finish doing drawing or similar you've already sent, before attempting more. It's up to you to choose a good point in your program to do that, but the aim will be not to hammer the server with more animation, updating text, window sizing or whatever than it can keep up with.

Implementation

SyncCall is done with a property change on the given $widget window, which means the widget must be realized. The setups on that widget are kept ready for further syncs on that same display. An unrealize or destroy of the widget will call pending callbacks and then reset ready for a different widget on subsequent syncs.

It's a good idea if $widget isn't a top-level Gtk2::Window widget, because generally the window manager listens for property changes on that. The property name "Gtk2::Ex::SyncCall" will be ignored by the window manager, but it's a little wasteful for it to see unnecessary change events.

(There's various alternatives to this approach. Something not directly involving a widget could be better, the widget then only indicating the target display.)

FUNCTIONS

Gtk2::Ex::SyncCall->sync ($widget, $coderef)

Gtk2::Ex::SyncCall->sync ($widget, $coderef, $userdata)

Send a synchronizing message to the X server and when the server replies call

    &$coderef ($userdata)

$widget must be realized (ie. $widget->realize()). $coderef is called just once.

Multiple sync calls to the same display are collected up so just one synchronising message is sent, with all the callbacks then done when the one reply comes back.

Within a callback a new sync can be initiated. This results in a new synchronising message sent to the server and the new callback runs when the reply is received. Chained syncs like this arise quite naturally if you've got an animation or similar which is being held back by the speed of the server.

Error Handling

If $coderef dies the error is trapped by the usual Glib main loop exception handler mechanism (see "EXCEPTIONS" in Glib). Currently however an error in one sync callback kills all the rest too. Perhaps this will change.

SEE ALSO

Gtk2::Widget, Gtk2::Gdk::Display, Gtk2::Ex::WidgetBits

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