=head1 NAME

Gtk - GIMP Toolkit bindings for Perl

=head1 DESCRIPTION

Loads the default modules for the Gtk+ bindings for Perl.
The current bindings are for Gtk version 1.2.

=head1 SYNOPSIS

Be sure to always include these.

=over 4

=item use Gtk;

=item init Gtk;

=item main Gtk;

=back

These are all the methods available from the Gtk class.

=over 4

=item Gtk->check_version(req_maj, req_min, req_micro)

=item Gtk->error(text)

=item Gtk->events_pending()

=item Gtk->exit(status)

=item Gtk->false()

=item Gtk->gc()

=item Gtk->get_current_event()	

=item Gtk->get_event_widget(event)

=item Gtk->grab_add(widget)

=item Gtk->grab_get_current()

=item Gtk->grab_remove(widget)

=item Gtk->idle_add(handler, ...)

=item Gtk->idle_add_priority(priority, handler, ...)

=item Gtk->idle_remove(tag)

=item Gtk->init()

=item Gtk->init_add(handler, ...)

=item Gtk->init_check()

=item Gtk->init_types()

=item Gtk->key_snooper_install(handler, ...)

=item Gtk->key_snooper_remove(tag)

=item Gtk->main()

=item Gtk->main_iteration()

=item Gtk->main_iteration_do(blocking)

=item Gtk->main_level()

=item Gtk->main_quit(...)

=item Gtk->major_version()

=item Gtk->micro_version()

=item Gtk->minor_version()

=item Gtk->mod_init_add(module, handler, ...)

=item Gtk->module_configure(data)

=item Gtk->print(text)

=item Gtk->quit_add(main_level, handler, ...)

=item Gtk->quit_remove(tag)

=item Gtk->set_locale()

=item Gtk->timeout_add(interval, handler, ...)

=item Gtk->timeout_remove(tag)

=item Gtk->true()

=item Gtk->warning(text)

=item Gtk->watch_add(sv, priority, handler, ...)

=item Gtk->watch_remove(tag)

=back

=head1 DETAILS

These are the descriptions of the methods from the Gtk class.

=over 4

=item B<Gtk-E<gt>check_version($major, $minor, $micro)>

The version numbering system used by Gtk consists of three integers, 
sepparated by dots (e.g.  1.2.3).  These are called the I<major>, I<minor>,
and I<micro> releases respectively.  The B<Gtk-E<gt>check_version()> method,
allows you to verify which version of Gtk you are using.

This function returns an empty string if the Gtk+ library is the same as 
the given version, or a string describing the version mismatch.

You should B<not> use this function to check compatibility because all
micro versions should be compatible.

If you wish to check for a compatible version of Gtk+, take a look at 
C<Gtk-E<gt>major_version> and C<Gtk-E<gt>minor_version>.  If you need the 
micro, take a look at C<Gtk-E<gt>micro_version>.

=item B<Gtk-E<gt>error($text)>

Print $text as an error using Gtk+'s output facilities.
This function also exits the program with an error.
C<Gtk-E<gt>error> is similar to Perl's die() function.
C<Gtk-E<gt>error> produces some extra information which can be useful
for debugging or logging.

For example

 Gtk->error("hi");
 Gtk->error("hi\n");

will print

 Wed Aug  7 17:06:35 2002  Gtk-ERROR **: hi at ./prog line 6
 Wed Aug  7 17:06:26 2002  Gtk-ERROR **: hi 

respectively.

Also look at C<Gtk-E<gt>warning> for a similar equivalent to Perl's 
warn() function.

=item B<Gtk-E<gt>events_pending()>

Check if any events are pending. This can be used, together with 
C<Gtk-E<gt>main_iteration()> to update the GUI or invoke timeouts
while we are doing some time intensive computation.  See below.

    # Do some computations.
 	
    while(Gtk->events_pending) {
	Gtk->main_iteration;
    }
 
    # Continue with the computation.

See C<Gtk-E<gt>main_iteration()> for more information.

=item B<Gtk-E<gt>exit($status)>

Terminate the program and return the given exit code ($status) to the caller.
This function will shut down the GUI and free all resources allocated for GTK.

Another alternative is C<Gtk-E<gt>main_quit>.  This method will cause the
innermost main loop return, when this loop regains control.

You should probably use C<Gtk-E<gt>main_quit> to "exit normally" and 
C<Gtk-E<gt>exit> to exit with an error status.

See C<Gtk-E<gt>main> for more information.

=item B<Gtk-E<gt>false()>

This is simply a utility function that always returns FALSE. 
It can be useful on a signal handler for instance.

    use Gtk;
    init Gtk;

    my $window = new Gtk::Widget     "GtkWindow",
                 GtkWindow::type => -toplevel;

    $window->signal_connect( delete_event => sub{Gtk->false});
    $window->signal_connect( destroy => sub{Gtk->main_quit});

    show_all $window;
    main Gtk;

See also C<Gtk-E<gt>true>.

=item B<Gtk-E<gt>gc()>

Perform a garbage collection run.

=item B<Gtk-E<gt>get_current_event()>

Obtains a copy of the event currently being processed by GTK+. For example, 
if you get a "clicked" signal from Gtk::Button, the current event will be the 
Gdk::Event that triggered the "clicked" signal.

=item B<Gtk-E<gt>get_event_widget($event)>

Returns the widget that received the $event originally.

This method can be useful in combination with C<Gtk-E<gt>get_current_event>.

=item B<Gtk-E<gt>grab_add($widget)>

Makes $widget the current grabbed widget. This means that interaction with 
other widgets in the same application is blocked and mouse as well as 
keyboard events are delivered to this widget. 

=item B<Gtk-E<gt>grab_get_current()>

Querries the current grab.  It returns the currently grabbed widget.

B<Warning:> This method currently crashes if there is no widget grabbed.

=item B<Gtk-E<gt>grab_remove(widget)>

Removes the grab from the given widget.  You have to pair calls to 
C<Gtk-E<gt>grab_add()> and C<Gtk-E<gt>grab_remove()>.
You might also consider chaining functions.

    # Remove the grab from whichever widget currently has it.
    Gtk->grab_remove( Gtk->grab_get_current);

=item B<Gtk-E<gt>idle_add($handler, ...)>

An idle handler is a function that gets called when the main loop is
is not busy processing events of higher priority.  The default priority
is rather low.

This function adds an idle handler at the default priority.

The first element is a function reference.  The subsequent elements are 
the parameters to be passed to the function, if any.

If you need to specify the priority, take a look at
C<Gtk-E<gt>idle_add_priority>.

Also look at C<Gtk-E<gt>timeout_add> for an alternative.

=item B<Gtk-E<gt>idle_add_priority($priority, $handler, ...)>

An idle handler is a function that gets called when the main loop is
is not busy processing events of higher priority.  The default priority
is rather low.

This function adds an idle handler at the specified priority.

The first element is the priority (an integer).  The second element is a
function reference.  The subsequent elements are the parameters to be passed
to the function, if any.

Lower values of $priority are higher priorities (easy way to remember: 
your no 1 priority is higher than your no 2 priority).

=item B<Gtk-E<gt>idle_remove($tag)>

An idle handler is a function that gets called when the main loop is
is not busy processing events of higher priority.

This function removes the specified idle handler.

=item B<Gtk-E<gt>init()>

Call this method before using any other Gtk+ functions.  It will initialize
everything needed to operate the toolkit and parses some standard command 
line options out of @ARGV.

B<Note>: This function will terminate your program if it was unable to 
initialize the GUI for some reason. If you want your program to fall back to 
a textual interface you want to call C<Gtk-E<gt>init_check()> instead. 

=item B<Gtk-E<gt>init_add($handler, ...)>

Registers a function to be called when the mainloop is started.
Any additional arguments are passed as parameters to the handler (function
reference).

=item B<Gtk-E<gt>init_check()>

This function does the same work as C<Gtk-E<gt>init> with only a single change:
It does not terminate the program if the GUI can't be initialized. Instead it 
returns FALSE on failure.

This way the application can fall back to some other means of communication 
with the user - for example a curses or command line interface:

    use Gtk;

    if ( Gtk->init_check) {
	# GUI version of the program.
 
    } else {
	# Text-based version of the program.
 
    }

=item B<Gtk-E<gt>init_types()>

=item B<Gtk-E<gt>key_snooper_install($handler, ...)>

Installs a key snooper handler function, which will get called on all key 
events before delivering them normally. 

The function will get a Gtk::Widget, a Gtk::Gdk::Event and any additional
arguments that are passed to this function.  If the function returns TRUE,
the key will B<not> be handed over t othe Gtk internals.

This will be much clearer if you try this program:

    #!/usr/bin/perl -w

    use strict;
    use Gtk;

    init Gtk;

    my $window = new Gtk::Widget     "GtkWindow",
                 GtkWindow::type => -toplevel;

    $window->signal_connect( delete_event => sub{Gtk->false});
    $window->signal_connect( destroy => sub{Gtk->main_quit});

    Gtk->key_snooper_install(\&snooper);

    show_all $window;
    main Gtk;

    sub snooper {
	my ($widget, $event) = @_;
	print "Snoop activated\n";
	for my $key (keys %{$event}) {
		print "Event $key: ",$event->{$key},"\n";
	}
	print "\n";
	return Gtk->false;
    }

We could use a snooper to prevent the user from using the letter "q" or 
capital letters.

    sub snooper {
	my ($widget, $event) = @_;
	if ($event->{string} eq 'q') {
	    return Gtk->true
	}
	# The 'keyval' is the ASCII (or Unicode) value of they key.
	if ($event->{keyval} >= 65 and $event->{keyval} <= 95) {
	   return Gtk->true
	}
	return Gtk->false 
    }

=item B<Gtk-E<gt>key_snooper_remove($tag)>

Removes the key snooper identified by $tag.

See above for more on key snoopers.

=item B<Gtk-E<gt>main()>

Runs the main loop until C<Gtk-E<gt>main_quit> gets called.

Main loops can be nested.  If this is done, C<Gtk-E<gt>main_quit> only
causes the innermost invocation of C<Gtk-E<gt>main> to return.

=item B<Gtk-E<gt>main_iteration()>

Runs a single iteration of the mainloop. If no events are waiting to be 
processed GTK+ will block until the next event is noticed. If you don't want 
to block look at C<Gtk-E<gt>main_iteration_do> or check if any events are 
pending with C<Gtk-E<gt>events_pending> first.

One use of this method, in combination with C<Gtk-E<gt>main_iteration()>,
is to update the GUI while we are doing some time intensive computation.
See below.

    # Do some computations.
 
    while(Gtk->events_pending) {
	Gtk->main_iteration;
    }
        
    # Continue with the computation.

=item B<Gtk-E<gt>main_iteration_do($blocking)>

Runs a single iteration of the mainloop.  It is very similar to
C<Gtk-E<gt>main_iteration>, except that it allows you to specify the blocking
behaviour.

If $blocking is TRUE, and there are no events waiting, this method will 
block until the next event.  In this case it behaves just like
C<Gtk-E<gt>main_iteration>.  If $blocking is FALSE, the function will return
regardless.  See example below.

    if (condition) {
	$blocking = Gtk->false
    } else {
	$blocking = Gtk->true
    }
    Gtk->main_iteration_do($blocking);

Or, since C<Gtk-E<gt>true> and C<Gtk-E<gt>false> are just 1 and 0, we can 
just write:

    Gtk->main_iteration_do( condition );

=item B<Gtk-E<gt>main_level()>

It is possible to have multiple, nested, main loops.  This method returns
the current main loop level (an integer).  

Note: the current main loop level is not necessarily the innermost loop 
level.  Do not assume that this integer is equal to the total number of
levels.

This method can be useful when calling C<Gtk-E<gt>quit_add>.

=item B<Gtk-E<gt>main_quit()>

This method causes the innermost main loop to return, when this loop
regains control.  The typical usage is:

    $window->signal_connect( destroy => Gtk->main_quit);

If you wish to exit immediately, or wish to specify an exit status,
you should look at C<Gtk-E<gt>exit>.

See C<Gtk-E<gt>main> for for information.

=item B<Gtk-E<gt>major_version()>

The version numbering system used by Gtk consists of three integers,
sepparated by dots (e.g.  1.2.3).  These are called the I<major>, I<minor>,
and I<micro> releases respectively.

This method returns the major version.  This can be useful if there are
compatability issues.  For example:

    Gtk->major_version == 2
	or die "This program requires Gtk+ version 2.x"

=item B<Gtk-E<gt>micro_version()>

The version numbering system used by Gtk consists of three integers,
sepparated by dots (e.g.  1.2.3).  These are called the I<major>, I<minor>,
and I<micro> releases respectively.

This method returns the micro version.  All micro versions should be 
compatible.

=item B<Gtk-E<gt>minor_version()>

The version numbering system used by Gtk consists of three integers,
sepparated by dots (e.g.  1.2.3).  These are called the I<major>, I<minor>,
and I<micro> releases respectively.

This method returns the minor version.  This can be useful if there are
compatability issues.  For example.

    Gtk->major_version == 1 and Gtk->minor_version == 2
	or die "This program requires Gtk+ version 1.2"

=item B<Gtk-E<gt>mod_init_add(module, handler, ...)>

=item B<Gtk-E<gt>module_configure(data)>

=item B<Gtk-E<gt>print($text)>

Prints $text to the screen using Gtk's output facilities.  This function
is not as flexible as Perl's own print() and printf() functions, so you
probably don't want to use this one.  This function is included only for
completeness.

C<Gtk-E<gt>print> only accepts a single string as input.

This will work:

  Gtk->print("hello\nworld.\n");

This will B<NOT> work:

  Gtk->print("hello %s\n","world\n");
  Gtk->print("hello ","world\n");

If you wish to send warning messages, take a look at C<Gtk-E<gt>warning>.

=item B<Gtk-E<gt>quit_add($main_level, $handler, ...)>

Registers a function to be called when an instance of the mainloop quits.

Since main loops can be nested, you have to specify in $main_level which
loop the handler (function) applies to.

This method is useful for doing a final cleanup before exitting.  Removing
temporary files, saving the state of the program and the like.

B<Note:> If you want ask "are you sure you want to quit?", this method is 
B<NOT> what you are looking for.  The handler gets called B<after> the 
main loop quits.  Instead, you should connect the delete_event signal to
an appropriate handler.

=item B<Gtk-E<gt>quit_remove($tag)>

Remove the main loop quit handler identified by $tag.  See above for details.  

=item B<Gtk-E<gt>set_locale()>

Initializes internationalization support for GTK+.  This function must be
called before C<Gtk-E<gt>init>.

When Gtk-Perl gets ported to Gtk+ 2.0 there will no longer be any need for
this because this will be done automatically in C<Gtk-E<gt>init>

Changing the locale after GTK+ is initialized may produce inconsistent
results and is not supported.

In detail - sets the current locale according to the program environment. 
This is the same as calling the C library function setlocale (LC_ALL, "") 
but also takes care of the locale specific setup of the windowing system 
used by GDK.

=item B<Gtk-E<gt>timeout_add($interval, $handler, ...)>

Registers a function to be called periodically. $handler will be called 
repeatedly after $interval milliseconds until it returns FALSE at which point 
the timeout is destroyed and will not be called again. 

The additiona arguments are passed to the handler as parameters.

Also look at C<Gtk-E<gt>idle_add> for an alternative.

=item B<Gtk-E<gt>timeout_remove(tag)>

Remove a timeout handler identified by $tag.  See above for details.

=item B<Gtk-E<gt>true()>

This is simply a utility function that always returns TRUE. 
It can be useful on a signal handler for instance.  This example creates
a persistent window (it doesn't close when you click on "close").

    use Gtk;
    init Gtk;

    my $window = new Gtk::Widget     "GtkWindow",
                 GtkWindow::type => -toplevel;
 
    $window->signal_connect( delete_event => sub{Gtk->true});
    $window->signal_connect( destroy => sub{Gtk->main_quit});
 
    show_all $window;
    main Gtk;

See also C<Gtk-E<gt>false>.

=item B<Gtk-E<gt>warning($text)>

Print $text as a warning using Gtk+'s output facilities.  This is similar
to Perl's warn() function.  C<Gtk-E<gt>warning> produces some extra
information which can be useful in debugging or logging.

For example

 Gtk->warning("hi");
 Gtk->warning("hi\n");

will print

 Wed Aug  7 16:58:22 2002 Gtk-WARNING **: hi at ./prog line 6
 Wed Aug  7 16:58:22 2002 Gtk-WARNING **: hi 

respectively.

Also look at C<Gtk-E<gt>error> for a similar equivalent to Perl's die()
function.

=item B<Gtk-E<gt>watch_add(sv, priority, handler, ...)>

=item B<Gtk-E<gt>watch_remove(tag)>

=back

=head1 SEE ALSO

These are the other modules that are also loaded when you C<use Gtk;>

=over 4

=item Gtk::AccelGroup

=item Gtk::AccelLabel

=item Gtk::Accelerator

=item Gtk::Adjustment

=item Gtk::Alignment

=item Gtk::Allocation

=item Gtk::AnchorType

=item Gtk::Arrow

=item Gtk::ArrowType

=item Gtk::AspectFrame

=item Gtk::AttachOptions

=item Gtk::Bin

=item Gtk::Box

=item Gtk::BoxChild

=item Gtk::Button

=item Gtk::ButtonBox

=item Gtk::CList

=item Gtk::CTree

=item Gtk::CTreeNode

=item Gtk::CTreeRow

=item Gtk::Calendar

=item Gtk::CheckButton

=item Gtk::CheckMenuItem

=item Gtk::ColorSelection

=item Gtk::ColorSelectionDialog

=item Gtk::Combo

=item Gtk::Container

=item Gtk::CornerType

=item Gtk::Curve

=item Gtk::Dialog

=item Gtk::DrawingArea

=item Gtk::Editable

=item Gtk::Entry

=item Gtk::EventBox

=item Gtk::FileSelection

=item Gtk::Fixed

=item Gtk::FontSelection

=item Gtk::FontSelectionDialog

=item Gtk::Frame

=item Gtk::GammaCurve

=item Gtk::Gdk

=item Gtk::Gdk::Atom

=item Gtk::Gdk::Bitmap

=item Gtk::Gdk::Color

=item Gtk::Gdk::ColorContext

=item Gtk::Gdk::Colormap

=item Gtk::Gdk::Cursor

=item Gtk::Gdk::DragAction

=item Gtk::Gdk::DragContext

=item Gtk::Gdk::DragProtocol

=item Gtk::Gdk::Event

=item Gtk::Gdk::EventMask

=item Gtk::Gdk::ExtensionMode

=item Gtk::Gdk::FillRule

=item Gtk::Gdk::Font

=item Gtk::Gdk::Geometry

=item Gtk::Gdk::GC

=item Gtk::Gdk::Image

=item Gtk::Gdk::InputCondition

=item Gtk::Gdk::ModifierType

=item Gtk::Gdk::Pixmap

=item Gtk::Gdk::Property

=item Gtk::Gdk::PropMode

=item Gtk::Gdk::Rectangle

=item Gtk::Gdk::Region

=item Gtk::Gdk::Rgb

=item Gtk::Gdk::Rgb::Cmap

=item Gtk::Gdk::Rgb::Dither

=item Gtk::Gdk::Selection

=item Gtk::Gdk::Visual

=item Gtk::Gdk::Window

=item Gtk::Gdk::WindowHints

=item Gtk::Gdk::WMDecoration

=item Gtk::Gdk::WMFunction

=item Gtk::HBox

=item Gtk::HButtonBox

=item Gtk::HPaned

=item Gtk::HRuler

=item Gtk::HScale

=item Gtk::HScrollbar

=item Gtk::HSeparator

=item Gtk::HandleBox

=item Gtk::Image

=item Gtk::InputDialog

=item Gtk::Invisible

=item Gtk::Item

=item Gtk::ItemFactory

=item Gtk::ItemFactory::Entry

=item Gtk::Justification

=item Gtk::Label

=item Gtk::Layout

=item Gtk::List

=item Gtk::ListItem

=item Gtk::Menu

=item Gtk::MenuBar

=item Gtk::MenuFactory

=item Gtk::MenuFactoryType

=item Gtk::MenuItem

=item Gtk::MenuShell

=item Gtk::MetricType

=item Gtk::Misc

=item Gtk::Notebook

=item Gtk::NotebookPage

=item Gtk::Object

=item Gtk::OptionMenu

=item Gtk::Orientation

=item Gtk::Packer

=item Gtk::PackerChild

=item Gtk::PackerOptions

=item Gtk::Packtype

=item Gtk::Paned

=item Gtk::Pixmap

=item Gtk::Plug

=item Gtk::Preview

=item Gtk::PreviewType

=item Gtk::PositionType

=item Gtk::PolicyType

=item Gtk::Progress

=item Gtk::ProgressBar

=item Gtk::ProgressBarStyle

=item Gtk::ProgressBarOrientation

=item Gtk::RadioButton

=item Gtk::RadioMenuItem

=item Gtk::Range

=item Gtk::Rc

=item Gtk::RcStyle

=item Gtk::RcFlags

=item Gtk::ReliefStyle

=item Gtk::Requisition

=item Gtk::Ruler

=item Gtk::Scale

=item Gtk::ScrolledWindow

=item Gtk::ScrollType

=item Gtk::SelectionData

=item Gtk::SelectionMode

=item Gtk::ShadowType

=item Gtk::SideType

=item Gtk::Socket

=item Gtk::SpinButton

=item Gtk::SpinButtonUpdatePolicy

=item Gtk::StateType

=item Gtk::Statusbar

=item Gtk::Style

=item Gtk::SubmenuPlacement

=item Gtk::Table

=item Gtk::TargetList

=item Gtk::TearoffMenuItem

=item Gtk::Text

=item Gtk::TipsQuery

=item Gtk::ToggleButton

=item Gtk::Toolbar

=item Gtk::ToolbarChildType

=item Gtk::ToolbarSpaceStyle

=item Gtk::ToolbarStyle

=item Gtk::Tooltips

=item Gtk::Tree

=item Gtk::TreeItem

=item Gtk::TreeViewMode

=item Gtk::Type

=item Gtk::UpdateType

=item Gtk::VBox

=item Gtk::VButtonBox

=item Gtk::VPaned

=item Gtk::VRuler

=item Gtk::VScale

=item Gtk::VScrollbar

=item Gtk::Veparator

=item Gtk::Viewport

=item Gtk::Widget

=item Gtk::Window

=item Gtk::WindowType

=item Gtk::WindowPosition

=back