view release on metacpan or  search on metacpan

lib/POE/XUL/Node.pm  view on Meta::CPAN

=head1 METHODS

=head2 createTextNode

Creates and populates a L<POE::XUL::TextNode>.  Returns the new node.

    my $tn = window->createTextNode( 'Some text' );

=head2 textNode

Sets or changes the text of a node, such as
L<description|http://developer.mozilla.org/en/docs/XUL:description>. If the
node has multiple children (aka <i>mixed-mode</i>) then it will replace the
first textNode it finds.  If there are none, it will append a new text node.
See L<POE::XUL::TextNode>.

    my $d = Description( textNode => 'Hello world!' );
    $d->textNode( 'This is different' );


=head2 children

Find a given node's child nodes.  Returns array in array context, an array
reference in scalar context.  Modifying the arrayref will NOT modify the
node's list of children.

    foreach my $node ( $box->children ) {
        # ...
    }

=head2 child_count

Returns the number of child nodes of an node.

=head2 hasChildNodes

Returns true if a node has child nodes.

=head2 add_child

    $parent->add_child( $node, $index );

=head2 appendChild

    $parent->appendChild( $node );

=head2 firstChild / first_child

    my $node = $parent->firstChild;

=head2 get_child

    my $node = $parent->get_child( $index );

Use <POE::XUL::Window/getElementById> to find a node by its C<id>.

=head2 getItemAtIndex / get_item

    my $node = $menu->getItemAtIndex( $index );

Like L</get_child>, but works for C<menulist> and C<menupopup>.

=head2 lastChild / last_child

    my $node = $parent->lastChild;

=head2 removeChild / remove_child

    $parent->removeChild( $node );
    $parent->removeChild( $index );

=head2 replaceChild

    $parent->replaceChild( $old, $new );

=head2 attributes

    my %hash = $node->attributes;
    my $hashref = $node->attributes;

Note that even if you manipulate C<$hashref> directly, changes will not be
mirrored in the node.

=head2 getAttribute / get_attribute

    my $value = $node->getAttribute( $name );

=head2 setAttribute / set_attribute

    $node->setAttribute( $name => $value );

=head2 removeAttribute / remove_attribute

    $node->removeAttribute( $name );



=head2 hide

    $node->hide;

Syntatic sugar that does the following:

    $node->style->display( 'none' );

=head2 show

    $node->show;

Syntatic sugar that does the following:

    $node->style->display( '' );

=head2 attach

    $node->attach( $Event => $listener );
    $node->attach( $Event => $coderef );
    $node->attach( $Event );

Attaches an event listener to a node.  When C<$Event> happens (normaly in
response to a DOM event) the C<$poe_event> is posted to the application
session.  Alternatively, the C<$coderef> is called.  In both cases, an
L<POE::XUL::Event> object is passed as the first parameter.  C<$poe_event>
defaults to C<$Event>.

C<attach()> will auto-create handlers for C<POE::XUL::Application>.

=head2 detach

    $node->detach( $Event );

Removes the event listener for C<$Event>.  Auto-created handlers are
currently not removed.

=head2 event

    my $listener = $node->event( $Event );

Gets the node's event listener for C<$Event>.  A listener is either a
coderef, or the name of a POE event handler in the application's session. 
Application code will rarely need to call this method.

=head2 dispose / distroy

Calls C<dispose> on all the child nodes, and drops all events.

=head2 as_xml

Returns this element and all its child elements as an unindented XML string.
Useful for debuging.

=head1 LIMITATIONS

=over 4

=item *

Some elements are not supported yet: tree, popup.

=item *

Some DOM features are not supported yet:

  * multiple selections
  * node disposal
  * color picker will not fire events if type is set to button
  * equalsize attribute will not work
  * menus with no popups may not show

=item *

Some XUL properties are implemented with XBL.  The front-end attempts to
wait for the XBL to be created before setting the property.  If the object
takes too long, the attribute is set instead.

What this means is that you can't reliably set the properties of freshly
created nodes.

=back


=head1 SEE ALSO

L<POE::XUL>.
L<POE::XUL::Event> presents the list of all possible events.

L<http://developer.mozilla.org/en/docs/XUL>
has a good XUL reference.


=head1 AUTHOR

Philip Gwyn E<lt>gwyn-at-cpan.orgE<gt>

=head1 CREDITS

Based on work by Ran Eilam.

=head1 COPYRIGHT AND LICENSE

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

=cut