NAME

       Padre::Wx::Role::Idle - Role for delaying method calls until idle time

SYNOPSIS

         # Manually schedule some work on idle
         $self->idle_method( my_method => 'param' );

         # Delay work until idle time in response to an event
         Wx::Event::EVT_TREE_ITEM_ACTIVATED(
             $self,
             $self,
             sub {
                   shift->idle_method( my_method => 'param' );
             },
         );

         # The handler for the event
         sub my_method {
             my $self  = shift;
             my $param = shift;

             # Functionality is implemented here
         }

DESCRIPTION

       This role provides a standard mechanism for delaying method call dispatch until idle time.

       The role maintains a dispatch queue for each object, binds or unbinds an "EVT_IDLE"
       handler depending on whether there is anything in the queue, and dispatches one method
       from the queue each time idle is fired (to ensure that any large series of tasks will be
       spread out over time instead of all blocking at once on the first idle event).

METHODS

   idle_method
         $self->idle_method( method_name => @params );

       The "idle_method" method is used to schedule a method for execution at idle time.

       The first parameter to the call should be the name of the method to be called on this
       object. The method will be checked before it is added to the queue to ensure that it
       exists.

       Any remaining parameters to "idle_method" will be passed through as parameters to the
       specified method call.

       Please note that Wx::Event objects must not be used as parameters to this method. While
       the Perl level object will survive until idle time, the underlying Wx event structure for
       the event will no longer exist, and any attempt to call a method on the event object will
       segfault Perl.

       You should unpack any information you need from the Wx::Event before making the call to
       "idle_method" and pass it through as data instead.

   idle_handler
       The "idle_handler" method is called internally to dispatch the next method in the idle
       queue.

       It will dispatch one and only one call on the queue, returning true if there are any
       remaining calls on the queue of false if the queue is empty.

       While you generally should not need to know about this method, there are two ways to use
       this method to influence the behaviour of the role.

       Firstly, the method call be called directly to trigger the immediate dispatch of an idle
       method without waiting for the "EVT_IDLE" event to fire.

       Secondly, you could overload the "idle_handler" method to add extra functionality that
       should be run any time a delayed call of any other type is made.

COPYRIGHT & LICENSE

       Copyright 2008-2013 The Padre development team as listed in Padre.pm.

       This program is free software; you can redistribute it and/or modify it under the same
       terms as Perl 5 itself.

       The full text of the license can be found in the LICENSE file included with this module.