1Gtk2::Buildable(3) User Contributed Perl Documentation Gtk2::Buildable(3)
2
6 Gtk2::Buildable - Interface for objects that can be built by
7 Gtk2::Builder
8
10 package Thing;
11 use Gtk2;
12 use Glib::Object::Subclass
13 Glib::Object::,
14 # The important bit -- add this GInterface to our class
15 interfaces => [ Gtk2::Buildable:: ],
16 # Some signals and properties on the object...
18 signals => {
19 exploderize => {},
20 },
21 properties => [
22 Glib::ParamSpec->int ('force', 'Force',
23 'Explosive force, in megatons',
24 0, 1000000, 5, ['readable', 'writable']),
25 ],
26 ;
27 sub exploderize {
29 my $self = shift;
30 $self->signal_emit ('exploderize');
31 }
32 # We can accept all defaults for Buildable; see the description
34 # for details on custom XML.
35 package main;
37 use Gtk2 -init;
38 my $builder = Gtk2::Builder->new ();
39 $builder->add_from_string ('<interface>
40 <object class="Thing" id="thing1">
41 <property name="force">50</property>
42 <signal name="exploderize" handler="do_explode" />
43 </object>
44 </interface>');
45 $builder->connect_signals ();
46 my $thing = $builder->get_object ('thing1');
48 $thing->exploderize ();
50 sub do_explode {
52 my $thing = shift;
53 printf "boom * %d!\n", $thing->get ('force');
54 }
55 # This program prints "boom * 50!" on stdout.
57
59 Glib::Interface
60 +----Gtk2::Buildable
61
63 In order to allow construction from a Gtk2::Builder UI description
64 (http://library.gnome.org/devel/gtk/unstable/GtkBuilder.html#BUILDER-UI
65 <http://library.gnome.org/devel/gtk/unstable/GtkBuilder.html#BUILDER-
66 UI>), an object must implement the Gtk2::Buildable interface. The
67 interface includes methods for setting names and properties of objects,
68 parsing custom tags, and constructing child objects.
69 The Gtk2::Buildable interface is implemented by all widgets and many of
71 the non-widget objects that are provided by GTK+. The main user of
72 this interface is Gtk2::Builder, so there should be very little need
73 for applications to call any of the Gtk2::Buildable methods.
74 So, instead of focusing on how to call the methods of a
76 Gtk2::Buildable, this documentation deals with implementing a buildable
77 object.
78
80 Since Gtk2::Widget implements the Gtk2::Buildable interface, all
81 widgets get buildability gratis. If your widget requires no special
82 markup syntax to express its configuration, and all properties can be
83 handled through the standard mechanisms, you can simply add the name of
84 your perl-derived Glib::Object types to the "object" tag in the builder
85 UI description. You don't even have to do anything special in your
86 class definition. For example, objects of this class:
87 package My::Frame;
89 use Gtk2;
90 use Glib::Object::Subclass
91 Gtk2::Frame::,
92 properties => [
93 Glib::ParamSpec->int ('foo', ...),
94 ],
95 ;
96 ...
98 1;
100 could be expressed in a builder definition file like this:
102 <object class="My__Frame" id="myframe">
104 <property name="foo">15</property>
105 </object>
106 Notice that the '::' package separator has been replaced with '__' in
108 the "class" attribute; this is because the ':' character is not valid
109 for GType type names. The mapping from perl package names to GType
110 names should, in general, be as simple as transliterating the colons.
111
113 Glib::Object does not implement Gtk2::Buildable by itself, so to get a
114 builder UI file to create your custom Glib::Object subtypes, you'll
115 have add the Gtk2::Buildable interface to your class's interfaces list.
116 package My::Thing;
118 use Gtk2; # to get Gtk2::Buildable
119 use Glib::Object::Subclass
120 Glib::Object::,
121 interfaces => [ 'Gtk2::Buildable' ],
122 ...
123 ;
124 Again, if you have no special requirements, then that should be all you
126 need to do.
127
129 In some cases, you need to override the default Buildable behavior.
130 Maybe your objects already store their names, or you need some special
131 markup tags to express configuration. In these cases, add the
132 Gtk2::Buildable interface to your object declaration, and implement the
133 following methods as necessary.
134 Note that in the current implementation the custom tags code doesn't
136 chain up to any buildable interfaces in superclasses. This means for
137 instance if you implement Gtk2::Buildable on a new widget subclass then
138 you lose the <accelerator> and <accessibility> tags normally available
139 from Gtk2::Widget. This will likely change in the future, probably by
140 chaining up by default for unhandled tags, maybe with a way to ask
141 deliberately not to chain.
142 SET_NAME ($self, $name)
144 · $name (string)
145 This method should store $name in $self somehow. For example,
147 Gtk2::Widget maps this to the Gtk2::Widget's "name" property. If
148 you don't implement this method, the name will be attached in
149 object data down in C code. Implement this method if your object
150 has some notion of "name" and it makes sense to map the XML name
151 attribute to that.
152 string = GET_NAME ($self)
154 If you implement "SET_NAME", you need to implement this method to
155 retrieve that name.
156 ADD_CHILD ($self, $builder, $child, $type)
158 · $builder (Gtk2::Builder)
159 · $child (Glib::Object or undef)
161 · $type (string)
163 "ADD_CHILD" will be called to add $child to $self. $type can be
165 used to determine the kind of child. For example, Gtk2::Container
166 implements this method to add a child widget to the container, and
167 Gtk2::Notebook uses $type to distinguish between "page-label" and
168 normal children. The value of $type comes directly from the "type"
169 attribute of the XML "child" tag.
170 SET_BUILDABLE_PROPERTY ($self, $builder, $name, $value)
172 · $builder (Gtk2::Builder)
173 · $name (string)
175 · $value (scalar)
177 This will be called to set the object property $name on $self,
179 directly from the "property" XML tag. It is not normally necessary
180 to implement this method, as the fallback simply calls
181 "Glib::Object::set()". Gtk2::Window implements this method to
182 delay showing itself (i.e., setting the "visible" property) until
183 the whole interface is created. You can also use this to handle
184 properties that are not wired up through the Glib::Object property
185 system (though simply creating the property is easier).
186 parser or undef = CUSTOM_TAG_START ($self, $builder, $child, $tagname)
188 · $builder (Gtk2::Builder)
189 · $child (Glib::Object or undef)
191 · $tagname (string)
193 When Gtk2::Builder encounters an unknown tag while parsing the
195 definition of $self, it will call "CUSTOM_TAG_START" to give your
196 code a chance to do something with it. If $tagname was encountered
197 inside a "child" tag, the corresponding object will be passed in
198 $child; otherwise, $child will be "undef".
199 Your "CUSTOM_TAG_START" method should decide whether it supports
201 $tagname. If not, return "undef". If you do support it, return a
202 blessed perl object that implements three special methods to be
203 used to parse that tag. (These methods are defined by GLib's
204 GMarkupParser, which is a simple SAX-style setup.)
205 START_ELEMENT ($self, $context, $element_name, $attributes)
207 · $context (Gtk2::Buildable::ParseContext)
208 · $element_name (string)
210 · $attributes (hash reference) Dictionary of all attributes
212 of this tag.
213 TEXT ($self, $context, $text)
215 · $context (Gtk2::Buildable::ParseContext)
216 · $text (string) The text contained in the tag.
218 END_ELEMENT ($self, $context, $element_name)
220 · $context (Gtk2::Buildable::ParseContext)
221 · $element_name (string)
223 Any blessed perl object that implements these methods is valid as a
225 parser. (Ain't duck-typing great?) Gtk2::Builder will hang on to
226 this object until the parsing is complete, and will pass it to
227 "CUSTOM_TAG_END" and "CUSTOM_FINISHED", so you shouldn't have to
228 worry about its lifetime.
229 CUSTOM_TAG_END ($self, $builder, $child, $tagname, $parser)
231 · $builder (Gtk2::Builder)
232 · $child (Glib::Object or undef)
234 · $tagname (string)
236 · $parser (some perl object) as returned from "CUSTOM_TAG_START"
238 This method will be called (if it exists) when the close tag for
240 $tagname is encountered. $parser will be the object you returned
241 from "CUSTOM_TAG_START". $child is the same object-or-undef as
242 passed to "CUSTOM_TAG_START".
243 CUSTOM_FINISHED ($self, $builder, $child, $tagname, $parser)
245 · $builder (Gtk2::Builder)
246 · $child (Glib::Object or undef)
248 · $tagname (string)
250 · $parser (some perl object) as returned from "CUSTOM_TAG_START"
252 This method will be called (if it exists) when the parser finishes
254 dealing with the custom tag $tagname. $parser will be the object
255 you returned from "CUSTOM_TAG_START". $child is the same object-
256 or-undef as passed to "CUSTOM_TAG_START".
257 PARSER_FINISHED ($self, $builder)
259 · $builder (Gtk2::Builder)
260 If this method exists, it will be invoked when the builder finishes
262 parsing the description data. This method is handy if you need to
263 defer any object initialization until all of the rest of the input
264 is parsed, most likely because you need to refer to an object that
265 is declared after $self or you need to perform special cleanup
266 actions. It is not normally necessary to implement this method.
267 object or undef = GET_INTERNAL_CHILD ($self, $builder, $childname)
269 · $builder (Gtk2::Builder)
270 · $childname (string)
272 This will be called to fetch an internal child of $self. Implement
274 this method if your buildable has internal children that need to be
275 accessed from a UI definition. For example, Gtk2::Dialog
276 implements this to give access to its internal vbox child.
277
279 Gtk2, Glib::Interface,
280 http://library.gnome.org/devel/gtk/unstable/GtkBuilder.html#BUILDER-UI
281 <http://library.gnome.org/devel/gtk/unstable/GtkBuilder.html#BUILDER-
282 UI>, Gtk2::Buildable::ParseContext
283
285 Copyright (C) 2003-2008 by the gtk2-perl team.
286 This software is licensed under the LGPL. See Gtk2 for a full notice.
288perl v5.12.0 2010-05-02 Gtk2::Buildable(3)