view release on metacpan or  search on metacpan

lib/App/XUL.pm  view on Meta::CPAN

If debug is set to 1, a jsconsole is started together with the application
which can be used to debugging messages. The default is debug = 0, so no
jsconsole is started.

=head2 Creating interface components

=head2 Handling events

Events can be handled by attaching an event handler to
an interface component. Event handlers can either be written
in Perl or in JavaScript.

Here is an example of a Perl event handler that reacts on
the mouse click of a button:

  Button(label => 'click', oncommand => sub {
    # access environment and evtl. change it
    # ...
  });

Here is a similar JavaScript event handler:

  Button(id => 'btn', label => 'click', oncommand => <<EOFJS);
    // here is some js code
    $('btn').update('Alrighty!');
  EOFJS

JavaScript event handlers are executed faster than the Perl ones,
due to the architecture (see below).


=head2 Changing the environment from Perl

This refers to all activities within Perl event handlers that
change the DOM of the XUL application. An example is the
addition of another window, the insertion or update of a button
label or the deletion of a style attribute etc.

Some things are important here:

=over 1

=item Changes happen on the server side first and are
  transferred to the client side (the XUL application)
  when the event handler terminates.

=item To manually transfer the latest changes to the client side
  use the PUSH() function.

=back

=head4 Get (XML) element

The first step of changing the DOM is to get an element on which
the changes are applied. The ID() function is used for that:

  my $elem = ID('main');

The ID() function only works WHILE the application is running.
Any changes to the object returned by the ID() function are transferred
immedietly (asynchronous) to the XUL application/client.

=head4 Get child (XML) elements

  my $child1 = ID('main')->child(0);
  my $numchildren = ID('main')->numchildren();

=head4 Create/insert/append (XML) elements

  my $e = Div(id => 'container', 'style' => 'background:black', 
            Button(label => 'click'));
  ID('main')->insert($e, 'end'); # end|start|...

=head4 Edit (XML) element

  ID('container')->style('background:red')->content(Span('Hello!'));

=head4 Delete/remove (XML) element

  my $e = ID('container')->remove();

=head4 Call event handler on (XML) element

  ID('container')->click();

=head4 Register event handler on (XML) element

  ID('container')->oncommand(sub {
    # do stuff here
    # ...
  });

=head4 Un-register event handler on (XML) element

  ID('container')->oncommand(undef);
            

=head2 EXPORT

None by default.

=head1 INTERNALS

This chapter is meant for informational purposes. Sometimes it is nessessary
to know how things are implemented to decide, for example, if you should
use a Perl or a JavaScript event handler etc.

App::XUL is client-server based. The client is the instance of
XULRunner running and the server is a pure Perl based webserver
that reacts on the events that are triggered by the XUL interface.

=head3 Event handling

Essentially all events are dispatched from XUL as Ajax calls to the
Perl webserver which handles the event, makes changes to the DOM etc.
The changes are then transferred back to the XUL app where they
are applied.

Here is a rough workflow for event handling:

=over 1