Kevin Ryde
and 1 contributors

NAME

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

SYNOPSIS

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

WIDGET HIERARCHY

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

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

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 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.

X Request Flushing

The Splash code tries to flush the outgoing X request queue at suitable times to ensure that a $splash->show() etc immediately shows the splash, or a $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.

FUNCTIONS

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

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

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

PROPERTIES

pixmap (Gtk2::Gdk::Pixmap object, default undef)
pixbuf (Gtk2::Gdk::Pixbuf object, default undef)
filename (string, default undef)

The image to display in the splash.

A filename is read with 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 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 Gtk2::Gdk::Pixbuf->new_from_file() used to read the file. Is that the right property type and the right way to do it?

The usual Gtk2::Window screen property determines the screen the splash window displays on (see "PROPERTIES" in Gtk2::Window).

IMPLEMENTATION NOTES

The splash is only a Gtk2::Gdk::Window with a background, but it's done as a widget since Gtk2::Gdk::Window doesn't subclass properly, as of Gtk circa 2.22 (see notes in 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 of the first. The current code tries to handle most cases by listening for any widget unmaps and any splashes closing. It doesn't pick up direct Gtk2::Gdk::Window hides (ie. not from a widget), though hopefully that's rare.

SEE ALSO

Gtk2::Window, gtk2-ex-splash(1)

HOME PAGE

http://user42.tuxfamily.org/gtk2-ex-splash/index.html

LICENSE

Copyright 2010, 2011, 2019 Kevin Ryde

Gtk2-Ex-Splash is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version.

Gtk2-Ex-Splash is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Gtk2-Ex-Splash. If not, see http://www.gnu.org/licenses/.