/ 
Gtk2-Ex-WidgetBits-17
/ Test::Weaken::Gtk2

NAME

Test::Weaken::Gtk2 -- Gtk2 widget helpers for Test::Weaken

SYNOPSIS

use Test::Weaken::Gtk2;

DESCRIPTION

This is a few functions to help Test::Weaken leaks on Gtk2 widgets etc. They can be used individually, or combined into larger application-specific callbacks.

This module doesn't load Gtk2. If Gtk2 is not loaded then the functions simply return empty, false, or do nothing, as appropriate. This module also doesn't load Test::Weaken, that's left to the test script.

FUNCTIONS

Contents Functions

@widgets = Test::Weaken::Gtk2::contents_container ($ref)

If $ref is a Gtk2::Container (or subclass) then return its widget children per $container->get_children. If $ref is not a container, or Gtk2 is not loaded, then return an empty list.

The children of a container are held in C structures and are not otherwise reached by the traversal leaks does.

@widgets = Test::Weaken::Gtk2::contents_submenu ($ref)

If $ref is a Gtk2::MenuItem (or subclass) and it has a submenu per $item->get_submenu then return that submenu. If $ref is not a MenuItem, or it doesn't have a submenu, or Gtk2 is not loaded, then return an empty list.

A submenu is held in the item's C structure and is not otherwise reached by the traversal leaks does.

Destructor Functions

Test::Weaken::Gtk2::destructor_destroy ($top)

Call $top->destroy, or if $top is an arrayref then call destroy on its first element. This can be used when a constructed widget or object requires an explicit destroy. For example,

my $leaks = leaks({
  constructor => sub { Gtk2::Window->new('toplevel') },
  destructor => \&Test::Weaken::Gtk2::destructor_destroy,
});

The arrayref case is designed for multiple widgets etc returned from a constructor, the first of which is a toplevel window or similar needing a destroy,

my $leaks = leaks({
  constructor => sub {
    my $toplevel = Gtk2::Window->new('toplevel');
    my $label = Gtk2::Label->new('Hello World');
    $toplevel->add($label);
    return [ $toplevel, $label ];
  },
  destructor => \&Test::Weaken::Gtk2::destructor_destroy,
});

All Gtk2::Objects support destroy but most don't need it for garbage collection. Gtk2::Window is the most common which does, another is a MenuItem with an AccelLabel not in a menu (see notes in Gtk2::MenuItem).

Test::Weaken::Gtk2::destructor_destroy_and_iterate ($top)

The same as destructor_destroy above, but in addition run Gtk2->main_iteration_do for queued main loop actions. A maximum iteration count protects against a runaway main loop.

This is good if some finalizations are only done in an idle handler, or perhaps under a timer which has expired by now. Queued X server events are run, but there's no wait for further events.

Ignore Functions

$bool = Test::Weaken::Gtk2::ignore_default_display ($ref)

Return true if $ref is the default Gtk2::Gdk::Display per Gtk2::Gdk::Display->get_default_display.

If Gtk2 is not loaded, or Gtk2->init has not been called, then there's no default display and this function returns false.

my $leaks = leaks({
  constructor => sub { make_something },
  ignore => \&Test::Weaken::Gtk2::ignore_default_display,
});

The default display is generally a permanent object, existing across a test, and on that basis should not be tracked for leaking. Usually the display object is not seen by leaks anyway, since it's only in the C structures of a widget or window. This function can be used if it might appear elsewhere, such as a Perl code sub-object.

EXPORTS

Nothing is exported by default, but the functions can be requested in usual Exporter style.

use Test::Weaken::Gtk2 'contents_container';

There's no :all tag since new functions are likely to be added in the future and an import of all runs the risk of name clashes with application functions etc.

SEE ALSO

Test::Weaken, Gtk2::Container, Gtk2::MenuItem, Gtk2::Object, Gtk2::Window, Gtk2::Gdk::Display

HOME PAGE

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

LICENSE

Copyright 2008, 2009, 2010 Kevin Ryde

Gtk2-Ex-WidgetBits 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-WidgetBits 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-WidgetBits. If not, see http://www.gnu.org/licenses/.