view release on metacpan or  search on metacpan

lib/Fl/Window.pod  view on Meta::CPAN

class 'Fl::Window';
isa 'Fl::Group';
include 'FL/Fl_Window.H';

=pod

=head1 NAME

Fl::Window - Window Container for Widgets

=head1 Synopsis

    use Fl;
    my $window = Fl::Window->new(350, 500, 'Hello, World!');
    $window->show();
    Fl::run();

=head1 Description

This widget produces an actual window.

This can either be a main window, with a border and title and all the window
management controls, or a "subwindow" inside a window. This is controlled by
whether or not the window has a C<parent()>.

Once you create a window, you usually add children L<Fl::Widget>s to it by
using C<<$window->add($child)>> for each new widget. See Fl::Group for more
information on how to add and remove children.

There are several subclasses of Fl::Window that provide double-buffering,
overlay, menu, and OpenGL support.

The window's callback is done if the user tries to close a window using the
window manager and Fl::modal() is zero or equal to the window. Fl::Window has
a default callback that calls C<<Fl::Window->hide()>>.

=head1 Methods

In addition to inheriting from Fl::Group, this widget also supports the
following methods.

=head2 new(...)

The constructor creates a window of a given size and (optionally) position on
screen. The upstream API has a few poorly designed options:

    my $window_a = Fl::Window->new(300, 500);

This creates a window from the given size. You may also set the window's title
like this:

    my $window_b = Fl::Window->new(300, 500, 'Basic math');

If not provided, the window's title defaults to the filename of the current
running script.

You'll notice that the above examples don't define an on screen position. The
window manager is allowed to place the new window as it sees fit. To define a
position yourself, use either:

    my $window_c = Fl::Window->new(100, 150, 300, 500);

...or...

    my $window_d = Fl::Window->new(100, 150, 300, 500, 'Math is singular');

In these examples, the new window is placed 100 pixels from the left and 150
pixels down from the top of the display area.

=begin TODO

Ideally, we could also create windows with something like:

    my $window = Fl::Window->new(
        -position => [100, 100],
        -size     => [380, 400],
        -title    => 'NA'
    );

=end TODO

Again, the ($w, $h) form of the constructor creates a top-level window and
asks the window manager to position the window. The ($x, $y, $w, $h) form of
the constructor either creates a subwindow or a top-level window at the
specified location ($x, $y), subject to window manager configuration. If you
do not specify the position of the window, the window manager will pick a
place to show the window or allow the user to pick a location. Use
C<position($x, $y)> or C<hotspot()> before calling C<show()> to request a
position on the screen. See L<Fl::Window->resize()/resize(...)> for more
details on positioning windows.