=head1 NAME

Mozilla::DOM::KeyEvent

=head1 DESCRIPTION

The second argument of GtkMozEmbed's dom_key_* signal handlers will be a
Mozilla::DOM::KeyEvent object, which is a wrapper around an instance
of Mozilla's nsIDOMKeyEvent interface. This inherits from
L<UIEvent|Mozilla::DOM::UIEvent>.

Note: although <DOMImplementation|Mozilla::DOM::DOMImplementation>'s
HasFeature('KeyEvents', '2.0') (and '3.0' and '') claimed (on my
system) that KeyEvents were not supported, I found that you can in fact
do key events.

The following constants are available to be compared with L</GetKeyCode>.
You can access these either through the (mouse or key) event object,
like $event->DOM_VK_TAB, export them all with
C<use Mozilla::DOM::KeyEvent qw(:keycodes)>, or export them individually.

=over 4

=item DOM_VK_CANCEL

=item DOM_VK_HELP

=item DOM_VK_BACK_SPACE

=item DOM_VK_TAB

=item DOM_VK_CLEAR

=item DOM_VK_RETURN

=item DOM_VK_ENTER

=item DOM_VK_SHIFT

=item DOM_VK_CONTROL

=item DOM_VK_ALT

=item DOM_VK_PAUSE

=item DOM_VK_CAPS_LOCK

=item DOM_VK_ESCAPE

=item DOM_VK_SPACE

=item DOM_VK_PAGE_UP

=item DOM_VK_PAGE_DOWN

=item DOM_VK_END

=item DOM_VK_HOME

=item DOM_VK_LEFT

=item DOM_VK_UP

=item DOM_VK_RIGHT

=item DOM_VK_DOWN

=item DOM_VK_PRINTSCREEN

=item DOM_VK_INSERT

=item DOM_VK_DELETE

=item DOM_VK_x, where x = 0 - 9

=item DOM_VK_SEMICOLON

=item DOM_VK_EQUALS

=item DOM_VK_x, where x = A - Z

=item DOM_VK_CONTEXT_MENU

=item DOM_VK_NUMPADx, where x = 0 - 9

=item DOM_VK_MULTIPLY

=item DOM_VK_ADD

=item DOM_VK_SEPARATOR

=item DOM_VK_SUBTRACT

=item DOM_VK_DECIMAL

=item DOM_VK_DIVIDE

=item DOM_VK_Fx, where x = 1 - 24

=item DOM_VK_NUM_LOCK

=item DOM_VK_SCROLL_LOCK

=item DOM_VK_COMMA

=item DOM_VK_PERIOD

=item DOM_VK_SLASH

=item DOM_VK_BACK_QUOTE

=item DOM_VK_OPEN_BRACKET

=item DOM_VK_BACK_SLASH

=item DOM_VK_CLOSE_BRACKET

=item DOM_VK_QUOTE

=item DOM_VK_META

=back

=head1 CLASS METHODS

=head2 $iid = Mozilla::DOM::KeyEvent->B<GetIID>()

Pass this to QueryInterface.

=head1 METHODS

=head2 $bool = $event->B<GetAltKey>

=over

This function returns true if the Alt key was held down
when the key event occured. (Note: I found this to not
be strictly true.)

=back

=head2 $char_code = $event->B<GetCharCode>

=over

This function gets the character code, which is the Unicode number
representing that character (e.g. 'a' is 97). For example, you could
pass this number to the `chr' function in Perl.

=back

=head2 $bool = $event->B<GetCtrlKey>

=over

This function returns true if the Ctrl key was held down
when the key event occured.

=back

=head2 $key_code = $event->B<GetKeyCode>

=over

This function gets the key code for "special" keys, such as the function
keys (e.g., F3), caps lock, right arrow, etc.

=back

=head2 $bool = $event->B<GetMetaKey>

=over

This function returns true if the Meta key was held down
when the key event occured.

=back

=head2 $bool = $event->B<GetShiftKey>

=over

This function returns true if the Shift key was held down
when the key event occured.

=back

=head2 $event->B<InitKeyEvent>($eventType, $canbubble, $cancelable, $ctrlkey, $altkey, $shiftkey, $metakey, $keycode, $charcode)

=over

=over

=item * $eventtype (string)

=item * $canbubble (boolean)

=item * $cancelable (boolean)

=item * $ctrlkey (boolean)

=item * $altkey (boolean)

=item * $shiftkey (boolean)

=item * $metakey (boolean)

=item * $keycode (integer (long))

=item * $charcode (integer (long))

=back

See L<Event::InitEvent|Mozilla::DOM::Event/InitEvent> for more
information. This method is basically the same as L<InitEvent>,
but with six (seven normally) extra arguments.
(XXX: add docs for args)

Note: I don't see how you can Create or QueryInterface an AbstractView,
and trying to pass in C<0> or C<undef> was just causing a segfault,
so I've omitted what would normally be the 4th argument of this method.
If someone can explain why you'd need it and how you'd use it,
then I can put it back in.

=back

=head1 SEE ALSO

L<Mozilla::DOM>, L<F<E<sol>usrE<sol>includeE<sol>mozillaE<sol>nsIDOMKeyEvent.h>>, L<sections 1.7.4 and Appendix A of the DOM level 3 specification>

=head1 COPYRIGHT

Copyright (C) 2005, Scott Lanning

This software is licensed under the LGPL.  See L<Mozilla::DOM> for a full notice.

=cut
