adesklets.events_handler
index
events_handler.py

adesklets events handler module

 
Modules
        
posix_signal
re
string
sys
types
 
Classes
        
_Events_handler( adesklets.signal_handler.Signal_handler, adesklets.singleton._States)
Events_handler( adesklets.singleton._Singleton, _Events_handler)
adesklets.singleton._Singleton
Events_handler( adesklets.singleton._Singleton, _Events_handler)
 
class Events_handler(adesklets.singleton._Singleton, _Events_handler)
    High-level events handler
 
Made to be used as a base class in applications wanting to catch
adesklets related events. 
 
class My_events_handler(Events_handler):
    def __init__(self):
         Events_handler.__init__(self)
    def __del__(self):
         Events_handler.__del__(self)
    ...
 
from there, you just have to redefine the methods you are interested in,
choosing between ready(), quit(), alarm(), menu_fire(),  background_grab(),
button_press(),  button_release(), motion_notify(),  enter_notify() and
leave_notify() - see short descriptions below.
 
As soon as you will instanciate an object from your class, all
events corresponding to functions you 'overloaded' will
automatically be caugth and will cause your object methods to be
appropriately called.
 
Note 1: all methods events but  alarm() are protected critical
sections, if POSIX reliable signals are supported on your
architecture. This means they will not get interrupted by normal
adesklets operation. No adesklets events will ever be lost either:
they are garanteed to be all processed in the order they arrived,
except for one case: quit() signal is always processed right after
the current event method returns.
 
    WARNING 1: Of course, this means that events are not guaranteed
    to be processed as they arrive: they can be arbitrarily delayed
    since former events processing could have taken any amount of time.
    This is the reason you are encouraged to take advantage of the
    'delayed' flag passed to most methods (and to write quick to compute
    methods!). For instance, depending of your desklet, you may want
    to ignore all motion_notify events that were not processed right
    away, since they are no longuer relevant for giving quick feedback
    to the user.
 
    WARNING 2: As stated above, the  alarm() method, used for periodic
    action, could get interrupted. You are responsible for providing
    proper exception recovery in case of problem with IO, for instance.
    Alternatively, you can use the posix_signal API, already imported,
    to make your own signal management, or use the  block()
    unblock() methods provided. Please note it is probably
    a bad idea to have a long-running  alarm() method blocking signals
    without any possibility of beeing interrupted.
    
Note 2: every time an object from a class deriving from  Events_handler
is instanciated, the content of all communications channel to adesklets
interpreter is flushed.
 
Note 3: for obvious reasons, at most one instance of  Events_handler's
children can exist at any given time.
 
Note 4: when using the python interpreter in interactive mode,
        calls to  Events_handler's functions could block, depending
        of the platform/python version you use. This is due to
        the way python handle access to various streams, including
        stdout and stderr. If this happens to you, there are
        two workarounds:
            - Invoke python with the -u swith or the environment variable
            PYTHONUNBUFFERED=1 - this works many times
            - Avoid interactive mode - directly build a test script
            and run it. :-)
 
Note 5: It you need to (from adesklets 0.3.0), you also have the two
methods Events_handler::get_events() and  Events_handler::set_events()
that give you an easy way to change at run time what events are catched,
and using what unbounded methods.
 
This is especially convenient if you want to program interruptable
timed 'effects' (see test/fading.py), while not having them
interrupetd by the same set of events you normally use.
 
 
Method resolution order:
Events_handler
adesklets.singleton._Singleton
_Events_handler
adesklets.signal_handler.Signal_handler
adesklets.singleton._States

Methods defined here:
__del__(self)
__init__(self)
alarm(self)
Called periodically. Usefull to perform any perdiodic operation.
Delay until next call is determined from return value (which must be
an integer), in seconds (zero means not to reschedule). First call is
automatically scheduled right after the  ready() event method returns.
background_grab(self, delayed)
Called whenever adesklets' background image is updated
block(self)
Convenience functions to block signals generated
by adesklets, if supported by your platform
 
WARNING: you never need to call it for any event but  alarm()
button_press(self, delayed, x, y, button)
Called whenever a button is pressed
button_release(self, delayed, x, y, button)
Called whenever a button is released
enter_notify(self, delayed, x, y)
Called whenever pointer enters the window
get_events(self)
This returns a dictionary of all events catched by the desklet
at the time of calling. 
 
For reliable use, it should always be called when signals are blocked
(See Events_handler class description above)
leave_notify(self, delayed, x, y)
Called whenever pointer leaves the window
menu_fire(self, delayed, menu_id, item)
Called whenever a catchable menu selection returns.
`item' may be None if no selection was made.
motion_notify(self, delayed, x, y)
Called whenever pointer is moved inside the window
pause(self)
Put python intepreter to sleep forever, only waking up to
process events.
quit(self)
Called only once when adesklets is about to quit:
the python interpreter will exit right after this function returns.
 
Note: this function is guaranteed not to be interrupted
by others signals from adesklets, but SIGKILL, whether you have POSIX
reliable signal support or not.
ready(self)
Called only once when adesklets is ready to receive command
set_events(self, events)
This overrides the catched events using a dictionnary compatible to
the one sent back by  Events_handler::get_events().
 
This gives the desklet programmer a way to dynamically change
what signals are caught, which may be useful when working
with indirect mode programming (adesklets.start() command and others
alike).
unblock(self)
Convenience functions to block signals generated
by adesklets, if supported by your platform
 
WARNING: you never need to call it for any event but  alarm()

Methods inherited from adesklets.signal_handler.Signal_handler:
clear(self, my_signals=None)

Data and other attributes inherited from adesklets.signal_handler.Signal_handler:
func = <built-in function signal>
signal(sig, action) -> action
 
Set the action for the given signal.  The action can be SIG_DFL,
SIG_IGN, or a callable Python object.  The previous action is
returned.  See getsignal() for possible return values.
 
*** IMPORTANT NOTICE ***
A signal handler function is called with two arguments:
the first is the signal number, the second is the interrupted stack frame.
ignore = 1
posix_signal = <module 'posix_signal' from '/usr/lib/python2.4/site-packages/posix_signal.so'>