1Gtk3(3) User Contributed Perl Documentation Gtk3(3)
2
6 Gtk3 - Perl interface to the 3.x series of the gtk+ toolkit
7
9 use Gtk3 -init;
10 my $window = Gtk3::Window->new ('toplevel');
11 my $button = Gtk3::Button->new ('Quit');
12 $button->signal_connect (clicked => sub { Gtk3::main_quit });
13 $window->add ($button);
14 $window->show_all;
15 Gtk3::main;
16
18 Perl bindings to the 3.x series of the gtk+ toolkit. This module
19 allows you to write graphical user interfaces in a Perlish and object-
20 oriented way, freeing you from the casting and memory management in C,
21 yet remaining very close in spirit to original API.
22
24 The "Gtk3" module allows a Perl developer to use the gtk+ graphical
25 user interface library. Find out more about gtk+ at
26 <http://www.gtk.org>.
27 The gtk+ reference manual is also a handy companion when writing "Gtk3"
29 programs in Perl: <http://developer.gnome.org/gtk3/stable/>. The Perl
30 bindings follow the C API very closely, and the C reference
31 documentation should be considered the canonical source. The
32 principles underlying the mapping from C to Perl are explained in the
33 documentation of Glib::Object::Introspection, on which "Gtk3" is based.
34 Glib::Object::Introspection also comes with the "perli11ndoc" program
36 which displays the API reference documentation of all installed
37 libraries organized in accordance with these principles.
38 Wrapped libraries
40 "Gtk3" automatically sets up the following correspondence between C
41 libraries and Perl packages:
42 Library | Package
44 --------------+----------
45 Gtk-3.0 | Gtk3
46 Gdk-3.0 | Gtk3::Gdk
47 GdkPixbuf-2.0 | Gtk3::Gdk
48 GdkPixdata-2.0| Gtk3::Gdk
49 Pango-1.0 | Pango
50 Import arguments
52 When importing "Gtk3", you can pass "-init" as in "use Gtk3 -init;" to
53 have "Gtk3::init" automatically called. You can also pass a version
54 number to require a certain version of "Gtk3".
55 Customizations and overrides
57 In order to make things more Perlish or to make porting from "Gtk2" to
58 "Gtk3" easier, "Gtk3" customizes the API generated by
59 Glib::Object::Introspection in a few spots:
60 • The array ref normally returned by the following functions is
62 flattened into a list:
63 Gtk3::ActionGroup::list_actions
65 Gtk3::Builder::get_objects
66 Gtk3::CellLayout::get_cells
67 Gtk3::Container::get_children
68 Gtk3::SizeGroup::get_widgets
69 Gtk3::TreePath::get_indices
70 Gtk3::TreeView::get_columns
71 Gtk3::UIManager::get_action_groups
72 Gtk3::UIManager::get_toplevels
73 Gtk3::Window::list_toplevels
74 Gtk3::stock_list_ids
75 Gtk3::Gdk::Pixbuf::get_formats
76 • The following functions normally return a boolean and additional
77 out arguments, where the boolean indicates whether the out
78 arguments are valid. They are altered such that when the boolean
79 is true, only the additional out arguments are returned, and when
80 the boolean is false, an empty list is returned.
81 Gtk3::TextBuffer::get_selection_bounds
83 Gtk3::TreeModel::get_iter
84 Gtk3::TreeModel::get_iter_first
85 Gtk3::TreeModel::get_iter_from_string
86 Gtk3::TreeModel::iter_children
87 Gtk3::TreeModel::iter_nth_child
88 Gtk3::TreeModel::iter_parent
89 Gtk3::TreeModelFilter::convert_child_iter_to_iter
90 Gtk3::TreeModelSort::convert_child_iter_to_iter
91 Gtk3::TreeSelection::get_selected
92 Gtk3::TreeView::get_dest_row_at_pos
93 Gtk3::TreeView::get_path_at_pos
94 Gtk3::TreeView::get_tooltip_context
95 Gtk3::TreeView::get_visible_range
96 Gtk3::TreeViewColumn::cell_get_position
97 Gtk3::stock_lookup
98 Gtk3::Gdk::Event::get_axis
99 Gtk3::Gdk::Event::get_button
100 Gtk3::Gdk::Event::get_click_count
101 Gtk3::Gdk::Event::get_coords
102 Gtk3::Gdk::Event::get_keycode
103 Gtk3::Gdk::Event::get_keyval
104 Gtk3::Gdk::Event::get_scroll_direction
105 Gtk3::Gdk::Event::get_scroll_deltas
106 Gtk3::Gdk::Event::get_state
107 Gtk3::Gdk::Event::get_root_coords
108 Gtk3::Gdk::Window::get_origin
109 • Values of type Gtk3::ResponseType are converted to and from nick
110 names if possible, while still allowing raw IDs, in the following
111 places:
112 - For Gtk3::Dialog and Gtk3::InfoBar: the signal "response" as well
114 as the methods "add_action_widget", "add_button", "add_buttons",
115 "response", "set_default_response" and "set_response_sensitive".
116 - For Gtk3::Dialog: the methods "get_response_for_widget",
117 "get_widget_for_response", "run" and
118 "set_alternative_button_order".
119 • Values of type Gtk3::IconSize are converted to and from nick names
120 if possible, while still allowing raw IDs, in the following places:
121 - Gtk3::Image: the constructors new_from_stock, new_from_icon_set,
123 new_from_icon_name and new_from_gicon, the getters get_stock,
124 get_icon_set, get_icon_name and get_gicon and the setters
125 set_from_stock, set_from_icon_set, set_from_icon_name,
126 set_from_gicon.
127 - Gtk3::Widget: the method render_icon.
128 • The constants "Gtk3::EVENT_PROPAGATE" and "Gtk3::EVENT_STOP" can be
129 used in handlers for event signals like "key-press-event" to
130 indicate whether or not the event should continue propagating
131 through the widget hierarchy.
132 • The records corresponding to the various Gtk3::Gdk::Event types,
134 like "expose" or "key-release", are represented as objects blessed
135 into specific Perl packages, like "Gtk3::Gdk::EventExpose" or
136 "Gtk3::Gdk::EventKey", that all inherit from "Gtk3::Gdk::Event".
137 This allows you to seemlessly access type-specific fields as well
138 as common fields, as in "$event->window" or "$event->keyval".
139 • Gtk3::Gdk::Atom has overloads for the "==" and "!=" operators that
141 check for equality of the underlying atoms.
142 • For backwards compatibility, the functions "Gtk3::get_version_info"
144 and "Gtk3::GET_VERSION_INFO" are provided, and the functions
145 "Gtk3::CHECK_VERSION", "Gtk3::check_version", "Gtk3::init",
146 "Gtk3::init_check", "Gtk3::main", "Gtk3::main_level" and
147 "Gtk3::main_quit" can be called as class-static or as normal
148 functions: for example, "Gtk3->main_quit" and "Gtk3::main_quit" are
149 both supported. Additionally, "Gtk3::init" and "Gtk3::init_check"
150 automatically handle passing and updating @ARGV as appropriate.
151 • A Perl reimplementation of "Gtk3::show_about_dialog" is provided.
153 • Perl reimplementations of "Gtk3::ActionGroup::add_actions",
155 "add_radio_actions" and "add_toggle_actions" are provided.
156 • "Gtk3::Builder::add_objects_from_file" and
158 "add_objects_from_string" also accept a list of objects instead of
159 an array ref.
160 • "Gtk3::Builder::add_objects_from_string" and "add_from_string"
162 don't take length arguments, as they are computed automatically.
163 • A Perl reimplementation of "Gtk3::Builder::connect_signals" is
165 provided.
166 • The default "new" constructors of Gtk3::Button, Gtk3::CheckButton,
168 Gtk3::ColorButton, Gtk3::FontButton and Gtk3::ToggleButton reroute
169 to "new_with_mnemonic" if given an extra argument.
170 • The default "new" constructor of Gtk3::CheckMenuItem reroutes to
172 "new_with_mnemonic" if given an extra argument.
173 • The "length" argument of "Gtk3::Clipboard::set_text" is optional.
175 • Perl reimplementations of "Gtk3::Container::add_with_properties",
177 "Gtk3::Container::child_get" and "Gtk3::Container::child_set" are
178 provided.
179 • "Gtk3::Container::find_child_property" and
181 "Gtk3::Container::list_child_properties" are forwarded to the
182 corresponding functions in "Gtk3::ContainerClass".
183 • "Gtk3::Container::get_focus_chain" returns a list of widgets, or an
185 empty list.
186 • "Gtk3::Container::set_focus_chain" also accepts a list of widgets.
188 • "Gtk3::CssProvider::load_from_data" also accepts a string.
190 • For Gtk3::Dialog and Gtk3::InfoBar, a Perl implementation of
192 "add_buttons" is provided.
193 • "Gtk3::Dialog::new" can optionally be called as "Gtk3::Dialog->new
195 (TITLE, PARENT, FLAGS, ...)" where "..." is a series of button text
196 and response id pairs.
197 • A Perl implementation of "Gtk3::Dialog::new_with_buttons" is
199 provided.
200 • The "length" argument of "Gtk3::Editable::insert_text" is optional.
202 • A Perl implementation of "Gtk3::FileChooserDialog::new" is
204 provided.
205 • "Gtk3::HBox::new" uses the defaults homogeneous = FALSE and spacing
207 = 5.
208 • The default "new" constructor of Gtk3::ImageMenuItem reroutes to
210 "new_with_mnemonic" if given an extra argument.
211 • "Gtk3::InfoBar::new" can optionally be called as
213 "Gtk3::InfoBar->new (...)" where "..." is a series of button text
214 and response id pairs.
215 • A Perl reimplementation of "Gtk3::InfoBar::new_with_buttons" is
217 provided.
218 • The default "new" constructor of Gtk3::LinkButton reroutes to
220 "new_with_label" if given an extra argument.
221 • "Gtk3::ListStore::new" also accepts a list of type names.
223 • Gtk3::ListStore has a "get" method that calls
225 "Gtk3::TreeModel::get" instead of "Glib::Object::get".
226 • "Gtk3::ListStore::insert_with_values" also accepts a list of
228 "column => value" pairs and reroutes to "insert_with_valuesv".
229 • "Gtk3::ListStore::set" also accepts a list of "column => value"
231 pairs.
232 • "Gtk3::Menu::popup" reroutes to "popup_for_device" for better
234 callback handling.
235 • "Gtk3::Menu::popup_for_device" allows the given menu position func
237 to return only x and y coordinates, defaulting "push_in" to FALSE.
238 • The default "new" constructor of Gtk3::MenuItem reroutes to
240 "new_with_mnemonic" if given an extra argument.
241 • A Perl reimplementation of "Gtk3::MessageDialog::new" is provided.
243 • A Perl reimplementation of "Gtk3::MessageDialog::new_with_markup"
245 is provided.
246 • A Perl reimplementation of
248 "Gtk3::MessageDialog::format_secondary_text" and
249 "Gtk3::MessageDialog::format_secondary_markup" is provided
250 • The group handling in the constructors and accessors of
252 Gtk3::RadioAction, Gtk3::RadioButton, Gtk3::RadioMenuItem and
253 Gtk3::RadioToolButton is amended to work correctly when given array
254 refs of group members or single group members.
255 • Perl reimplementations of "Gtk3::RecentChooserDialog::new" and
257 "new_for_manager" are provided.
258 • Redirects are provided from "Gtk3::Stock::[function]" to
260 "Gtk3::stock_[function]" for "add", "add_static", "list_ids",
261 "lookup" and "set_translate_func".
262 • A Perl reimplementation of "Gtk3::StyleContext::get" is provided.
264 • An override for "Gtk3::TargetEntry::new" is provided that
266 automatically handles the conversion of the "flags" argument.
267 • A Perl reimplementation of "Gtk3::TextBuffer::create_tag" is
269 provided.
270 • The "length" arguments of "Gtk3::TextBuffer::insert",
272 "insert_at_cursor", "insert_interactive",
273 "insert_interactive_at_cursor", "insert_markup" and "set_text" are
274 optional.
275 • Perl reimplementations of "Gtk3::TextBuffer::insert_with_tags" and
277 "insert_with_tags_by_name" are provided which do not require a
278 "length" argument.
279 • A Perl reimplementation of "Gtk3::TreeModel::get" is provided.
281 • A redirect is added from "Gtk3::TreeModelFilter::new" to
283 <Gtk3::TreeModel::filter_new> so that Gtk3::TreeModelFilter objects
284 can be constructed normally.
285 • Gtk3::TreeModelFilter has a "get" method that calls
287 "Gtk3::TreeModel::get" instead of "Glib::Object::get".
288 • Prior to gtk+ 3.24.14, a redirect is added from
290 "Gtk3::TreeModelSort::new_with_model" to
291 <Gtk3::TreeModel::sort_new_with_model> so that Gtk3::TreeModelSort
292 objects can be constructed normally.
293 • Gtk3::TreeModelSort has a "get" method that calls
295 "Gtk3::TreeModel::get" instead of "Glib::Object::get".
296 • "Gtk3::TreePath::new" redirects to "new_from_string" if an
298 additional argument is given.
299 • A Perl reimplementation of "Gtk3::TreePath::new_from_indices" is
301 provided.
302 • "Gtk3::TreeStore::new" also accepts a list of type names.
304 • Gtk3::TreeStore has a "get" method that calls
306 "Gtk3::TreeModel::get" instead of "Glib::Object::get".
307 • "Gtk3::TreeStore::insert_with_values" also accepts a list of
309 "column => value" pairs.
310 • "Gtk3::TreeStore::set" also accepts a list of "column => value"
312 pairs.
313 • "Gtk3::TreeView::new" redirects to "new_with_model" if an
315 additional argument is given.
316 • A Perl reimplementation of
318 "Gtk3::TreeView::insert_column_with_attributes" is provided.
319 • A Perl reimplementation of
321 "Gtk3::TreeViewColumn::new_with_attributes" is provided.
322 • Perl reimplementations of "Gtk3::TreeViewColumn::set_attributes"
324 and "Gtk3::CellLayout::set_attributes" are provided.
325 • "Gtk3::UIManager::add_ui_from_string" takes no "length" argument.
327 • "Gtk3::VBox::new" uses the defaults homogeneous = FALSE and spacing
329 = 5.
330 • "Gtk3::Widget::add_events" and "Gtk3::Widget::set_events" also
332 accept strings, array references and "Gtk3::Gdk::EventMask" objects
333 for the "events" parameter.
334 • "Gtk3::Widget::get_events" returns a "Gtk3::Gdk::EventMask" object
336 that can also be compared to numeric values with "==" and ">=".
337 • "Gtk3::Widget::find_style_property" and
339 "Gtk3::Widget::list_style_properties" are forwarded to the
340 corresponding functions in "Gtk3::WidgetClass".
341 • A Perl reimplementation of "Gtk3::Widget::style_get" is provided.
343 • "Gtk3::Window::new" uses the default type = 'toplevel'.
345 • A constructor "Gtk3::Gdk::RGBA::new" is provided that can be called
347 as "Gtk3::Gdk::RGBA->new (r, g, b, a)".
348 • "Gtk3::Gdk::RGBA::parse" can be called as a function returning a
350 new instance ("$rgba = Gtk3::Gdk::RGBA::parse ($spec)") or as a
351 method ("$rgba->parse ($spec)").
352 • "Gtk3::Gdk::Window::new" optionally computes the "attr_mask"
354 automatically from the given "attr".
355 • "Gtk3::Gdk::Pixbuf::get_pixels" returns a byte string.
357 • "Gtk3::Gdk::Pixbuf::new_from_data" is reimplemented in terms of
359 "new_from_bytes" (with gdk-pixbuf >= 2.32) or "new_from_inline"
360 (with gtk-pixbuf < 2.32) for correct memory management. No
361 "destroy_fn" and "destroy_fn_data" arguments are needed.
362 • "Gtk3::Gdk::Pixbuf::new_from_inline" does not take a "copy_pixels"
364 argument. It is always set to TRUE for correct memory management.
365 • "Gtk3::Gdk::Pixbuf::new_from_xpm_data" also accepts a list of XPM
367 lines.
368 • "Gtk3::Gdk::Pixbuf::save", "save_to_buffer" and "save_to_callback"
370 also accept "key => value" pairs and invoke the correct C function
371 as appropriate for the current gdk-pixbuf version.
372 • The "length" arguments of "Pango::Layout::set_text" and
374 "set_markup" are optional.
375 Perl compatibility
377 As of 5.20.0, perl does not automatically re-check the locale
378 environment for changes. If a function thus changes the locale behind
379 perl's back, problems might arise whenever numbers are formatted, for
380 example when checking versions. To ensure perl's assumption about the
381 locale are up-to-date, the functions "Gtk3::init", "init_check",
382 "init_with_args" and "parse_args" are amended to let perl know of any
383 changes.
384 Porting from Gtk2 to Gtk3
386 The majority of the API has not changed, so as a first approximation
387 you can run "s/Gtk2/Gtk3/" on your application. A big exception to
388 this rule is APIs that were deprecated in gtk+ 2.x -- these were all
389 removed from gtk+ 3.0 and thus from Gtk3. The migration guide at
390 <http://developer.gnome.org/gtk3/stable/migrating.html> describes what
391 to use instead. Apart from this, here is a list of some other
392 incompatible differences between Gtk2 and Gtk3:
393 • The call syntax for class-static methods is now always
395 "Gtk3::Stock::lookup" instead of "Gtk3::Stock->lookup".
396 • The %Gtk2::Gdk::Keysyms hash is gone; instead of
398 "Gtk2::Gdk::Keysyms{XYZ}", use "Gtk3::Gdk::KEY_XYZ".
399 • The Gtk2::Pango compatibility wrapper was not carried over; simply
401 use the namespace "Pango" everywhere. It gets set up automatically
402 when loading Gtk3.
403 • The types Gtk3::Allocation and Gtk3::Gdk::Rectangle are now aliases
405 for Cairo::RectangleInt, and as such they are represented as plain
406 hashes with keys 'width', 'height', 'x' and 'y'.
407 • Gtk3::Editable: Callbacks connected to the "insert-text" signal do
409 not have as many options anymore as they had in Gtk2. Changes to
410 arguments will not be propagated to the next signal handler, and
411 only the updated position can and must be returned.
412 • Gtk3::Menu: In gtk+ < 3.16, the position callback passed to popup()
414 does not receive x and y parameters.
415 • Gtk3::RadioAction: The constructor now follows the C API.
417 • Gtk3::TreeModel: iter_next() is now a method that is modifying the
419 iter directly, instead of returning a new one. rows_reordered()
420 and the "rows-reordered" signal are currently unusable.
421 • Gtk3::TreeSelection: get_selected_rows() now returns two values: an
423 array ref containing the selected paths, and the model.
424 get_user_data() is not available currently.
425 • Gtk3::TreeSortable: get_sort_column_id() has an additional boolean
427 return value.
428 • Gtk3::TreeStore, Gtk3::ListStore: reorder() is currently unusable.
430 • Gtk3::Widget: grab_add() and grab_remove() are methods now:
432 "$widget->grab_add", "$widget->grab_remove".
433 • Gtk3::Gdk::Atom: The constructor new() is not provided anymore, and
435 the class function intern() must now be called as
436 "Gtk3::Gdk::Atom::intern (name, only_if_exists)".
437 • Implementations of Gtk3::TreeModel: Gtk3::TreeIter now has a
439 constructor called new() expecting "key => value" pairs;
440 new_from_arrayref() does not exist anymore. To access the contents
441 of Gtk3::TreeIter, use stamp(), user_data(), user_data2() and
442 user_data3(); to_arrayref() does not exist anymore. GET_ITER(),
443 ITER_CHILDREN(), ITER_NTH_CHILD() and ITER_PARENT() must return an
444 additional boolean value. ITER_NEXT() must modify the iter and
445 return a boolean rather than return a new iter. GET_VALUE() must
446 return the value wrapped with
447 "Glib::Object::Introspection::GValueWrapper->new".
448 • Implementations of Gtk3::CellLayout: GET_CELLS() now needs to
450 return an array ref instead of a list.
451 Note also that Gtk3::CHECK_VERSION will always fail when passed 2.y.z,
453 so if you have any existing version checks in your code, you will most
454 likely need to remove them.
455
457 • To discuss Gtk3 and ask questions join gtk-perl-list@gnome.org at
458 <http://mail.gnome.org/mailman/listinfo/gtk-perl-list>.
459 • Also have a look at the gtk2-perl website and sourceforge project
461 page, <http://gtk2-perl.sourceforge.net>.
462 • Glib
464 • Glib::Object::Introspection
466
468 Torsten Schönfeld <kaffeetisch@gmx.de>
469
471 Copyright (C) 2011-2015 by Torsten Schoenfeld <kaffeetisch@gmx.de>
472 This library is free software; you can redistribute it and/or modify it
474 under the terms of the GNU Library General Public License as published
475 by the Free Software Foundation; either version 2.1 of the License, or
476 (at your option) any later version.
477perl v5.34.0 2021-07-22 Gtk3(3)