NAME
POE::XUL::Event - A DOM event
SYNOPSIS
sub xul_Handler {
my( $self, $event ) = @_[ OBJECT, EVENT ];
warn "Event ", $event->name, " on ", $event->target->id;
$event->done( 0 );
$poe_kernel->yield( other_event => $event );
}
sub other_event {
my( $self, $event ) = @_[ OBJECT, EVENT ];
$event->wrap( sub {
# ... do work
$event->finish;
} );
}DESCRIPTION
User interaction with the browser's DOM may provoke a DOM event. These events are handled by the Javascript client library, which will send them to the POE::XUL server. POE::XUL encapsulates the event as a POE::XUL::Event object. This object associates an application's POE::XUL::Nodes with the application's POE::XUL::ChangeManager.
First, the ChangeManager handles all side-effects of an event, such as setting the target node's value attribute.
Next, if there is a listener defined for the event, further execution is wrappedso that any changes to a Node will be seen by the ChangeManager and the listener is called.
Note that POE::XUL::Events to not bubble up the DOM tree like DOM events do.
METHODS
name / type / event
my $name = $event->name;Accessor that returns the name of the event. Normaly one of "Click", "Change", "Select" or "Pick".
SID
my $SID = $event->SID;
my $instance = $heap->{ $SID };Returns the session ID of the current application instance. This is roughly equivalent to a PID.
target / source
my $node = $event->target;Returns the POE::XUL::Node that was the target of the event. For Click this is the a Button, for Change, a TextBox, for Select, the node you attached the event (either RadioGroup, Radio MenuList or MenuItem).
done
$event->done( $state );
$state = $event->done;Mark the current event as completed. Or not. Initially, an event is marked as completed. If you wish to defer the event to another POE state, you may set done to 0, and then call "finish" later.
finish
$event->finish;Mark the current event as completed, and flush any changes from the ChangeManager to the browser. You only have to call this if you set "done" to 0 perviously.
wrap
$event->wrap( $coderef );Wrap a coderef in this event. This has 2 effects:
First, activates the application's ChangeManager, so that any new or modified POE::XUL::Node are seen by it.
Second, if the coderef dies, the error message is displayed in the browser.
flushed
die "Too late!" if $event->flushed;Returns true if the current event has already been flushed to the browser. Because POE::XUL uses a synchronous-event-based model, an event may only be flushed once. This, however, should change later at some point.
DOM EVENTS
Click
sub Click {
my( $self, $event ) = @_[ OBJECT, ARG0 ];
my $button = $event->source;
}The most important event; most action in the application will be in reaction to the user clicking a button or other control.
Change
sub Change {
my( $self, $event ) = @_[ OBJECT, ARG0 ];
my $node = $event->source;
my $value = $event->value;
}A less important event, Change is called when the value of a TextBox has changed. The application does not have to update the source node's value; this is a side-effect handled by the ChangeManager.
Select
sub Select {
my( $self, $event ) = @_[ OBJECT, ARG0 ];
my $list = $event->source;
my $selected = $list->getItemAtIndex( $list->selectIndex );
my $value = $selected->value;
}This event happens when a user selects an item in a menulist, radiogroup, list or other. The event may also be attached to the menulist or radiogroup itself.
The target node will be the menulist or radiogroup. These node's selected is set as a side-effect by the ChangeManager.
Pick
sub Pick {
my( $self, $event ) = @_[ OBJECT, ARG0 ];
}Called when the users selects a colour in a Colorpicker, Datepicker or other nodes. TODO better doco.
AUTHOR
Philip Gwyn <gwyn-at-cpan.org>
CREDITS
Based on XUL::Node::Event by Ran Eilam.
COPYRIGHT AND LICENSE
Copyright 2007 by Philip Gwyn. All rights reserved;
Copyright 2003-2004 Ran Eilam. All rights reserved.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
SEE ALSO
perl(1), POE::XUL, POE::XUL::ChangeManager.