home *** CD-ROM | disk | FTP | other *** search
/ Clickx 115 / Clickx 115.iso / software / tools / windows / tails-i386-0.16.iso / live / filesystem.squashfs / usr / lib / perl5 / Gtk2.pm < prev    next >
Encoding:
Perl POD Document  |  2012-01-20  |  12.9 KB  |  432 lines

  1. #
  2. # Copyright (C) 2003-2012 by the gtk2-perl team (see the file AUTHORS for
  3. # the full list)
  4. #
  5. # This library is free software; you can redistribute it and/or modify it under
  6. # the terms of the GNU Library General Public License as published by the Free
  7. # Software Foundation; either version 2.1 of the License, or (at your option)
  8. # any later version.
  9. #
  10. # This library is distributed in the hope that it will be useful, but WITHOUT
  11. # ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
  12. # FOR A PARTICULAR PURPOSE.  See the GNU Library General Public License for
  13. # more details.
  14. #
  15. # You should have received a copy of the GNU Library General Public License
  16. # along with this library; if not, write to the Free Software Foundation, Inc.,
  17. # 59 Temple Place - Suite 330, Boston, MA  02111-1307  USA.
  18. #
  19. # $Id$
  20. #
  21.  
  22. package Gtk2;
  23.  
  24. # Gtk uses unicode strings; thus we require perl>=5.8.x,
  25. # which is unicode internally.
  26. use 5.008;
  27. use strict;
  28. use warnings;
  29.  
  30. use Glib;
  31. use Pango;
  32.  
  33. # Backwards compatibility: create Gtk2::Pango aliases for everything in Pango
  34. # that was originally in Gtk2::Pango.
  35. {
  36.   no strict 'refs';
  37.   my @pango_keys = qw(
  38.     AttrBackground:: AttrColor:: AttrFallback:: AttrFamily:: AttrFontDesc::
  39.     AttrForeground:: AttrGravity:: AttrGravityHint:: Attribute:: AttrInt::
  40.     AttrIterator:: AttrLanguage:: AttrLetterSpacing:: AttrList:: AttrRise::
  41.     AttrScale:: AttrShape:: AttrSize:: AttrStretch:: AttrStrikethrough::
  42.     AttrStrikethroughColor:: AttrString:: AttrStyle:: AttrUnderline::
  43.     AttrUnderlineColor:: AttrVariant:: AttrWeight:: Cairo:: Color:: Context::
  44.     Font:: FontDescription:: FontFace:: FontFamily:: FontMap:: FontMask::
  45.     FontMetrics:: Fontset:: GlyphString:: Gravity:: Language:: Layout::
  46.     LayoutIter:: LayoutLine:: Matrix:: Renderer:: Script:: ScriptIter::
  47.     TabArray::
  48.  
  49.     extents_to_pixels find_base_dir parse_markup pixels scale scale_large
  50.     scale_medium scale_small scale_x_large scale_x_small scale_xx_large
  51.     scale_xx_small units_from_double units_to_double
  52.  
  53.     PANGO_PIXELS
  54.  
  55.     CHECK_VERSION GET_VERSION_INFO VERSION
  56.  
  57.     ISA
  58.   );
  59.   foreach my $key (@pango_keys) {
  60.     # Avoid warnings about names that are used only once by checking for
  61.     # definedness here.
  62.     if (defined *{'Pango::' . $key}) {
  63.       *{'Gtk2::Pango::' . $key} = *{'Pango::' . $key};
  64.     }
  65.   }
  66. }
  67.  
  68. # if the gtk+ we've been compiled against is at 2.8.0 or newer or if pango is
  69. # at 1.10.0 or newer, we need to import the Cairo module for the cairo glue in
  70. # gtk+ and pango.
  71. eval "use Cairo;";
  72.  
  73. use Exporter;
  74. require DynaLoader;
  75.  
  76. our $VERSION = '1.242';
  77.  
  78. our @ISA = qw(DynaLoader Exporter);
  79.  
  80. # this is critical -- tell dynaloader to load the module so that its
  81. # symbols are available to all other modules.  without this, nobody
  82. # else can use important functions like gtk2perl_new_object!
  83. #
  84. # hrm.  win32 doesn't really use this, because we have to link the whole
  85. # thing at compile time to ensure all the symbols are defined.
  86. #
  87. # on darwin, at least with the particular 5.8.0 binary i'm using, perl
  88. # complains "Can't make loaded symbols global on this platform" when this
  89. # is set to 0x01, but goes on to work fine.  returning 0 here avoids the
  90. # warning and doesn't appear to break anything.
  91. sub dl_load_flags { $^O eq 'darwin' ? 0x00 : 0x01 }
  92.  
  93. # now load the XS code.
  94. Gtk2->bootstrap ($VERSION);
  95.  
  96. # %Gtk2::EXPORT_TAGS is filled from the constants-x.y files by the generated XS
  97. # code in build/constants.xs
  98. our @EXPORT_OK = map { @$_ } values %Gtk2::EXPORT_TAGS;
  99. $Gtk2::EXPORT_TAGS{all} = \@EXPORT_OK;
  100.  
  101. # Names "STOP" and "PROPAGATE" here are per the GtkWidget event signal
  102. # descriptions.  In some other flavours of signals the jargon is "handled"
  103. # instead of "stop".  "Handled" matches g_signal_accumulator_true_handled(),
  104. # though that function doesn't rate a mention in the Gtk docs.  There's
  105. # nothing fixed in the idea of "true means cease emission" (whether it's
  106. # called "stop" or "handled").  You can just as easily have false for cease
  107. # (the way the underlying GSignalAccumulator func in fact operates).  The
  108. # upshot being don't want to attempt to be too universal with the names
  109. # here; "EVENT" is meant to hint at the context or signal flavour they're
  110. # for use with.
  111. use constant {
  112.   EVENT_STOP      => 1,
  113.   EVENT_PROPAGATE => !1,
  114. };
  115.  
  116. sub import {
  117.     my $class = shift;
  118.  
  119.     # threads' init needs to be called before the main init and we don't
  120.     # want to force the order those options are passed to us so we need to
  121.     # cache the choices in booleans and (optionally) do them in the corect
  122.     # order afterwards
  123.     my $init = 0;
  124.     my $threads_init = 0;
  125.  
  126.     my @unknown_args = ($class);
  127.     foreach (@_) {
  128.         if (/^-?init$/) {
  129.             $init = 1;
  130.         } elsif (/-?threads-init$/) {
  131.             $threads_init = 1;
  132.         } else {
  133.             push @unknown_args, $_;
  134.         }
  135.     }
  136.  
  137.     Gtk2::Gdk::Threads->init if ($threads_init);
  138.     Gtk2->init if ($init);
  139.  
  140.     # call into Exporter for the unrecognized arguments; handles exporting
  141.     # and version checking
  142.     Gtk2->export_to_level (1, @unknown_args);
  143. }
  144.  
  145. # Preloaded methods go here.
  146.  
  147. package Gtk2::Gdk;
  148.  
  149. sub CHARS { 8 };
  150. sub SHORTS { 16 };
  151. sub LONGS { 32 };
  152.  
  153. sub USHORTS { 16 };
  154. sub ULONGS { 32 };
  155.  
  156. package Gtk2::Gdk::Atom;
  157.  
  158. use overload
  159.     '==' => \&Gtk2::Gdk::Atom::eq,
  160.     '!=' => \&Gtk2::Gdk::Atom::ne,
  161.     fallback => 1;
  162.  
  163. package Gtk2::CellLayout::DataFunc;
  164.  
  165. use overload
  166.     '&{}' => sub {
  167.                    my ($func) = @_;
  168.                    return sub { Gtk2::CellLayout::DataFunc::invoke($func, @_) }
  169.                  },
  170.     fallback => 1;
  171.  
  172. package Gtk2::TreeSortable::IterCompareFunc;
  173.  
  174. use overload
  175.     '&{}' => sub {
  176.                    my ($func) = @_;
  177.                    return sub { Gtk2::TreeSortable::IterCompareFunc::invoke($func, @_) };
  178.                  },
  179.     fallback => 1;
  180.  
  181. package Gtk2::TreeModelSort;
  182.  
  183. # We forgot to prepend Gtk2::TreeModel to @Gtk2::TreeModelSort::ISA.  So this
  184. # hack is here to make sure that $model_sort->get resolves to
  185. # Gtk2::TreeModel::get when appropriate and to Glib::Object::get otherwise, so
  186. # we stay backwards compatible.
  187. sub get {
  188.     if (@_ > 1 and ref $_[1] eq 'Gtk2::TreeIter') {
  189.         # called as $model->get ($iter, columns...);
  190.         return Gtk2::TreeModel::get (@_);
  191.     } else {
  192.         # called as $model->get (names...);
  193.         return Glib::Object::get (@_);
  194.     }
  195. }
  196.  
  197. package Gtk2::Builder;
  198.  
  199. sub _do_connect {
  200.   my ($object,
  201.       $signal_name,
  202.       $user_data,
  203.       $connect_object,
  204.       $flags,
  205.       $handler) = @_;
  206.  
  207.   my $func = ($flags & 'after') ? 'signal_connect_after' : 'signal_connect';
  208.  
  209.   # we get connect_object when we're supposed to call
  210.   # signal_connect_object, which ensures that the data (an object)
  211.   # lives as long as the signal is connected.  the bindings take
  212.   # care of that for us in all cases, so we only have signal_connect.
  213.   # if we get a connect_object, just use that instead of user_data.
  214.   $object->$func($signal_name => $handler,
  215.                  $connect_object ? $connect_object : $user_data);
  216. }
  217.  
  218. sub connect_signals {
  219.   my $builder = shift;
  220.   my $user_data = shift;
  221.  
  222.   # $builder->connect_signals ($user_data)
  223.   # $builder->connect_signals ($user_data, $package)
  224.   if ($#_ <= 0) {
  225.     my $package = shift;
  226.     $package = caller unless defined $package;
  227.  
  228.     $builder->connect_signals_full(sub {
  229.       my ($builder,
  230.           $object,
  231.           $signal_name,
  232.           $handler_name,
  233.           $connect_object,
  234.           $flags) = @_;
  235.  
  236.       no strict qw/refs/;
  237.  
  238.       my $handler = $handler_name;
  239.       if (ref $package) {
  240.         $handler = sub { $package->$handler_name(@_) };
  241.       } else {
  242.         if ($package && $handler !~ /::/) {
  243.           $handler = $package.'::'.$handler_name;
  244.         }
  245.       }
  246.  
  247.       _do_connect ($object, $signal_name, $user_data, $connect_object,
  248.                    $flags, $handler);
  249.     });
  250.   }
  251.  
  252.   # $builder->connect_signals ($user_data, %handlers)
  253.   else {
  254.     my %handlers = @_;
  255.  
  256.     $builder->connect_signals_full(sub {
  257.       my ($builder,
  258.           $object,
  259.           $signal_name,
  260.           $handler_name,
  261.           $connect_object,
  262.           $flags) = @_;
  263.  
  264.       return unless exists $handlers{$handler_name};
  265.  
  266.       _do_connect ($object, $signal_name, $user_data, $connect_object,
  267.                    $flags, $handlers{$handler_name});
  268.     });
  269.   }
  270. }
  271.  
  272. package Gtk2;
  273.  
  274. 1;
  275. __END__
  276. # documentation is a good thing.
  277.  
  278. =head1 NAME
  279.  
  280. Gtk2 - Perl interface to the 2.x series of the Gimp Toolkit library
  281.  
  282. =head1 SYNOPSIS
  283.  
  284.   use Gtk2 -init;
  285.   # Gtk2->init; works if you didn't use -init on use
  286.   my $window = Gtk2::Window->new ('toplevel');
  287.   my $button = Gtk2::Button->new ('Quit');
  288.   $button->signal_connect (clicked => sub { Gtk2->main_quit });
  289.   $window->add ($button);
  290.   $window->show_all;
  291.   Gtk2->main;
  292.  
  293. =head1 ABSTRACT
  294.  
  295. Perl bindings to the 2.x series of the Gtk+ widget set.  This module
  296. allows you to write graphical user interfaces in a Perlish and
  297. object-oriented way, freeing you from the casting and memory management
  298. in C, yet remaining very close in spirit to original API.
  299.  
  300. =head1 DESCRIPTION
  301.  
  302. The Gtk2 module allows a Perl developer to use the Gtk+ graphical user
  303. interface library.  Find out more about Gtk+ at http://www.gtk.org.
  304.  
  305. The GTK+ Reference Manual is also a handy companion when writing Gtk
  306. programs in any language.  http://developer.gnome.org/doc/API/2.0/gtk/
  307. The Perl bindings follow the C API very closely, and the C reference
  308. documentation should be considered the canonical source.
  309.  
  310. To discuss gtk2-perl, ask questions and flame/praise the authors,
  311. join gtk-perl-list@gnome.org at lists.gnome.org.
  312.  
  313. Also have a look at the gtk2-perl website and sourceforge project page,
  314. http://gtk2-perl.sourceforge.net
  315.  
  316. =head1 INITIALIZATION
  317.  
  318.   use Gtk2 qw/-init/;
  319.   use Gtk2 qw/-init -threads-init/;
  320.  
  321. =over
  322.  
  323. =item -init
  324.  
  325. Equivalent to Gtk2->init, called to initialize GLIB and GTK+. Just about every
  326. Gtk2-Perl script should do "use Gtk2 -init"; This initialization should take
  327. place before using any other Gtk2 functions in your GUI applications. It will
  328. initialize everything needed to operate the toolkit and parses some standard
  329. command line options. @ARGV is adjusted accordingly so your own code will never
  330. see those standard arguments.
  331.  
  332. =item -threads-init
  333.  
  334. Equivalent to Gtk2::Gdk::Threads->init, called to initialze/enable gdk's thread
  335. safety mechanisms so that gdk can be accessed from multiple threads when used
  336. in conjunction with Gtk2::Gdk::Threads->enter and Gtk2::Gdk::Threads->leave. If
  337. invoked as Gtk2::Gdk::Threads->init it should be done before Gtk2->init is
  338. called, if done by "use Gtk2 -init -threads-init" order does not matter.
  339.  
  340. =back
  341.  
  342. =head1 EXPORTS
  343.  
  344. Gtk2 exports nothing by default, but some constants are available upon request.
  345.  
  346. =over
  347.  
  348. =item Tag: constants
  349.  
  350.   GTK_PRIORITY_RESIZE
  351.  
  352.   GTK_PATH_PRIO_LOWEST
  353.   GTK_PATH_PRIO_GTK
  354.   GTK_PATH_PRIO_APPLICATION
  355.   GTK_PATH_PRIO_THEME
  356.   GTK_PATH_PRIO_RC
  357.   GTK_PATH_PRIO_HIGHEST
  358.  
  359.   GDK_PRIORITY_EVENTS
  360.   GDK_PRIORITY_REDRAW
  361.   GDK_CURRENT_TIME
  362.  
  363. =back
  364.  
  365. See L<Glib> for other standard priority levels.
  366.  
  367. =head1 SEE ALSO
  368.  
  369. L<perl>(1), L<Glib>(3pm), L<Pango>(3pm).
  370.  
  371. L<Gtk2::Gdk::Keysyms>(3pm) contains a hash of key codes, culled from
  372. gdk/gdkkeysyms.h
  373.  
  374. L<Gtk2::api>(3pm) describes how to map the C API into Perl, and some of the
  375. important differences in the Perl bindings.
  376.  
  377. L<Gtk2::Helper>(3pm) contains stuff that makes writing Gtk2 programs
  378. a little easier.
  379.  
  380. L<Gtk2::SimpleList>(3pm) makes the GtkListStore and GtkTreeModel a I<lot>
  381. easier to use.
  382.  
  383. L<Gtk2::Pango>(3pm) exports various little-used but important constants you
  384. may need to work with pango directly.
  385.  
  386. L<Gtk2::index>(3pm) lists the autogenerated api documentation pod files
  387. for Gtk2.
  388.  
  389. Gtk2 also provides code to make it relatively painless to create Perl
  390. wrappers for other GLib/Gtk-based libraries.  See L<Gtk2::CodeGen>,
  391. L<ExtUtils::PkgConfig>, and L<ExtUtils::Depends>.  If you're writing bindings,
  392. you'll probably also be interested in L<Gtk2::devel>, which is a supplement
  393. to L<Glib::devel> and L<Glib::xsapi>.  The Binding Howto, at
  394. http://gtk2-perl.sourceforge.net/doc/binding_howto.pod.html, ties it all
  395. together.
  396.  
  397. =head1 AUTHORS
  398.  
  399. =encoding utf8
  400.  
  401. The gtk2-perl team:
  402.  
  403.  muppet <scott at asofyet dot org>
  404.  Ross McFarland <rwmcfa1 at neces dot com>
  405.  Torsten Schoenfeld <kaffeetisch at web dot de>
  406.  Marc Lehmann <pcg at goof dot com>
  407.  G├╢ran Thyni <gthyni at kirra dot net>
  408.  J├╢rn Reder <joern at zyn dot de>
  409.  Chas Owens <alas at wilma dot widomaker dot com>
  410.  Guillaume Cottenceau <gc at mandrakesoft dot com>
  411.  
  412. =head1 COPYRIGHT AND LICENSE
  413.  
  414. Copyright 2003-2011 by the gtk2-perl team.
  415.  
  416. This library is free software; you can redistribute it and/or
  417. modify it under the terms of the GNU Library General Public
  418. License as published by the Free Software Foundation; either
  419. version 2 of the License, or (at your option) any later version.
  420.  
  421. This library is distributed in the hope that it will be useful,
  422. but WITHOUT ANY WARRANTY; without even the implied warranty of
  423. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  424. Library General Public License for more details.
  425.  
  426. You should have received a copy of the GNU Library General Public
  427. License along with this library; if not, write to the
  428. Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  429. Boston, MA  02111-1307  USA.
  430.  
  431. =cut
  432.