/ 
POE-XUL-0.0405
River stage one • 1 direct dependent • 1 total dependent
/ POE::XUL::Application

NAME

POE::XUL::Application - Base class for POE::XUL application objects

SYNOPSIS

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" ) );
}

DESCRIPTION

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.

FUNCTIONS

POE::XUL::Application exports 2 very unfull functions.

window

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

my $node = window->getElementById( $id );
window->appendChild( $new_node );

server

Returns the POE::XUL::Session delegate object. This is analogous to JS DOM's global browser object.

$SID = server->SID;
$poe_kernel->post( server->session, 'some_event' );

METHODS

create

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' );

createHandler

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 ];
}

removeHandler

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 EVENTS

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.

boot

You will want to set a boot message and create POE event handlers in 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

timeout

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.

shutdown

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.

DOM EVENTS

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:

  1. The method name you provide to $node-attach>.

  2. A method name based on the event name and the node's ID. Non-world (ie \W) characters in the ID are converted to _

  3. 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 } );

MULTIPLE WINDOWS

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:

Connect

Posted when a new sub-window has been created.

The sub-window's node has already been created and is available in $event-window>.

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.

Disconnect

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.

TODO

POE::XUL is still a work in progress. Things that aren't done:

connect/disconnect

Allow defereable connect and disconnect events.

AUTHOR

Philip Gwyn <gwyn-at-cpan.org>

CREDITS

COPYRIGHT AND LICENSE

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

SEE ALSO

perl(1), POE::XUL, POE::XUL::Event, POE::XUL::Node, POE::XUL::Session.

http://www.prototypejs.org/.