POE::XUL::Application - Base class for POE::XUL application objects
package My::Application; use strict; use warnings; use POE::XUL::Node; use base qw( POE::XUL::Application ); sub boot { Boot( "Worlds smallest POE::XUL app" ); Window( Description( "Hello world" ) ); }
POE::XUL::Application deals with most of the little details a POE::XUL application would have to deal with. It enforces the API contract, as it were.
It also provides POE::XUL::Application works hand in hand with POE::XUL::Session to provide some advanced features.
POE::XUL::Application exports 2 very unfull functions.
Returns the main window node. This is similar to how JS DOM code always has a window object available. Obviously, window() returns undef() before you create the node in "boot".
window()
my $node = window->getElementById( $id ); window->appendChild( $new_node );
Returns the POE::XUL::Session delegate object. This is analogous to JS DOM's global browser object.
browser
$SID = server->SID; $poe_kernel->post( server->session, 'some_event' );
This convienient package method will create a POE::Component::XUL instance. It is provided so that mutter short code mutter.
POE::XUL::Application->create( 'MyName' );
Create a new POE event handler. These handlers may be used by other POE components, POE::Wheel or as node event listeners.
$self->createHandler( 'some_method' ); $node->attach( 'some_method' ); $self->createHandler( 'Event' => 'event_handler' ); $node->attach( 'Click' ); # auto-creates the necessary handler
Because POE::XUL::Application uses POE::XUL::Session, the event handler calling semantics are the same as regular perl method invocation:
sub some_method { my( $self, $arg1, $arg2 ) = @_; # and not @_[ OBJECT, ARG0, ARG1 ]; }
Removes the POE event handler.
Because createHandler and removeHandler are small wrappers around "state" in POE::Kernel, it is possible for you to remove event handlers that are necessary for the normal functioning of the application:
$self->removeHandler( 'shutdown' ); # pain!
SO DON'T DO THAT.
POE::XUL::Application handles most events for you. You will need to define a handler for "boot", but that is it. All the POE::XUL events are still available if you need them as object methods.
You will want to set a boot message and create POE event handlers in boot().
boot()
sub boot { my( $self, $event ) = @_; Boot( $boot_message ); Window( ... ); }
Note that the event is automatically handled() after the boot method returns.
Furthur events handlers may be defined
sub timeout { my( $self ) = @_; # Time, gentlemen, please. }
Called after the application has been inactive (no events from the client) for longer then the timeout value. No action is required.
timeout
sub timeout { my( $self ) = @_; # Remove any user-created POE references }
Posted when it is time to delete an application instance. This is either when the instance has timed-out, or when the server is shutting down.
The session is expected to remove all references (aliases, files, extrefs, ...) so that the POE kernel may GC it.
Attaching a listener to a node will auto-create the event handler if nessary. The event is mapped to one of the method names, in order:
The method name you provide to $node-attach>.
$node-
A method name based on the event name and the node's ID. Non-world (ie \W) characters in the ID are converted to _
\W
The event's name.
So, the following code:
my $node = Button( id=>'my-button' ); $node->attach( Click => 'method' );
Attempt be mapped to one of the following 3 methods:
$self->method() $self->xul_Click_my_button() $self->Click()
You may also attach to an event without naming a method:
my $node = Button( id=>'B1' ); $node->attach( 'Click' ); # Maps to : $self->xul_Click_B1 or $self->Click;
Of course, your event handler may be a coderef:
$node->attach( Click => sub { some code here } );
POE::XUL::Applications may use the temporary window returned by "open" in POE::XUL::Window to set event handlers to something other then the default object methods.
$Twin = window->open( 'subwin1' ); $Twin->attach( 'Connect' ); # maps to xul_Connect_subwin1, see above $Twin->attach( 'Disconnect' => 'some_method' );
Window related events are:
Posted when a new sub-window has been created.
The sub-window's node has already been created and is available in $event-window>.
$event-
Note that the event is automatically handled() after the Connect handler returns. If you need to run code that would defer the response, you must created an element who's XBL would then post a furthur, edeferable event. TODO how ackward!
See also "connect" in POE::XUL::Event.
Posted from the main window when a sub-window is closed.
When this handler returns, the sub-window node and all its child nodes will be deleted.
See also "disconnect" in POE::XUL::Event.
Note that the event is automatically handled() after the Disconnect handler returns.
POE::XUL is still a work in progress. Things that aren't done:
Allow defereable connect and disconnect events.
Philip Gwyn <gwyn-at-cpan.org>
Copyright 2007-2010 by Philip Gwyn. 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::Event, POE::XUL::Node, POE::XUL::Session.
http://www.prototypejs.org/.
To install POE::XUL::RDF, copy and paste the appropriate command in to your terminal.
cpanm
cpanm POE::XUL::RDF
CPAN shell
perl -MCPAN -e shell install POE::XUL::RDF
For more information on module installation, please visit the detailed CPAN module installation guide.