Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
GladeXML(3)	      User Contributed Perl Documentation	   GladeXML(3)

NAME
       Gtk2::GladeXML -	Create user interfaces directly	from Glade XML files.

SYNOPSIS
	 # for a pure gtk+ glade project
	 use Gtk2 -init;
	 use Gtk2::GladeXML;
	 $gladexml = Gtk2::GladeXML->new('example.glade');
	 $gladexml->signal_autoconnect_from_package('main');
	 $quitbtn = $gladexml->get_widget('Quit');
	 Gtk2->main;

	 # for glade files using gnome widgets,	you must initialize Gnome2
	 # before loading the glade file.
	 use Gnome2;
	 use Gtk2::GladeXML;
	 # this	call also initializes gtk+ for us
	 Gnome2::Program->init ($appname, $version);
	 $gladexml = Gtk2::GladeXML->new('gnomeapp.glade');
	 Gtk2->main;

ABSTRACT
       Gtk2::GladeXML allows Perl programmers to use libglade, a C library
       which generates graphical user interfaces directly from the XML output
       of the Glade user interface designer.

DESCRIPTION
       Glade is	a free user interface builder for GTK+ and GNOME.  After
       designing a user	interface with glade-2 the layout and configuration
       are saved in an XML file.  libglade is a	library	which knows how	to
       build and hook up the user interface described in the Glade XML file at
       application run time.

       This extension module binds libglade to Perl so you can create and
       manipulate user interfaces in Perl code in conjunction with Gtk2	and
       even Gnome2.  Better yet	you can	load a file's contents into a PERL
       scalar do a few magical regular expressions to customize	things and the
       load up the app.	It doesn't get any easier.

FUNCTIONS
       $gladexml = Gtk2::GladeXML->new(GLADE_FILE, [ROOT, DOMAIN])
	   Create a new	GladeXML object	by loading the data in GLADE_FILE.
	   ROOT	is an optional parameter that specifies	a point	(widget	node)
	   from	which to start building.  DOMAIN is an optional	parameter that
	   specifies the translation domain for	the xml	file.

       $gladexml = Gtk2::GladeXML->new_from_buffer(BUFFER, [ROOT, DOMAIN])
	   Create a new	GladeXML object	from the scalar	string contained in
	   BUFFER.  ROOT is an optional	parameter that specifies a point
	   (widget node) from which to start building.	DOMAIN is an optional
	   parameter that specifies the	translation domain for the xml file.

       $widget = $gladexml->get_widget(NAME)
	   Return the widget created by	the XML	file with NAME or undef	if no
	   such	name exists.

       $gladexml->signal_autoconnect($callback[, $userdata])
	   Iterates over all signals and calls the given callback:

	      sub example_cb {
		 my ($name, $widget, $signal, $signal_data, $connect, $after, $userdata) = @_;
	      }

	   The following two convenience methods use this to provide a more
	   convenient interface.

       $gladexml->signal_autoconnect_from_package([PACKAGE or OBJECT])
	   Sets	up the signal handling callbacks as specified in the glade XML
	   data.

	   The argument	to this	method can be a	Perl package name or an
	   object.  If a package name is used, each handler named in the Glade
	   XML data will be called as a	subroutine in the named	package.  If
	   an object is	supplied each handler will be called as	a method of
	   the object.	If no argument is supplied, the	name of	the calling
	   package will	be used.  A user data argument cannot be supplied
	   however this	is seldom necessary when an object is used.

	   The names of	the subroutines	or methods must	exactly	match the
	   handler name	in the XML data.  It is	worth noting that callbacks
	   you get for free in c such as gtk_main_quit will not	exist in perl
	   and must always be defined, for example:

	     sub gtk_main_quit
	     {
		   Gtk2->main_quit;
	     }

	   Otherwise behavior should be	exactly	as expected with the use of
	   libglade from a C application.

       $gladexml->signal_autoconnect_all (name => handler, ...)
	   Iterates over all named signals and tries to	connect	them to	the
	   handlers specified as arguments (handlers not given as argument are
	   being ignored). This	is very	handy when implementing	your own
	   widgets, where you can't use	global callbacks.

       $widget = Gtk2::Glade->set_custom_handler ($callback[, $userdata])
	   This	method tells Gtk2::GladeXML how	to create handlers for custom
	   widgets.

	   You can specify a "custom" widget in	a glade	file, which allows you
	   to include in your interface	widgets	that Glade itself doesn't know
	   how to create.  To tell libglade how	to instantiate such widgets,
	   you specify a "custom widget	handler", a function which returns a
	   Gtk2:Widget object for that custom widget.  This handler needs to
	   be installed	sometime before	the instantiation of your
	   Gtk2::GladeXML object, by calling "set_custom_handler".

	       my $widget = Gtk2::Glade->set_custom_handler( \&my_handler );
	       my $gladexml = Gtk2::GladeXML->new( 'MyApp.glade' );

	   The prototype for the custom	handler	is:

	       sub my_handler {
		   my ($xml,	   # The Gtk2::GladeXML	object
		       # the remaining arguments are as	specified in the glade file:
		       $func_name, # The function name
		       $name,	   # the name of the widget to be created
		       $str1,	   # the string1 property
		       $str2,	   # the string2 property
		       $int1,	   # the int1 property
		       $int2,	   # the int2 property
		       $userdata   # the data passed to	set_custom_handler
		      )	= @_;
		   ...
		   return $widget; # a new Gtk2::Widget; you must call ->show on it.
	       }

FAQ
       Where is	the option to generate Perl source in Glade?
	   Glade itself	only creates the XML description, and relies on	extra
	   converter programs to write source code; only a few converters are
	   widely popular.

	   In general, however,	you don't want to generate source code for a
	   variety of reasons, mostly to do with maintainability.  This
	   message on the glade-devel list explains it best:

	   http://lists.ximian.com/archives/public/glade-devel/2003-February/000015.html

       Why does	my program crash on startup?
	   Does	your glade file	use Gnome widgets?  If so, you must initialize
	   Gnome manually; libglade can	knows how to create gnome widgets, but
	   can't know how you want to initialize the app.  This	is usually
	   sufficient:

	     use Gnome2;
	     Gnome2::Program->init ($app_name, $version_string);

	   Libglade's API reference mentions this:
	   http://developer.gnome.org/doc/API/2.0/libglade/libglade-modules.html

SEE ALSO
       perl(1),	Glib(3pm), Gtk2(3pm)

       The Libglade Reference Manual at
       <http://developer.gnome.org/doc/API/2.0/libglade/>

       An introductory article that originally appeared	in The Perl Review:
       <http://live.gnome.org/GTK2-Perl/GladeXML/Tutorial>

AUTHOR
       Ross McFarland <rwmcfa1 at neces	dot com>, Marc Lehmann <pcg@goof.com>,
       muppet <scott at	asofyet	dot org>.  Bruce Alderson provided several
       examples.  Grant	McClean	<grant at mclean dot net dot nz> and Marco
       Antonio Manzo <amnesiac at perl dot org dot mx> contributed
       documentation.

COPYRIGHT AND LICENSE
       Copyright 2003-2006 by the gtk2-perl team.

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

       This library 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
       Library General Public License for more details.

       You should have received	a copy of the GNU Library General Public
       License along with this library;	if not,	write to the Free Software
       Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307
       USA.

perl v5.24.1			  2008-09-07			   GladeXML(3)

NAME | SYNOPSIS | ABSTRACT | DESCRIPTION | FUNCTIONS | FAQ | SEE ALSO | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Gtk2::GladeXML&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help