view release on metacpan or  search on metacpan

lib/Gtk2/Ex/Splash.pm  view on Meta::CPAN

=for stopwords Gtk2-Ex-Splash Gtk Ryde toplevel startup filename GdkPixbuf PNG JPEG Gtk2 toplevels cron subclassed unmaps

=head1 NAME

Gtk2::Ex::Splash -- toplevel splash widget

=head1 SYNOPSIS

 use Gtk2::Ex::Splash;
 my $splash = Gtk2::Ex::Splash->new (filename => '/my/image.png');
 $splash->show;
 # do some things
 $splash->destroy;

=head1 WIDGET HIERARCHY

C<Gtk2::Ex::Splash> is a subclass of C<Gtk2::Window> (the
usual toplevels), but don't rely on more than C<Gtk2::Widget> just yet.

    Gtk2::Widget
      Gtk2::Container
        Gtk2::Bin
          Gtk2::Window
            Gtk2::Ex::Splash

=head1 DESCRIPTION

This is a toplevel splash window centred on the screen.  It can be used as a
splash at program startup if some initializations might be slow, or a
general purpose flash or splash.

    +-------------------------------------+
    |                                     |
    |                                     |
    |           +----------+              |
    |           | Foo Prog |              |
    |           |  1.x **  |              |
    |           +----------+              |
    |                                     |
    |                                     |
    +-------------------------------------+

A splash at program startup can be annoying.  It's often better to get the
main window up and displayed early, and finish populating or opening an
initial document while the user has something to look at.  Though that's not
always easy.

A splash can also show something briefly without being too intrusive.  For
example a slide-show or cron job to flash a fun image every few minutes for
perhaps 1/2 second or so to relieve the monotony of work.  The supplied and
installed C<gtk2-ex-splash> program displays an image file that way.

The splash window is not interactive and doesn't take the keyboard focus
away from whatever the user is doing.  (Is that true of "focus follows
mouse" window manager style though?)  It does consume mouse button clicks
though.

The splash contents are shown as the window background, so it doesn't
require any redraws etc from the application and so continues to display
even if the application is busy doing other things.

=head2 X Request Flushing

The Splash code tries to flush the outgoing X request queue at suitable
times to ensure that a C<< $splash->show() >> etc immediately shows the
splash, or a C<< $splash->destroy() >> etc immediately removes it.  This
seems to work reasonably well, and hopefully there won't be any need for
special specific methods to show and hide.

=head1 FUNCTIONS

=over 4

=item C<< $splash = Gtk2::Ex::Splash->new (key=>value,...) >>

Create and return a new Splash widget.  Optional key/value pairs set initial
properties per C<< Glib::Object->new >>.

    my $splash = Gtk2::Ex::Splash->new (filename => '/my/dir/image.png');

=back

=head1 PROPERTIES

=over 4

=item C<pixmap> (C<Gtk2::Gdk::Pixmap> object, default C<undef>)

=item C<pixbuf> (C<Gtk2::Gdk::Pixbuf> object, default C<undef>)

=item C<filename> (string, default C<undef>)

The image to display in the splash.

A filename is read with C<Gtk2::Gdk::Pixbuf> so can be any file format
supported by GdkPixbuf.  PNG and JPEG are supported in all Gtk2 versions.

In the current code C<filename> is a scalar type, so it can hold a byte
string which is usual for a filename in Perl and is what's required by the
C<< Gtk2::Gdk::Pixbuf->new_from_file() >> used to read the file.  Is that
the right property type and the right way to do it?

=back

The usual C<Gtk2::Window> C<screen> property determines the screen the
splash window displays on (see L<Gtk2::Window/PROPERTIES>).

=head1 IMPLEMENTATION NOTES

The splash is only a C<Gtk2::Gdk::Window> with a background, but it's done
as a widget since C<Gtk2::Gdk::Window> doesn't subclass properly, as of Gtk
circa 2.22 (see notes in L<Gtk2::Gdk::Window>).

Something fishy happens when another window in the same program is on top of
the splash and is unmapped.  The revealed area of the splash should
automatically clear to its background, but doesn't.  Maybe something to do
with double buffering.

Windows from other client connections, ie. other programs, don't cause the
problem.  It only normally arises if a program shows a second splash on top