1GladeXML(3)           User Contributed Perl Documentation          GladeXML(3)
2
3
4

NAME

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

SYNOPSIS

9         # for a pure gtk+ glade project
10         use Gtk2 -init;
11         use Gtk2::GladeXML;
12         $gladexml = Gtk2::GladeXML->new('example.glade');
13         $gladexml->signal_autoconnect_from_package('main');
14         $quitbtn = $gladexml->get_widget('Quit');
15         Gtk2->main;
16
17         # for glade files using gnome widgets, you must initialize Gnome2
18         # before loading the glade file.
19         use Gnome2;
20         use Gtk2::GladeXML;
21         # this call also initializes gtk+ for us
22         Gnome2::Program->init ($appname, $version);
23         $gladexml = Gtk2::GladeXML->new('gnomeapp.glade');
24         Gtk2->main;
25

ABSTRACT

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

DESCRIPTION

32       Glade is a free user interface builder for GTK+ and GNOME.  After
33       designing a user interface with glade-2 the layout and configuration
34       are saved in an XML file.  libglade is a library which knows how to
35       build and hook up the user interface described in the Glade XML file at
36       application run time.
37
38       This extension module binds libglade to Perl so you can create and
39       manipulate user interfaces in Perl code in conjunction with Gtk2 and
40       even Gnome2.  Better yet you can load a file's contents into a PERL
41       scalar do a few magical regular expressions to customize things and the
42       load up the app. It doesn't get any easier.
43

FUNCTIONS

45       $gladexml = Gtk2::GladeXML->new(GLADE_FILE, [ROOT, DOMAIN])
46           Create a new GladeXML object by loading the data in GLADE_FILE.
47           ROOT is an optional parameter that specifies a point (widget node)
48           from which to start building.  DOMAIN is an optional parameter that
49           specifies the translation domain for the xml file.
50
51       $gladexml = Gtk2::GladeXML->new_from_buffer(BUFFER, [ROOT, DOMAIN])
52           Create a new GladeXML object from the scalar string contained in
53           BUFFER.  ROOT is an optional parameter that specifies a point (wid‐
54           get node) from which to start building.  DOMAIN is an optional
55           parameter that specifies the translation domain for the xml file.
56
57       $widget = $gladexml->get_widget(NAME)
58           Return the widget created by the XML file with NAME or undef if no
59           such name exists.
60
61       $gladexml->signal_autoconnect($callback[, $userdata])
62           Iterates over all signals and calls the given callback:
63
64              sub example_cb {
65                 my ($name, $widget, $signal, $signal_data, $connect, $after, $userdata) = @_;
66              }
67
68           The following two convenience methods use this to provide a more
69           convenient interface.
70
71       $gladexml->signal_autoconnect_from_package([PACKAGE or OBJECT])
72           Sets up the signal handling callbacks as specified in the glade XML
73           data.
74
75           The argument to this method can be a Perl package name or an
76           object.  If a package name is used, each handler named in the Glade
77           XML data will be called as a subroutine in the named package.  If
78           an object is supplied each handler will be called as a method of
79           the object.  If no argument is supplied, the name of the calling
80           package will be used.  A user data argument cannot be supplied how‐
81           ever this is seldom necessary when an object is used.
82
83           The names of the subroutines or methods must exactly match the han‐
84           dler name in the XML data.  It is worth noting that callbacks you
85           get for free in c such as gtk_main_quit will not exist in perl and
86           must always be defined, for example:
87
88             sub gtk_main_quit
89             {
90                   Gtk2->main_quit;
91             }
92
93           Otherwise behavior should be exactly as expected with the use of
94           libglade from a C application.
95
96       $gladexml->signal_autoconnect_all (name => handler, ...)
97           Iterates over all named signals and tries to connect them to the
98           handlers specified as arguments (handlers not given as argument are
99           being ignored). This is very handy when implementing your own wid‐
100           gets, where you can't use global callbacks.
101
102       $widget = Gtk2::Glade->set_custom_handler ($callback[, $userdata])
103           This method tells Gtk2::GladeXML how to create handlers for custom
104           widgets.
105
106           You can specify a "custom" widget in a glade file, which allows you
107           to include in your interface widgets that Glade itself doesn't know
108           how to create.  To tell libglade how to instantiate such widgets,
109           you specify a "custom widget handler", a function which returns a
110           Gtk2:Widget object for that custom widget.  This handler needs to
111           be installed sometime before the instantiation of your
112           Gtk2::GladeXML object, by calling "set_custom_handler".
113
114               my $widget = Gtk2::Glade->set_custom_handler( \&my_handler );
115               my $gladexml = Gtk2::GladeXML->new( 'MyApp.glade' );
116
117           The prototype for the custom handler is:
118
119               sub my_handler {
120                   my ($xml,       # The Gtk2::GladeXML object
121                       # the remaining arguments are as specified in the glade file:
122                       $func_name, # The function name
123                       $name,      # the name of the widget to be created
124                       $str1,      # the string1 property
125                       $str2,      # the string2 property
126                       $int1,      # the int1 property
127                       $int2,      # the int2 property
128                       $userdata   # the data passed to set_custom_handler
129                      ) = @_;
130                   ...
131                   return $widget; # a new Gtk2::Widget; you must call ->show on it.
132               }
133

FAQ

135       Where is the option to generate Perl source in Glade?
136           Glade itself only creates the XML description, and relies on extra
137           converter programs to write source code; only a few converters are
138           widely popular.
139
140           In general, however, you don't want to generate source code for a
141           variety of reasons, mostly to do with maintainability.  This mes‐
142           sage on the glade-devel list explains it best:
143
144           http://lists.ximian.com/archives/public/glade-devel/2003-Febru
145           ary/000015.html
146
147       Why does my program crash on startup?
148           Does your glade file use Gnome widgets?  If so, you must initialize
149           Gnome manually; libglade can knows how to create gnome widgets, but
150           can't know how you want to initialize the app.  This is usually
151           sufficient:
152
153             use Gnome2;
154             Gnome2::Program->init ($app_name, $version_string);
155
156           Libglade's API reference mentions this: http://devel
157           oper.gnome.org/doc/API/2.0/libglade/libglade-modules.html
158

SEE ALSO

160       perl(1), Glib(3pm), Gtk2(3pm)
161
162       The Libglade Reference Manual at <http://devel
163       oper.gnome.org/doc/API/2.0/libglade/>
164
165       An introductory article that originally appeared in The Perl Review:
166       <http://live.gnome.org/GTK2-Perl/GladeXML/Tutorial>
167

AUTHOR

169       Ross McFarland <rwmcfa1 at neces dot com>, Marc Lehmann <pcg@goof.com>,
170       muppet <scott at asofyet dot org>.  Bruce Alderson provided several
171       examples.  Grant McClean <grant at mclean dot net dot nz> and Marco
172       Antonio Manzo <amnesiac at perl dot org dot mx> contributed documenta‐
173       tion.
174
176       Copyright 2003-2006 by the gtk2-perl team.
177
178       This library is free software; you can redistribute it and/or modify it
179       under the terms of the GNU Library General Public License as published
180       by the Free Software Foundation; either version 2 of the License, or
181       (at your option) any later version.
182
183       This library is distributed in the hope that it will be useful, but
184       WITHOUT ANY WARRANTY; without even the implied warranty of MER‐
185       CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library
186       General Public License for more details.
187
188       You should have received a copy of the GNU Library General Public
189       License along with this library; if not, write to the Free Software
190       Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307
191       USA.
192
193
194
195perl v5.8.8                       2006-09-04                       GladeXML(3)
Impressum