++ed by:

1 non-PAUSE user.

Philip Gwyn
and 1 contributors


POE::XUL::Event - A DOM event


    # POEish
    sub xul_Handler {
        my( $self, $event ) = @_[ OBJECT, ARG0 ];
        warn "Event ", $event->name, " on ", $event->target->id;
        $poe_kernel->yield( other_event => $event );

    sub other_event {
        my( $self, $event ) = @_[ OBJECT, EVENT ];
        $event->wrap( sub {
                # ... do work
            } );


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.


name / type / event

    my $name = $event->name;

Accessor that returns the name of the event. Normaly one of "Click", "Change", "Select" or "Pick".


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


Returns the Window node that generated a request. While POE::XUL::Aplication's window() always points to the main window, $event-window()> may point to a sub-window, if the event orginated there.



Defer the event until "handled" is called.


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

$event-done(0)> is better written as $event-defer>.



Mark the current event as completed, and flush any changes from the ChangeManager to the browser. You only have to call this if you called "defer" previously.


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

POE::XUL::Application handlers are already wrapped.


    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.


    $event->response->content_type( 'image/gif' );
    $event->data_response( $data );

Allows you to send any data as a response to an event. Especially useful for <image> with src attribute set to a callback. data_response will set the Content-Length header.


The following events are generated in response to user interaction. The application will attach event listeners to nodes. See "attach" in POE::XUL::Node.


    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.


    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.


    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.


    sub Pick {
        my( $self, $event ) = @_[ OBJECT, ARG0 ];

Called when the users selects a colour in a Colorpicker, Datepicker or other nodes. TODO better doco.


The following events are generated during the life time of the application and do not have an equivalent in the DOM.

Non-POE::XUL::Application events are not automatically handled; event listeners must call $event-handled> when completed.


    sub boot {
        my( $self, $event ) = @_[ OBJECT, ARG0 ];
        Window( ... );

Called when an application instance is first started. There is no node to attach a listener to, however, so this event is posted directly to the application's session.

A boot event does not have a "target" node nor a source /window.

The application's boot handler is expected to create a Window node.


Called when an application closes, that is when the main window closes.

NOT CURRENTLY IMPLEMENTED. See "timeout" in POE::XUL and shutdown.


Called when the browser opens a sub-window. Sub-windows are created with "window-open()"|POE::XUL::Window/open>.

POE::XUL::Application's will have a window opened and available via $event-window>.

    sub connect {
        my( $self, $event ) = @_;

        # add elements to the sub-window
        $event->window->appendChild( Description( "Hello world!" ) );

        # updated the main window also
        window->getElementById( 'message' )->textNode( 'Sub-window opened' );

Other applications will need to create the POE::XUL::Window themselves. $event-window> will be the window ID as passed to "window-open()">.

    sub connect {
        my( $self, $event ) = @_[ OBJECT, ARG0 ];
        my $winID = $event->window;
        # create and popuplate the sub-window
        my $win = POE::XUL::Window( id=>$win, 
                                    Description( "Hello world!" ) 


Called when the users closes a sub-window.

$event-window> is the sub-window node.

POE::XUL::Application's will have the sub-window node closed when disconnect returns.

    sub disconnect {
        my( $self, $event ) = @_;
        my $winID = $event->window->id;
        window->getElementById( 'message' )
                    ->textNode( "Closed window $winID" );

Other applications must get rid of the sub-window explicitly.

    sub disconnect {
        my( $self, $event ) = @_[ OBJECT, ARG0 ];
        $event->window( undef() );


Philip Gwyn <gwyn-at-cpan.org>


Based on XUL::Node::Event by Ran Eilam.


Copyright 2007-2010 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.


perl(1), POE::XUL, POE::XUL::ChangeManager.