/ 
POE-XUL-0.0300
River stage one • 1 direct dependent • 1 total dependent
/ POE::XUL::Event

NAME

POE::XUL::Event - A DOM event

SYNOPSIS

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

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

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

window

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

$event->defer;

Defer the event until "handled" is called.

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.

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

handled

$event->handled;

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.

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.

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

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

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

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.

APPLICATION EVENTS

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.

boot

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

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.

close

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

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

connect

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!" ) 
                              );
    $event->handled;
}

disconnect

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->destroy;
    $event->window( undef() );
    $event->handled;
}

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.